@kungfu-tech/buildchain 4.1.3-alpha.9 → 4.1.4-alpha.0

package/packages/core/paper/operations/scaffold.js

@@ -1,40 +1,22 @@
+import { PAPER_PATHS } from "../paper-repository.js";
 import {
-  readJson,
-  PAPER_PATHS,
-  parsePaperVersion,
-  paperConfig,
-  resolvePaperRepository,
-} from "../paper-repository.js";
-import path from "node:path";
-import { createBuildchainContractLock } from "../../contracts/buildchain-contract.js";
-import { paperAgentEntryFiles } from "../paper-agent-entry.js";
+  consumerAgentInstructions,
+  consumerConfiguration,
+} from "../../adoption/consumer-init.js";
+import { consumerWorkflows } from "../../consumer/contract/entries.js";
 import {
   scaffoldMakefile,
   scaffoldPackageJson,
   scaffoldReadme,
   scaffoldMap,
   scaffoldMainTex,
-  managedPaperPackageJson,
-  paperDependencyIgnore,
   createPaperScaffoldOperations,
 } from "../paper-scaffold-content.js";
 import {
-  runtimeContractWorld,
-  runtimeAcceptedAt,
   runtimeLicenseText,
   normalizePackageName,
-  resolvePaperRuntimeGitSha,
   buildchainPackageIdentity,
 } from "./runtime.js";
-import { jsonText } from "./files.js";
-import {
-  scaffoldBuildWorkflow,
-  scaffoldReleaseWorkflow,
-  scaffoldVerifyWorkflow,
-} from "./scaffold-workflows.js";
-import { createPaperProvisioningAuthority } from "./provisioning.js";
-import { scaffoldConfig } from "./scaffold-config.js";
-import { paperPnpmWorkspace } from "./workspace.js";
 import {
   DEFAULT_TOOLCHAIN_IMAGE,
   DEFAULT_TOOLCHAIN_DIGEST,
@@ -43,18 +25,11 @@ import {
   PAPER_MIGRATION_CONTRACT,
   PAPER_SCAFFOLD_CONTRACT,
 } from "./identity.js";
-import { validateBuildchainConfig } from "../../consumer/buildchain-config.js";
-import fs from "node:fs";
-import { projectNextDevelopmentToml } from "../../release/next-development-projection.js";
-import {
-  paperChannels,
-  bindPaperAuthority,
-} from "../paper-runtime-channels.js";
+import { migrationFiles } from "./migration.js";
+
 export function scaffoldFiles({
   buildchainRoot,
   buildchainVersion,
-  buildchainRef,
-  buildchainSha,
   cwd,
   name,
   title,
@@ -63,68 +38,11 @@ export function scaffoldFiles({
   version,
   siteBaseUrl,
 }) {
-  const contractWorld = runtimeContractWorld(buildchainRoot);
-  const existingLock = readJson(
-    path.resolve(cwd, PAPER_PATHS.contractLock),
-  ).value;
-  const acceptedAt =
-    existingLock?.buildchain?.acceptedAt ||
-    runtimeAcceptedAt(buildchainRoot, buildchainSha, buildchainVersion);
-  const contractLock = createBuildchainContractLock({
-    buildchainRef,
-    resolvedSha: buildchainSha,
-    contractWorld,
-    acceptedAt,
-  });
-  const contractLockText = jsonText(contractLock);
-  const buildWorkflow = scaffoldBuildWorkflow("v4-alpha", {
-    artifactName: name,
-  });
-  const releaseWorkflow = scaffoldReleaseWorkflow("v4-alpha", {
-    artifactPaths: "_build/main.pdf",
-    releasePassportProductName: title,
-  });
-  const verifyWorkflow = scaffoldVerifyWorkflow("v4-alpha");
-  const agentEntry = paperAgentEntryFiles({
-    cwd,
-    buildchainVersion,
-    buildchainSha,
-    developmentRef: `dev/v${parsePaperVersion(version).major}/v${
-      parsePaperVersion(version).major
-    }.${parsePaperVersion(version).minor}`,
-  });
-  const provisioningAuthority = createPaperProvisioningAuthority({
-    repository,
-    packageName,
-    buildchainVersion,
-    buildchainSha,
-    contractLock: contractLockText,
-    buildWorkflow,
-    verifyWorkflow,
-    releaseWorkflow,
-    agentEntry: agentEntry.get(PAPER_PATHS.agentEntry),
-    agentInstructions: agentEntry.get(PAPER_PATHS.agentInstructions),
-  });
   const licenseText = runtimeLicenseText(buildchainRoot);
-  const files = new Map([
-    [
-      PAPER_PATHS.config,
-      scaffoldConfig({
-        name,
-        title,
-        packageName,
-        version,
-        siteBaseUrl,
-      }),
-    ],
-    [PAPER_PATHS.contractLock, contractLockText],
-    [PAPER_PATHS.versionPin, `${buildchainVersion}\n`],
-    [PAPER_PATHS.buildWorkflow, buildWorkflow],
-    [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
-    [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
-    [PAPER_PATHS.pnpmWorkspace, paperPnpmWorkspace("", buildchainVersion)],
-    [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
-    ...agentEntry,
+  return new Map([
+    [PAPER_PATHS.config, consumerConfiguration({ type: "paper", version })],
+    ...Object.entries(consumerWorkflows()),
+    [PAPER_PATHS.agentInstructions, consumerAgentInstructions()],
     [
       "Makefile",
       scaffoldMakefile({
@@ -137,8 +55,11 @@ export function scaffoldFiles({
       "package.json",
       scaffoldPackageJson({
         name,
+        title,
         packageName,
         repository,
+        version,
+        siteBaseUrl,
         buildchainVersion,
       }),
     ],
@@ -147,149 +68,10 @@ export function scaffoldFiles({
     ["paper/main.tex", scaffoldMainTex(title)],
     ["paper/references.bib", "% Add reviewed bibliography entries here.\n"],
     ["LICENSE", licenseText],
-    [
-      ".gitignore",
-      "node_modules/\n_build/\n.buildchain/publication/\n.buildchain/release-state/\n.buildchain/release-evidence/\n.buildchain/paper/npm-bootstrap.json\n.buildchain/paper/npm-trust.json\n",
-    ],
+    [".gitignore", "node_modules/\n_build/\n"],
   ]);
-  return finalizePaperEntryFiles({
-    files,
-    cwd,
-    buildchainRoot,
-    buildchainVersion,
-    buildchainSha,
-    contractLock,
-    provisioningAuthority,
-  });
-}
-export function migrationFiles({
-  cwd,
-  buildchainRoot,
-  buildchainVersion,
-  buildchainSha,
-  stableBuildchainRoot,
-  alphaBuildchainRoot,
-}) {
-  const configResult = paperConfig(cwd);
-  if (configResult.error) {
-    throw new Error(
-      `paper migration requires a valid publication config: ${configResult.error}`,
-    );
-  }
-  validateBuildchainConfig(cwd, { requireLifecycleStages: ["verify"] });
-  const config = configResult.loaded.config;
-  const repository = resolvePaperRepository(cwd);
-  if (!repository) {
-    throw new Error(
-      "paper migration requires an exact GitHub repository identity",
-    );
-  }
-  const packageName = normalizePackageName(
-    config.publish?.package || config.publish?.mainPackage || "",
-    "paper publish package",
-  );
-  const runtimeSha =
-    buildchainSha ||
-    resolvePaperRuntimeGitSha(buildchainRoot, buildchainVersion);
-  if (!GIT_SHA_PATTERN.test(runtimeSha)) {
-    throw new Error("paper migration requires an exact Buildchain source SHA");
-  }
-  const runtimeIdentity = buildchainPackageIdentity(
-    buildchainRoot,
-    buildchainVersion,
-  );
-  if (!runtimeIdentity.version) {
-    throw new Error(
-      "paper migration requires an exact Buildchain package version",
-    );
-  }
-  const existingLock = readJson(
-    path.resolve(cwd, PAPER_PATHS.contractLock),
-  ).value;
-  const contractLock = migrationContractLock({
-    buildchainRoot,
-    existingLock,
-    runtimeIdentity,
-    runtimeSha,
-  });
-  const contractLockText = jsonText(contractLock);
-  const buildWorkflow = scaffoldBuildWorkflow("v4-alpha", {
-    artifactName: config.project.name,
-  });
-  const releaseWorkflow = scaffoldReleaseWorkflow("v4-alpha", {
-    artifactPaths: config.publication.artifactPaths.join(","),
-    releasePassportProductName: config.publication.title,
-  });
-  const verifyWorkflow = scaffoldVerifyWorkflow("v4-alpha");
-  const agentEntry = paperAgentEntryFiles({
-    cwd,
-    buildchainVersion: runtimeIdentity.version,
-    buildchainSha: runtimeSha,
-  });
-  const provisioningAuthority = createPaperProvisioningAuthority({
-    repository,
-    packageName,
-    buildchainVersion: runtimeIdentity.version,
-    buildchainSha: runtimeSha,
-    contractLock: contractLockText,
-    buildWorkflow,
-    verifyWorkflow,
-    releaseWorkflow,
-    agentEntry: agentEntry.get(PAPER_PATHS.agentEntry),
-    agentInstructions: agentEntry.get(PAPER_PATHS.agentInstructions),
-  });
-  const currentPackage = readJson(path.resolve(cwd, "package.json"));
-  if (!currentPackage.exists || currentPackage.error || !currentPackage.value) {
-    throw new Error("paper migration requires a valid package.json");
-  }
-  const packageJson = managedPaperPackageJson(
-    currentPackage.value,
-    runtimeIdentity.version,
-  );
-  const pnpmWorkspacePath = path.resolve(cwd, PAPER_PATHS.pnpmWorkspace);
-  const pnpmWorkspace = paperPnpmWorkspace(
-    fs.existsSync(pnpmWorkspacePath)
-      ? fs.readFileSync(pnpmWorkspacePath, "utf8")
-      : "",
-    runtimeIdentity.version,
-  );
-  const files = new Map([
-    [
-      PAPER_PATHS.config,
-      projectNextDevelopmentToml(
-        fs.readFileSync(path.resolve(cwd, PAPER_PATHS.config), "utf8"),
-      ),
-    ],
-    [PAPER_PATHS.contractLock, contractLockText],
-    [PAPER_PATHS.versionPin, `${runtimeIdentity.version}\n`],
-    [PAPER_PATHS.buildWorkflow, buildWorkflow],
-    [PAPER_PATHS.verifyWorkflow, verifyWorkflow],
-    [PAPER_PATHS.releaseWorkflow, releaseWorkflow],
-    [PAPER_PATHS.pnpmWorkspace, pnpmWorkspace],
-    [PAPER_PATHS.provisioningAuthority, jsonText(provisioningAuthority)],
-    ...agentEntry,
-    ["package.json", jsonText(packageJson)],
-    [
-      ".gitignore",
-      paperDependencyIgnore(
-        fs.existsSync(path.join(cwd, ".gitignore"))
-          ? fs.readFileSync(path.join(cwd, ".gitignore"), "utf8")
-          : "",
-      ),
-    ],
-  ]);
-  return finalizePaperEntryFiles({
-    files,
-    cwd,
-    buildchainRoot,
-    buildchainVersion: runtimeIdentity.version,
-    buildchainSha: runtimeSha,
-    contractLock,
-    provisioningAuthority,
-    stableBuildchainRoot,
-    alphaBuildchainRoot,
-  });
 }
+
 export const {
   planPaperMigration,
   planPaperScaffold,
@@ -302,97 +84,5 @@ export const {
   buildchainPackageIdentity,
   migrationFiles,
   normalizePackageName,
-  resolvePaperRuntimeGitSha,
   scaffoldFiles,
 });
-
-function migrationContractLock({
-  buildchainRoot,
-  existingLock,
-  runtimeIdentity,
-  runtimeSha,
-}) {
-  return createBuildchainContractLock({
-    buildchainRef: "v4",
-    resolvedSha: runtimeSha,
-    contractWorld: runtimeContractWorld(buildchainRoot),
-    acceptedAt:
-      existingLock?.buildchain?.resolvedSha === runtimeSha
-        ? existingLock.buildchain.acceptedAt
-        : runtimeAcceptedAt(
-            buildchainRoot,
-            runtimeSha,
-            runtimeIdentity.version,
-          ),
-  });
-}
-
-function finalizePaperEntryFiles({
-  files,
-  cwd,
-  buildchainRoot,
-  buildchainVersion,
-  buildchainSha,
-  contractLock,
-  provisioningAuthority,
-  stableBuildchainRoot,
-  alphaBuildchainRoot,
-}) {
-  if (!buildchainVersion.startsWith("4."))
-    throw new Error("Paper provisioning requires a Buildchain v4 runtime");
-  const channelPlan = paperChannels({
-    cwd,
-    buildchainRoot,
-    buildchainVersion: buildchainVersion,
-    buildchainSha: buildchainSha,
-    contractWorld: runtimeContractWorld(buildchainRoot),
-    acceptedAt: contractLock.buildchain.acceptedAt,
-    stableBuildchainRoot,
-    alphaBuildchainRoot,
-  });
-  for (const channel of Object.values(channelPlan.channels))
-    files.set(channel.lockPath, channel.content);
-  for (const workflowPath of [
-    PAPER_PATHS.buildWorkflow,
-    PAPER_PATHS.verifyWorkflow,
-  ]) {
-    files.set(
-      workflowPath,
-      files
-        .get(workflowPath)
-
-        .replaceAll(
-          ".buildchain/contract-lock.json",
-          ".buildchain/alpha-contract-lock.json",
-        ),
-    );
-  }
-  const releaseWorkflow = files.get(PAPER_PATHS.releaseWorkflow);
-  const releaseStart = releaseWorkflow.indexOf("  paper-release:\n");
-  const releaseJob = releaseWorkflow.slice(releaseStart);
-  const alphaJob = releaseJob
-    .replace(
-      "  paper-release:\n",
-      "  paper-release-alpha:\n    if: ${{ startsWith(github.ref_name, 'alpha/') }}\n",
-    )
-
-    .replaceAll(
-      ".buildchain/contract-lock.json",
-      ".buildchain/alpha-contract-lock.json",
-    );
-  const stableJob = releaseJob
-    .replace(
-      "  paper-release:\n",
-      "  paper-release:\n    if: ${{ startsWith(github.ref_name, 'release/') }}\n",
-    )
-    .replaceAll("@v4-alpha", "@v4");
-  files.set(
-    PAPER_PATHS.releaseWorkflow,
-    `${releaseWorkflow.slice(0, releaseStart)}${alphaJob}\n${stableJob}`,
-  );
-  files.set(
-    PAPER_PATHS.provisioningAuthority,
-    jsonText(bindPaperAuthority(provisioningAuthority, channelPlan, files)),
-  );
-  return files;
-}

package/packages/core/paper/operations/status.js

@@ -1,3 +1,4 @@
+import { paperConsumerStatus } from "../consumer-status.js";
 import path from "node:path";
 import { PAPER_PATHS, resolvePaperRepository } from "../paper-repository.js";
 import {
@@ -9,63 +10,36 @@ import {
 } from "./status-facts.js";
 import { existingFileFact } from "./files.js";
 import { PAPER_STATUS_CONTRACT } from "./identity.js";
-export function paperStatusBlockingNextActions({
-  stateMap,
-  deterministic,
-  transactionFacts,
-}) {
-  const actions = [];
-  if (!stateMap.scaffolded.satisfied) {
-    actions.push({
-      id: "scaffold-paper",
-      command: "buildchain paper scaffold --help",
-      description: "Plan a no-overwrite Buildchain paper scaffold.",
-    });
-  } else if (!stateMap.governed.satisfied) {
-    actions.push({
-      id: "restore-governance",
-      command: "buildchain paper preflight --json",
-      description:
-        "Repair the Git/contract-lock governance checks reported by preflight.",
-    });
-  } else if (!stateMap["content-ready"].satisfied) {
-    actions.push({
-      id: "complete-paper-content",
-      command: "make check",
-      description: "Add every declared paper source and metadata input.",
-    });
-  } else if (!deterministic) {
-    actions.push({
-      id: "build-reproducible-artifact",
-      command: "buildchain paper build --execute --json",
-      description:
-        "Run the existing two-clean-build reproducibility gate and promote exact bytes.",
-    });
-  } else if (
-    !stateMap.bootstrapped.satisfied ||
-    !stateMap["trust-bound"].satisfied
-  ) {
-    actions.push({
-      id: "bootstrap-npm",
-      command: "buildchain paper bootstrap npm --json",
+export function paperStatusBlockingNextActions() {
+  return [
+    {
+      id: "migrate-consumer-contract",
+      command: "buildchain paper migrate --json",
       description:
-        "Inspect the dry-run npm bootstrap and Trusted Publishing handoff.",
-    });
-  } else if (!stateMap["alpha-complete"].satisfied) {
-    actions.push({
-      id: transactionFacts.selected ? "resume-alpha" : "start-alpha",
-      command: transactionFacts.selected
-        ? "buildchain paper resume --json"
-        : "buildchain paper alpha --json",
-      description: transactionFacts.selected
-        ? "Resume the exact sealed release transaction."
-        : "Plan the protected dev-to-alpha publication PR.",
-    });
-  }
-  return actions;
+        "Review migration of this legacy Paper repository to schema 2 and the shared normal/recovery caller pair. Historical receipts remain unchanged.",
+    },
+  ];
 }
 export function collectPaperStatus({ cwd = process.cwd() } = {}) {
   const resolvedCwd = path.resolve(cwd);
+  const consumer = paperConsumerStatus(resolvedCwd);
+  if (consumer)
+    return {
+      ...consumer,
+      contract: PAPER_STATUS_CONTRACT,
+      highestEvidenceState: consumer.ok
+        ? "configured"
+        : "configuration-invalid",
+      states: consumer.checks.map((check) => ({
+        id: check.id,
+        status: check.status,
+        reason: check.message,
+      })),
+    };
+  return collectLegacyPaperStatus(resolvedCwd);
+}
+
+function collectLegacyPaperStatus(resolvedCwd) {
   const governance = collectPaperGovernanceFacts(resolvedCwd);
   const evidence = collectPaperEvidenceFacts(
     resolvedCwd,

package/packages/core/paper/paper-agent-entry.js

@@ -12,13 +12,7 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
-import {
-  mergeNextDevelopmentAgentInstructions,
-  NEXT_DEVELOPMENT_AGENT_SECTION_START,
-  NEXT_DEVELOPMENT_AGENT_SECTION_END,
-  NEXT_DEVELOPMENT_LOCAL_COMMAND,
-} from "../release/next-development-projection.js";
-import { NEXT_DEVELOPMENT_ADR } from "../release/next-development-transition.js";
+import { paperConsumerStatus } from "./consumer-status.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -36,10 +30,6 @@ const EXACT_PAPER_SCRIPTS = Object.freeze({
 const GIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
 const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/i;
 
-function jsonText(value) {
-  return `${JSON.stringify(value, null, 2)}\n`;
-}
-
 export function paperAgentEntryInstructions({ developmentRef }) {
   return `${PAPER_AGENT_ENTRY_SECTION_START}
 ## Paper work entry (required)
@@ -65,142 +55,6 @@ does not bypass remote policy.
 ${PAPER_AGENT_ENTRY_SECTION_END}`;
 }
 
-export function mergePaperAgentEntryInstructions(
-  current = "",
-  { developmentRef },
-) {
-  const source = String(current || "");
-  const section = paperAgentEntryInstructions({ developmentRef });
-  const start = source.indexOf(PAPER_AGENT_ENTRY_SECTION_START);
-  const end = source.indexOf(PAPER_AGENT_ENTRY_SECTION_END);
-  if ((start === -1) !== (end === -1)) {
-    throw new Error(
-      "AGENTS.md has an incomplete Buildchain Paper agent-entry managed section",
-    );
-  }
-  if (start === -1) {
-    return source.trim()
-      ? `${source.trimEnd()}\n\n${section}\n`
-      : `# AGENTS.md\n\n${section}\n`;
-  }
-  if (
-    source.indexOf(PAPER_AGENT_ENTRY_SECTION_START, start + 1) !== -1 ||
-    source.indexOf(PAPER_AGENT_ENTRY_SECTION_END, end + 1) !== -1 ||
-    end < start
-  ) {
-    throw new Error(
-      "AGENTS.md has ambiguous Buildchain Paper agent-entry managed sections",
-    );
-  }
-  return `${source.slice(0, start)}${section}${source.slice(
-    end + PAPER_AGENT_ENTRY_SECTION_END.length,
-  )}`;
-}
-
-export function createPaperAgentEntry({
-  buildchainVersion,
-  buildchainSha,
-  developmentRef,
-}) {
-  const version = String(buildchainVersion || "").trim();
-  const sourceSha = String(buildchainSha || "").trim();
-  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
-    throw new Error(
-      "paper agent entry requires an exact Buildchain semantic version",
-    );
-  }
-  if (!GIT_SHA_PATTERN.test(sourceSha)) {
-    throw new Error(
-      "paper agent entry requires an exact Buildchain source SHA",
-    );
-  }
-  if (!/^dev\/v\d+\/v\d+\.\d+$/.test(developmentRef)) {
-    throw new Error("paper agent entry requires an exact development ref");
-  }
-  const payload = {
-    schemaVersion: PAPER_AGENT_ENTRY_SCHEMA_VERSION,
-    contract: PAPER_AGENT_ENTRY_CONTRACT,
-    runtime: {
-      package: "@kungfu-tech/buildchain",
-      version,
-      sourceSha,
-    },
-    repository: {
-      developmentRef,
-      pullRequestTarget: developmentRef,
-    },
-    commands: {
-      verify: "pnpm paper:agent:verify",
-      start: "pnpm paper:work:start -- <topic> --execute --json",
-      submit: "pnpm paper:work:submit -- --execute --json",
-    },
-    policy: {
-      localMutation: "dry-run-first",
-      protectedBranchPatterns: [
-        "main",
-        "dev/**",
-        "alpha/**",
-        "release/**",
-        "publish-gate/**",
-      ],
-      workBranchPattern: PAPER_WORK_BRANCH_PATTERN.source,
-      forcePush: false,
-      remoteAcceptance: "required-buildchain-check",
-    },
-  };
-  return {
-    ...payload,
-    entryDigest: sha256Text(stableJson(payload)),
-  };
-}
-
-function mergePaperNextDevelopmentInstructions(current) {
-  const merged = mergeNextDevelopmentAgentInstructions(current);
-  const start = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_START);
-  const end = merged.indexOf(NEXT_DEVELOPMENT_AGENT_SECTION_END);
-  const section = merged.slice(start, end)
-    .replace(
-      `\`${NEXT_DEVELOPMENT_ADR}\``,
-      `[Buildchain next-development ADR](https://github.com/kungfu-systems/buildchain/blob/v4/${NEXT_DEVELOPMENT_ADR})`,
-    )
-    .replace(
-      NEXT_DEVELOPMENT_LOCAL_COMMAND,
-      NEXT_DEVELOPMENT_LOCAL_COMMAND.replace(
-        "node packages/core/", "node node_modules/@kungfu-tech/buildchain/packages/core/",
-      ),
-    );
-  return `${merged.slice(0, start)}${section}${merged.slice(end)}`;
-}
-
-export function paperAgentEntryFiles({
-  cwd,
-  buildchainVersion,
-  buildchainSha,
-  developmentRef = "",
-}) {
-  const resolvedDevelopmentRef = developmentRef || paperDevelopmentRef(cwd);
-  const agentsPath = path.resolve(cwd, PAPER_PATHS.agentInstructions);
-  const currentAgents = fs.existsSync(agentsPath)
-    ? fs.readFileSync(agentsPath, "utf8")
-    : "";
-  const entry = createPaperAgentEntry({
-    buildchainVersion,
-    buildchainSha,
-    developmentRef: resolvedDevelopmentRef,
-  });
-  return new Map([
-    [PAPER_PATHS.agentEntry, jsonText(entry)],
-    [
-      PAPER_PATHS.agentInstructions,
-      mergePaperNextDevelopmentInstructions(
-        mergePaperAgentEntryInstructions(currentAgents, {
-          developmentRef: resolvedDevelopmentRef,
-        }),
-      ),
-    ],
-  ]);
-}
-
 export function resolvePaperBuildchainSha(buildchainRoot, buildchainSha = "") {
   if (buildchainSha) return buildchainSha;
   if (!fs.existsSync(path.resolve(buildchainRoot, ".git"))) return "";
@@ -283,6 +137,41 @@ export function collectPaperAgentEntry({
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const developmentRef = paperDevelopmentRef(resolvedCwd);
+  const consumer = paperConsumerStatus(resolvedCwd);
+  if (consumer) {
+    const context =
+      mode === "ci"
+        ? ciContext({ env, developmentRef })
+        : mode === "local"
+          ? localContext({ cwd: resolvedCwd, developmentRef })
+          : { mode: "contract", ok: true };
+    const checks = [...consumer.checks];
+    if (mode !== "contract")
+      checks.push(
+        workCheck(
+          "agent-entry.work-context",
+          context.ok,
+          context.message,
+          `Use a work branch containing origin/${developmentRef} and target that development channel`,
+        ),
+      );
+    return {
+      ...consumer,
+      contract: PAPER_AGENT_ENTRY_CONTRACT,
+      mode,
+      context,
+      checks,
+      ok: checks.every((check) => check.status === "pass"),
+      nextActions: checks
+        .filter((check) => check.status === "fail")
+        .map((check) => ({
+          id: `repair-${check.id}`,
+          command:
+            check.correctiveCommand || "buildchain paper preflight --json",
+          description: check.message,
+        })),
+    };
+  }
   const source = readJson(path.resolve(resolvedCwd, PAPER_PATHS.agentEntry));
   const entry = source.value || {};
   const packageJson =