@miraland-labs/conduit-bridge 0.16.5 → 0.16.7

package/dist/driver.js

@@ -99,6 +99,28 @@ export function buildAssignmentPrompt(context) {
     }
     if (changeScope?.length)
         lines.push("", `CHANGE SCOPE — only modify paths under\n${changeScope.map((item) => `- ${item}`).join("\n")}`);
+    const integrationObligations = spec.integration_obligations ?? [];
+    if (integrationObligations.length) {
+        lines.push("", "INTEGRATION OBLIGATIONS — finalize fails unless these hold");
+        for (const obligation of integrationObligations) {
+            if (obligation.kind !== "symbol_referenced_from")
+                continue;
+            const globs = obligation.from_globs?.length ? obligation.from_globs.join(", ") : "runtime entrypoints";
+            lines.push(`- symbol "${obligation.symbol}" must be referenced from ${globs}`);
+        }
+    }
+    if (context.normativeRefs?.length) {
+        lines.push("", "NORMATIVE REFERENCES — read-only contract files; your implementation must align. Do not edit anything under .conduit/normative/.");
+        for (const ref of context.normativeRefs) {
+            lines.push(`- ${ref.label} (${ref.repository} @ ${ref.revision.slice(0, 12)})`);
+            for (const path of ref.workspace_paths)
+                lines.push(`  - ${path}`);
+            const specRef = context.spec.normative_refs?.find((entry) => entry.label === ref.label);
+            if (specRef?.markers?.length) {
+                lines.push(`  - Required markers in changed files: ${specRef.markers.join(", ")}`);
+            }
+        }
+    }
     if (spec.repository?.base_commit)
         lines.push("", `The workspace is expected to be at or after base commit ${spec.repository.base_commit}.`);
     if (context.currentHead)
@@ -127,7 +149,9 @@ export function buildAssignmentPrompt(context) {
         mustCommit,
         mustOpenPr,
     });
-    lines.push("", "RULES", "- Stay within the change scope and boundaries.", ...(languageRule ? [languageRule] : []), ...classRules, "- Never merge, deploy, force-push, push to protected branches, or touch production.", `- Hard-denied commands (all drivers): ${deniedCommands.join("; ")}.`, "- Do not invent evidence. Report unknown when you could not verify a criterion.", 
+    lines.push("", "RULES", "- Stay within the change scope and boundaries.", ...(context.normativeRefs?.length
+        ? ["- When normative references are listed, treat them as the authoritative contract for any cross-repo API, signature, or protocol shape they describe."]
+        : []), ...(languageRule ? [languageRule] : []), ...classRules, "- Never merge, deploy, force-push, push to protected branches, or touch production.", `- Hard-denied commands (all drivers): ${deniedCommands.join("; ")}.`, "- Do not invent evidence. Report unknown when you could not verify a criterion.", 
     // The reviewer requests changes when "verification output is only summarized (not verbatim)"
     // (REVIEWER_PROMPT). Only the bounded-shell rule said to report real output, so publish_artifact
     // — the class the reviewer scrutinises hardest — summarized, and every criterion came back

package/dist/ensure-change-evidence.js

@@ -0,0 +1,55 @@
+import { changedPathsSince, diffStatSince } from "./git-witness.js";
+export function needsChangeEvidence(_report, spec, grants) {
+    if (!grants.includes("repo_write"))
+        return false;
+    return (spec.required_evidence ?? []).includes("change");
+}
+/** Reuse criteria the agent mapped onto change-kind evidence. */
+export function criteriaForChangeEvidence(report) {
+    const mapped = new Set();
+    for (const item of report.evidence) {
+        if (item.kind !== "change")
+            continue;
+        for (const criterion of item.acceptance_criteria ?? []) {
+            if (criterion)
+                mapped.add(criterion);
+        }
+    }
+    return [...mapped];
+}
+export async function ensureChangeEvidence(input) {
+    if (!needsChangeEvidence(input.report, input.spec, input.grants))
+        return input.report;
+    const paths = input.changedPaths
+        ?? (input.baseCommit ? await changedPathsSince(input.workspace, input.baseCommit) : null);
+    if (paths === null)
+        return input.report;
+    if (!paths.length) {
+        return {
+            ...input.report,
+            evidence: input.report.evidence.filter((item) => item.kind !== "change"),
+        };
+    }
+    const stat = input.baseCommit ? await diffStatSince(input.workspace, input.baseCommit) : null;
+    const baseLabel = input.baseCommit?.slice(0, 12) ?? "base";
+    const details = [
+        `git diff --name-only ${baseLabel}..HEAD`,
+        ...paths,
+        ...(stat ? ["", stat] : []),
+    ];
+    const withoutAgentChange = input.report.evidence.filter((item) => item.kind !== "change");
+    const criteria = criteriaForChangeEvidence(input.report);
+    return {
+        ...input.report,
+        evidence: [
+            ...withoutAgentChange,
+            {
+                kind: "change",
+                name: "Repository diff (Bridge witness)",
+                details,
+                acceptance_criteria: criteria,
+                witness: "bridge",
+            },
+        ],
+    };
+}

package/dist/ensure-normative-evidence.js

@@ -0,0 +1,22 @@
+export function ensureNormativeEvidence(input) {
+    if (!input.materialized.length)
+        return input.report;
+    const without = input.report.evidence.filter((item) => item.name !== "Normative references (Bridge witness)");
+    const details = input.materialized.flatMap((entry) => [
+        `${entry.label} @ ${entry.repository} (${entry.revision.slice(0, 12)})`,
+        ...entry.workspace_paths.map((path) => `  ${path}`),
+    ]);
+    return {
+        ...input.report,
+        evidence: [
+            ...without,
+            {
+                kind: "documentation",
+                name: "Normative references (Bridge witness)",
+                details,
+                acceptance_criteria: [],
+                witness: "bridge",
+            },
+        ],
+    };
+}

package/dist/execution.js

@@ -16,6 +16,11 @@ import { AgentNoLandCommitError, agentNoLandCommitMessage, requiresLandCommit }
 import { agentClaimsRepositoryWork, claimsVsGitMismatch, isLandTreeEmpty, reportClaimsRepositoryWork, } from "./land-git-reality.js";
 const execFileAsync = promisify(execFile);
 import { captureVerificationFailure, ensureTestEvidence } from "./ensure-test-evidence.js";
+import { ensureChangeEvidence } from "./ensure-change-evidence.js";
+import { ensureNormativeEvidence } from "./ensure-normative-evidence.js";
+import { changedPathsSince } from "./git-witness.js";
+import { assertNormativeRefsMaterialized, checkNormativeMarkers, materializeNormativeRefs, NORMATIVE_MARKER_PREFIX, NORMATIVE_REF_PREFIX, parseNormativeRefs, } from "./normative-refs.js";
+import { checkIntegrationObligations, INTEGRATION_OBLIGATION_PREFIX, parseIntegrationObligations, } from "./integration-obligations.js";
 /** Keep a Mac awake only while an assignment is active; display sleep remains allowed. */
 export function startIdleSleepGuard(options = {}) {
     if ((options.platform ?? process.platform) !== "darwin")
@@ -66,7 +71,7 @@ export function forgeTransportFailure(message) {
 /** Environment faults that must Hold — mirror CP ENVIRONMENT_FAILURES message patterns. */
 const FINALIZE_ENVIRONMENT_PATTERN = /base[_ ]not[_ ]ancestor|required base commit is not available|source[_ ]workspace[_ ]dirty|uncommitted changes|dirty workspace|workspace[_ ]head[_ ]changed|workspace[_ ]repository|workspace[_ ]unavailable|driver[_ ]not[_ ]authenticated|not logged in|no login|not authenticated|login required|no[_ ]online[_ ]driver|bridge[_ ]preflight|stale bridge|bridge version/i;
 /** Delivery-report / grant / evidence contract defects (non-retryable rework). */
-const FINALIZE_CONTRACT_PATTERN = /missing required evidence|without the repo_write grant|pull_request_url|Artifact delivery requires|outside the approved scope|head commit|test evidence must include|Met acceptance criteria|Agent report|Agent reported|Agent did not land repository changes|Delivery report/i;
+const FINALIZE_CONTRACT_PATTERN = /missing required evidence|without the repo_write grant|pull_request_url|Artifact delivery requires|outside the approved scope|head commit|test evidence must include|Met acceptance criteria|Agent report|Agent reported|Agent did not land repository changes|Delivery report|Integration obligation not met|Normative reference unavailable|Normative marker not found/i;
 /**
  * Classify throws from ensureDeliveryPullRequest + validateDeliveryReport.
  * Unknown non-contract faults must not be laundered as execution_contract_failed.
@@ -125,6 +130,18 @@ const taskSpecSchema = z.object({
     instruction: z.string().optional(),
     evidence_standard: z.unknown().optional(),
     working_language: z.enum(["en", "zh"]).optional(),
+    integration_obligations: z.array(z.object({
+        kind: z.literal("symbol_referenced_from"),
+        symbol: z.string(),
+        from_globs: z.array(z.string()).optional(),
+    })).optional(),
+    normative_refs: z.array(z.object({
+        label: z.string(),
+        repository: z.string(),
+        paths: z.array(z.string()),
+        revision: z.string().optional(),
+        markers: z.array(z.string()).optional(),
+    })).optional(),
 });
 const executionContractSchema = z.object({
     repository_fingerprint: z.string().nullable().optional().default(null),
@@ -612,6 +629,34 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
         }
         await client.updateAttempt(taskId, { worktreePath: attemptWorkspace });
     }
+    let normativeMaterialized = [];
+    if (!diagnosis) {
+        const normativeRefs = parseNormativeRefs(spec.normative_refs);
+        if (normativeRefs.length) {
+            try {
+                normativeMaterialized = await materializeNormativeRefs({
+                    sourceWorkspace: workspace,
+                    attemptWorkspace,
+                    refs: normativeRefs,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const retryable = message.startsWith(NORMATIVE_REF_PREFIX)
+                    && /could not clone|could not checkout|timed out|Could not resolve|connection/i.test(message);
+                await queueTerminal(client, taskId, {
+                    action: "fail",
+                    body: {
+                        error: message,
+                        retryable,
+                        idempotency_key: `bridge:normative-ref:${active.attemptId}`,
+                    },
+                });
+                console.error(`Assignment ${taskId} normative reference materialization failed: ${redactSecrets(message)}`);
+                return;
+            }
+        }
+    }
     // Diagnosis reads manifests and verification commands from the failed tree itself. The source
     // checkout may be clean but stale relative to edits that caused the failure.
     const attemptBrief = diagnosis
@@ -707,7 +752,19 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
             failureOutput: diagnosticFailure,
             verificationCommands: attemptBrief?.verification ?? [],
         })
-        : buildAssignmentPrompt({ taskId, objective: task.objective, spec, grants, workspace: attemptWorkspace, currentHead: worktreeStart, reworkFeedback, workPackage, verificationCommands: attemptBrief?.verification ?? [], executionClass });
+        : buildAssignmentPrompt({
+            taskId,
+            objective: task.objective,
+            spec,
+            grants,
+            workspace: attemptWorkspace,
+            currentHead: worktreeStart,
+            reworkFeedback,
+            workPackage,
+            verificationCommands: attemptBrief?.verification ?? [],
+            executionClass,
+            normativeRefs: normativeMaterialized,
+        });
     const resuming = Boolean(options.forceResumeSessionId);
     await client.attemptRequest(taskId, "progress", {
         phase: diagnosis ? "inspecting" : "changing",
@@ -1151,6 +1208,10 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                 title: task.objective,
                 repositoryFingerprint: executionContract.repository_fingerprint,
             });
+            // Ask git what changed before trusting what the report says changed.
+            const actualPaths = /^[0-9a-f]{7,40}$/i.test(worktreeStart)
+                ? await changedPathsSince(attemptWorkspace, worktreeStart)
+                : null;
             // Mechanical test path: agent often forgets verbatim make test / npm test output.
             report = await ensureTestEvidence({
                 workspace: attemptWorkspace,
@@ -1159,11 +1220,25 @@ async function runClaimedAssignment(client, config, driver, workspace, brief, ta
                 grants,
                 verificationCommands: attemptBrief?.verification ?? [],
             });
-            // Ask git what changed before trusting what the report says changed.
-            const startCommit = executionContract.requested_base_commit && executionContract.claimed_head
-                ? await resolveAttemptStartCommit(workspace, executionContract.requested_base_commit, executionContract.claimed_head)
-                : null;
-            const actualPaths = startCommit ? await changedPathsSince(attemptWorkspace, startCommit) : null;
+            report = await ensureChangeEvidence({
+                workspace: attemptWorkspace,
+                baseCommit: /^[0-9a-f]{7,40}$/i.test(worktreeStart) ? worktreeStart : startCommit,
+                report,
+                spec,
+                grants,
+                changedPaths: actualPaths,
+            });
+            const integrationCheck = await checkIntegrationObligations(attemptWorkspace, parseIntegrationObligations(spec.integration_obligations));
+            if (!integrationCheck.ok) {
+                throw new Error(`${INTEGRATION_OBLIGATION_PREFIX}: ${integrationCheck.failures.join("; ")}`);
+            }
+            const normativeRefs = parseNormativeRefs(spec.normative_refs);
+            const markerCheck = await checkNormativeMarkers(attemptWorkspace, normativeRefs, actualPaths);
+            if (!markerCheck.ok) {
+                throw new Error(`${NORMATIVE_MARKER_PREFIX}: ${markerCheck.failures.join("; ")}`);
+            }
+            assertNormativeRefsMaterialized(normativeRefs, normativeMaterialized);
+            report = ensureNormativeEvidence({ report, spec, materialized: normativeMaterialized });
             validateDeliveryReport(report, spec, grants, actualPaths ?? undefined);
         }
         catch (error) {
@@ -1582,43 +1657,9 @@ function referenceKind(kind) {
 }
 /**
  * What this attempt actually changed, according to git rather than to the agent's prose.
- *
- * The scope check used to compare approved paths against strings the agent wrote about itself, so a
- * run that edited an approved file and named it "tools.ts" failed the contract and spent an attempt
- * on a path format. Git knows the truth, and Bridge holds the worktree: this is both stricter (a
- * change cannot be omitted from the report to escape the check) and more forgiving (how the agent
- * phrases a path stops mattering).
- *
- * Null when git cannot answer — an unknown must not fail a delivery, so the caller falls back to the
- * report exactly as before.
+ * Implemented in git-witness.ts; re-exported for control-plane test pins and investigation.
  */
-export async function changedPathsSince(worktree, startCommit) {
-    const run = async (args) => {
-        try {
-            const { stdout } = await execFileAsync("git", ["-C", worktree, ...args], { timeout: 30_000, maxBuffer: 8_000_000 });
-            return stdout;
-        }
-        catch {
-            return null;
-        }
-    };
-    const committed = await run(["diff", "--name-only", `${startCommit}..HEAD`]);
-    if (committed === null)
-        return null;
-    const paths = new Set(committed.split("\n").map((line) => line.trim()).filter(Boolean));
-    // Work the agent left uncommitted still lands in the delivery for lands=false packages.
-    const pending = await run(["status", "--porcelain"]);
-    for (const line of (pending ?? "").split("\n")) {
-        const entry = line.slice(3).trim();
-        if (!entry)
-            continue;
-        // A rename reports "old -> new"; the new path is the one that exists.
-        const path = entry.includes(" -> ") ? entry.slice(entry.lastIndexOf(" -> ") + 4).trim() : entry;
-        if (path)
-            paths.add(path.replace(/^"|"$/g, ""));
-    }
-    return [...paths];
-}
+export { changedPathsSince } from "./git-witness.js";
 export function validateChangeScope(report, changeScope, options = {}) {
     if (!changeScope.length)
         return;

package/dist/git-witness.js

@@ -0,0 +1,52 @@
+/**
+ * Git facts Bridge witnesses during finalize — not agent prose.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function gitLines(worktree, args) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", worktree, ...args], {
+            timeout: 30_000,
+            maxBuffer: 8_000_000,
+        });
+        return stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Paths changed on the attempt branch since `startCommit`, including uncommitted work.
+ * Null when git cannot answer — callers must not treat null as failure.
+ */
+export async function changedPathsSince(worktree, startCommit) {
+    const committed = await gitLines(worktree, ["diff", "--name-only", `${startCommit}..HEAD`]);
+    if (committed === null)
+        return null;
+    const paths = new Set(committed);
+    const pending = await gitLines(worktree, ["status", "--porcelain"]);
+    for (const line of pending ?? []) {
+        const entry = line.slice(3).trim();
+        if (!entry)
+            continue;
+        const path = entry.includes(" -> ") ? entry.slice(entry.lastIndexOf(" -> ") + 4).trim() : entry;
+        if (path)
+            paths.add(path.replace(/^"|"$/g, ""));
+    }
+    return [...paths];
+}
+/** Short stat summary for change evidence artifacts. */
+export async function diffStatSince(worktree, startCommit) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", worktree, "diff", "--stat", `${startCommit}..HEAD`], {
+            timeout: 30_000,
+            maxBuffer: 2_000_000,
+        });
+        const text = stdout.trim();
+        return text || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/integration-obligations.js

@@ -0,0 +1,69 @@
+/**
+ * Integration obligations — planner-authored wiring checks, enforced at Bridge finalize.
+ *
+ * Generic across stacks: a new implementation must be referenced from runtime entrypoints,
+ * not only defined in an isolated module.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+const execFileAsync = promisify(execFile);
+export const integrationObligationSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("symbol_referenced_from"),
+        symbol: z.string().trim().min(1).max(200),
+        from_globs: z.array(z.string().trim().min(1).max(200)).max(20).optional(),
+    }),
+]);
+/** Default runtime entrypoint globs when the planner omits from_globs. */
+export const DEFAULT_ENTRYPOINT_GLOBS = [
+    "**/main.rs",
+    "**/lib.rs",
+    "**/mod.rs",
+    "**/index.ts",
+    "**/index.tsx",
+    "**/index.js",
+    "**/App.tsx",
+    "**/app/main.py",
+    "**/main.go",
+];
+export function parseIntegrationObligations(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        const parsed = integrationObligationSchema.safeParse(entry);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out;
+}
+async function symbolReferencedFrom(workspace, symbol, globs) {
+    const pathspecs = globs.map((glob) => `:(glob)${glob}`);
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", workspace, "grep", "-l", "-F", "--untracked", symbol, "--", ...pathspecs], { timeout: 30_000, maxBuffer: 4_000_000 });
+        return stdout.trim().length > 0;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 1 || code === "1")
+            return false;
+        throw error;
+    }
+}
+export async function checkIntegrationObligations(workspace, obligations) {
+    if (!obligations.length)
+        return { ok: true };
+    const failures = [];
+    for (const obligation of obligations) {
+        if (obligation.kind === "symbol_referenced_from") {
+            const globs = obligation.from_globs?.length ? obligation.from_globs : [...DEFAULT_ENTRYPOINT_GLOBS];
+            const referenced = await symbolReferencedFrom(workspace, obligation.symbol, globs);
+            if (!referenced) {
+                failures.push(`symbol "${obligation.symbol}" is not referenced from any entrypoint (${globs.join(", ")})`);
+            }
+        }
+    }
+    return failures.length ? { ok: false, failures } : { ok: true };
+}
+export const INTEGRATION_OBLIGATION_PREFIX = "Integration obligation not met";

package/dist/land-git-reality.js

@@ -84,7 +84,7 @@ export function agentClaimsRepositoryWork(text) {
     }
     if (NO_CHANGE_OUTCOME.test(text))
         return false;
-    return /\b(rewrote|replaced|implemented|fetcher\.rs|head_commit|"changes"\s*:\s*\[)/i.test(text);
+    return /\b(rewrote|replaced|implemented|fetcher\.rs|head_commit|"changes"\s*:\s*\[\s*")/i.test(text);
 }
 /** Parsed Delivery claims repository work (stricter than free text). */
 export function reportClaimsRepositoryWork(report) {

package/dist/normative-refs.js

@@ -0,0 +1,217 @@
+/**
+ * Materialize planner-authored normative references into the attempt workspace.
+ *
+ * Cached under {sourceWorkspace}/.conduit/normative-cache/ so sibling-repo specs are
+ * fetched once per machine checkout, not once per attempt.
+ */
+import { access, cp, mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { normalizeRepositoryUrl } from "./brief.js";
+const execFileAsync = promisify(execFile);
+export const normativeRefSchema = z.object({
+    label: z.string().trim().min(1).max(120),
+    repository: z.string().trim().min(3).max(500),
+    paths: z.array(z.string().trim().min(1).max(500)).min(1).max(20),
+    revision: z.string().trim().min(1).max(120).optional(),
+    markers: z.array(z.string().trim().min(1).max(500)).max(20).optional(),
+});
+export const NORMATIVE_REF_PREFIX = "Normative reference unavailable";
+export const NORMATIVE_MARKER_PREFIX = "Normative marker not found";
+export function parseNormativeRefs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        const parsed = normativeRefSchema.safeParse(entry);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out;
+}
+function fingerprint(repository) {
+    return normalizeRepositoryUrl(repository.includes("://") ? repository : `https://${repository}`);
+}
+function sanitizeLabel(label) {
+    const cleaned = label.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return cleaned || "ref";
+}
+function validateNormativePath(path) {
+    const normalized = path.replaceAll("\\", "/");
+    if (!normalized || normalized.startsWith("/") || normalized.split("/").includes("..")) {
+        throw new Error(`${NORMATIVE_REF_PREFIX}: invalid path ${path}`);
+    }
+}
+function cacheDir(sourceWorkspace, repository) {
+    return join(sourceWorkspace, ".conduit", "normative-cache", fingerprint(repository).replaceAll("/", "__"));
+}
+const GIT_NO_PROMPT = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+function cloneUrl(repository) {
+    return `https://${fingerprint(repository)}.git`;
+}
+function assertPublicGitHost(repository) {
+    const host = fingerprint(repository).split("/")[0] ?? "";
+    if (!host || !host.includes(".") || host === "localhost" || host.endsWith(".localhost")
+        || host.endsWith(".internal") || /^\d/.test(host) || host.includes(":")) {
+        throw new Error(`${NORMATIVE_REF_PREFIX}: repository host is not a public git host`);
+    }
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPinnedRevision(repoDir) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", repoDir, "rev-parse", "HEAD"], {
+            timeout: 30_000,
+            maxBuffer: 256_000,
+        });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function gitNoPrompt(args, timeout, maxBuffer) {
+    await execFileAsync("git", args, { timeout, maxBuffer, env: GIT_NO_PROMPT });
+}
+async function ensureRepoCache(sourceWorkspace, ref) {
+    assertPublicGitHost(ref.repository);
+    const dir = cacheDir(sourceWorkspace, ref.repository);
+    const wantedRevision = ref.revision ?? "HEAD";
+    const marker = join(dir, ".conduit-normative-revision");
+    let cachedRevision = null;
+    if (await pathExists(marker)) {
+        cachedRevision = (await readFile(marker, "utf8")).trim() || null;
+    }
+    const repoReady = await pathExists(join(dir, ".git"));
+    if (!repoReady) {
+        await mkdir(dirname(dir), { recursive: true });
+        const cloneArgs = ["clone", "--depth", "1"];
+        if (ref.revision && !/^[0-9a-f]{40}$/i.test(ref.revision)) {
+            cloneArgs.push("--branch", ref.revision);
+        }
+        cloneArgs.push(cloneUrl(ref.repository), dir);
+        try {
+            await gitNoPrompt(cloneArgs, 180_000, 4_000_000);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`${NORMATIVE_REF_PREFIX}: could not clone ${fingerprint(ref.repository)} (${message})`);
+        }
+    }
+    else if (ref.revision && cachedRevision !== wantedRevision) {
+        try {
+            await gitNoPrompt(["-C", dir, "fetch", "--depth", "1", "origin", ref.revision], 120_000, 4_000_000);
+            await gitNoPrompt(["-C", dir, "checkout", "--detach", "FETCH_HEAD"], 60_000, 1_000_000);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`${NORMATIVE_REF_PREFIX}: could not checkout ${ref.revision} in ${fingerprint(ref.repository)} (${message})`);
+        }
+    }
+    else if (!ref.revision) {
+        try {
+            await gitNoPrompt(["-C", dir, "fetch", "--depth", "1", "origin", "HEAD"], 120_000, 4_000_000);
+            await gitNoPrompt(["-C", dir, "checkout", "--detach", "FETCH_HEAD"], 60_000, 1_000_000);
+        }
+        catch {
+            // Keep the last successful cache when origin is unreachable (offline tests, private host already rejected).
+        }
+    }
+    const revision = (await readPinnedRevision(dir)) ?? wantedRevision;
+    await writeFile(marker, `${revision}\n`, "utf8");
+    return { dir, revision };
+}
+async function copyNormativePath(cacheRepo, attemptWorkspace, label, path) {
+    validateNormativePath(path);
+    const src = join(cacheRepo, path);
+    if (!(await pathExists(src))) {
+        throw new Error(`${NORMATIVE_REF_PREFIX}: ${path} not found in ${cacheRepo}`);
+    }
+    const dest = join(attemptWorkspace, ".conduit", "normative", sanitizeLabel(label), path);
+    await mkdir(dirname(dest), { recursive: true });
+    await cp(src, dest, { recursive: true });
+    return relative(attemptWorkspace, dest).replaceAll("\\", "/");
+}
+export async function materializeNormativeRefs(input) {
+    if (!input.refs.length)
+        return [];
+    const materialized = [];
+    for (const ref of input.refs) {
+        const { dir, revision } = await ensureRepoCache(input.sourceWorkspace, ref);
+        const workspace_paths = [];
+        for (const path of ref.paths) {
+            workspace_paths.push(await copyNormativePath(dir, input.attemptWorkspace, ref.label, path));
+        }
+        materialized.push({
+            label: ref.label,
+            repository: fingerprint(ref.repository),
+            revision,
+            workspace_paths,
+        });
+    }
+    return materialized;
+}
+export function assertNormativeRefsMaterialized(refs, materialized) {
+    if (!refs.length)
+        return;
+    if (materialized.length !== refs.length) {
+        throw new Error(`${NORMATIVE_REF_PREFIX}: expected ${refs.length} materialized references, got ${materialized.length}`);
+    }
+    for (const entry of materialized) {
+        if (!entry.workspace_paths.length) {
+            throw new Error(`${NORMATIVE_REF_PREFIX}: ${entry.label} has no workspace paths`);
+        }
+    }
+}
+function isConduitPath(path) {
+    const normalized = path.replaceAll("\\", "/");
+    return normalized === ".conduit" || normalized.startsWith(".conduit/");
+}
+async function markerPresent(workspace, marker, paths) {
+    const args = ["-C", workspace, "grep", "-l", "-F", "--untracked", marker, "--", ...paths];
+    try {
+        const { stdout } = await execFileAsync("git", args, {
+            timeout: 30_000,
+            maxBuffer: 4_000_000,
+        });
+        return stdout.trim().length > 0;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 1 || code === "1")
+            return false;
+        throw error;
+    }
+}
+export async function checkNormativeMarkers(workspace, refs, changedPaths) {
+    const scoped = refs.filter((ref) => ref.markers?.length);
+    if (!scoped.length)
+        return { ok: true };
+    if (changedPaths === null) {
+        return { ok: false, failures: ["changed files are unknown; required markers cannot be verified"] };
+    }
+    const searchPaths = changedPaths.filter((path) => path && !isConduitPath(path));
+    if (!searchPaths.length) {
+        return { ok: false, failures: ["no changed files to search for required markers"] };
+    }
+    const failures = [];
+    for (const ref of scoped) {
+        for (const marker of ref.markers ?? []) {
+            const found = await markerPresent(workspace, marker, searchPaths);
+            if (!found) {
+                failures.push(`marker "${marker}" from ${ref.label} not found in changed files`);
+            }
+        }
+    }
+    return failures.length ? { ok: false, failures } : { ok: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miraland-labs/conduit-bridge",
-  "version": "0.16.5",
+  "version": "0.16.7",
   "description": "Conduit Bridge CLI — join, connect, disconnect, multi-driver lanes, and run Claude Code / Codex / Cursor / OpenCode / Pi / Kiro / Antigravity / Grok Build agents for a Conduit organization",
   "type": "module",
   "bin": {