@kungfu-tech/buildchain 3.0.6 → 3.0.7-alpha.1

package/scripts/engineering-housekeeper-workflow.mjs

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import {
+  GitHubHousekeeperClient,
+  applyGitHubHousekeeperPlan,
+  collectGitHubHousekeeperInventory,
+} from "../packages/core/engineering-housekeeper-github.js";
+
+const VALID_MODES = new Set(["report", "apply"]);
+const VALID_SCOPES = new Set(["branches", "pull-requests"]);
+const DEFAULT_OUTPUT_DIRECTORY = ".buildchain/engineering-housekeeper";
+
+function requiredString(value, field) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${field} is required`);
+  return normalized;
+}
+
+function boolOption(value, fallback = false) {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (typeof value === "boolean") return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) return true;
+  if (["0", "false", "no", "off"].includes(normalized)) return false;
+  throw new Error(`boolean input must be true or false, got: ${value}`);
+}
+
+function positiveInteger(value, fallback, field) {
+  const selected =
+    value === undefined || value === "" ? fallback : Number(value);
+  if (!Number.isInteger(selected) || selected < 1) {
+    throw new Error(`${field} must be a positive integer`);
+  }
+  return selected;
+}
+
+function splitPatterns(value, fallback) {
+  const normalized = String(value || "").trim();
+  if (!normalized) return [...fallback];
+  return [
+    ...new Set(
+      normalized
+        .split(/[\n,]+/)
+        .map((entry) => entry.trim())
+        .filter(Boolean),
+    ),
+  ].sort();
+}
+
+function normalizeRepository(value) {
+  const repository = requiredString(value, "repository");
+  if (!/^[^/\s]+\/[^/\s]+$/.test(repository)) {
+    throw new Error(`repository must be owner/repo, got: ${repository}`);
+  }
+  return repository;
+}
+
+function normalizeMode(value) {
+  const mode = String(value || "report")
+    .trim()
+    .toLowerCase();
+  if (!VALID_MODES.has(mode)) {
+    throw new Error(`mode must be report or apply, got: ${value || "<empty>"}`);
+  }
+  return mode;
+}
+
+export function normalizeHousekeeperWorkflowOptions(options = {}) {
+  const mode = normalizeMode(options.mode ?? process.env.HOUSEKEEPER_MODE);
+  const applyEnabled = boolOption(
+    options.applyEnabled ?? process.env.HOUSEKEEPER_APPLY_ENABLED,
+    false,
+  );
+  if (mode === "apply" && !applyEnabled) {
+    throw new Error("apply mode requires apply-enabled=true");
+  }
+  if (mode === "report" && applyEnabled) {
+    throw new Error("apply-enabled=true is only valid when mode=apply");
+  }
+  return {
+    mode,
+    applyEnabled,
+    repository: normalizeRepository(
+      options.repository ||
+        process.env.HOUSEKEEPER_REPOSITORY ||
+        process.env.GITHUB_REPOSITORY,
+    ),
+    targetBranch: requiredString(
+      options.targetBranch || process.env.HOUSEKEEPER_TARGET_BRANCH,
+      "target-branch",
+    ).replace(/^refs\/heads\//, ""),
+    staleDays: positiveInteger(
+      options.staleDays ?? process.env.HOUSEKEEPER_STALE_DAYS,
+      30,
+      "stale-days",
+    ),
+    maxActions: positiveInteger(
+      options.maxActions ?? process.env.HOUSEKEEPER_MAX_ACTIONS,
+      20,
+      "max-actions",
+    ),
+    protectedPatterns: splitPatterns(
+      options.protectedPatterns ?? process.env.HOUSEKEEPER_PROTECTED_PATTERNS,
+      ["dev/**", "alpha/**", "release/**", "publish-gate/**"],
+    ),
+    retainedPatterns: splitPatterns(
+      options.retainedPatterns ?? process.env.HOUSEKEEPER_RETAINED_PATTERNS,
+      ["train/**", "authority/**"],
+    ),
+    stalePullRequestLabel: String(
+      options.stalePullRequestLabel ??
+        process.env.HOUSEKEEPER_STALE_PR_LABEL ??
+        "",
+    ).trim(),
+    observedAt: String(
+      options.observedAt ||
+        process.env.HOUSEKEEPER_OBSERVED_AT ||
+        new Date().toISOString(),
+    ),
+    appliedAt: String(
+      options.appliedAt ||
+        process.env.HOUSEKEEPER_APPLIED_AT ||
+        new Date().toISOString(),
+    ),
+    outputDirectory: path.resolve(
+      String(
+        options.outputDirectory ||
+          process.env.HOUSEKEEPER_OUTPUT_DIRECTORY ||
+          DEFAULT_OUTPUT_DIRECTORY,
+      ),
+    ),
+  };
+}
+
+function workflowPolicy(options) {
+  return {
+    protectedPatterns: options.protectedPatterns,
+    retainedPatterns: options.retainedPatterns,
+    pullRequests: {
+      reportStale: true,
+      label: options.stalePullRequestLabel,
+      autoClose: false,
+    },
+  };
+}
+
+function actionIdentity(action) {
+  return action.name
+    ? `${action.kind}:${action.name}`
+    : `${action.kind}:#${action.number}`;
+}
+
+function decisionFor(entry) {
+  if (entry.kind === "branch") return entry.decision;
+  return entry.actions.length > 0 ? entry.actions.join(",") : "report-only";
+}
+
+export function renderHousekeeperWorkflowReport(
+  plan,
+  receipt,
+  { mode, scope = "all" } = {},
+) {
+  const lines = [
+    "## Engineering Housekeeper",
+    "",
+    `Mode: \`${mode || "report"}\``,
+    `Scope: \`${scope}\``,
+    `Repository: \`${plan.repository}\``,
+    `Target ref: \`${plan.target.name}@${plan.target.headOid}\``,
+    `Observed at: \`${plan.observedAt}\``,
+    `Plan root: \`${plan.planRoot}\``,
+    `Receipt root: \`${receipt.receiptRoot}\``,
+    "",
+    "### Decisions",
+    "",
+    "| Subject | Observed ref | Decision | Reason codes |",
+    "| --- | --- | --- | --- |",
+  ];
+  for (const entry of plan.inventory) {
+    const subject =
+      entry.kind === "branch" ? entry.name : `PR #${entry.number}`;
+    lines.push(
+      `| \`${subject}\` | \`${entry.headOid}\` | ${decisionFor(entry)} | \`${entry.reasonCodes.join(",")}\` |`,
+    );
+  }
+  if (plan.inventory.length === 0)
+    lines.push("| - | - | retain | `inventory.empty` |");
+  lines.push(
+    "",
+    "### Outcomes",
+    "",
+    "| Action | Outcome | Details |",
+    "| --- | --- | --- |",
+  );
+  for (const outcome of receipt.outcomes) {
+    const details =
+      outcome.reasonCodes?.join(",") || outcome.providerError?.operation || "-";
+    lines.push(
+      `| \`${outcome.action}\` | ${outcome.status} | \`${details}\` |`,
+    );
+  }
+  if (receipt.outcomes.length === 0)
+    lines.push("| - | no-op | `no-actions-in-scope` |");
+  return `${lines.join("\n")}\n`;
+}
+
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function writeText(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, value);
+}
+
+function writeOutputs(outputs, outputFile = process.env.GITHUB_OUTPUT) {
+  if (!outputFile) return;
+  const lines = Object.entries(outputs).map(
+    ([key, value]) => `${key}=${String(value).replace(/\n/g, "%0A")}`,
+  );
+  fs.appendFileSync(outputFile, `${lines.join("\n")}\n`);
+}
+
+function appendSummary(
+  markdown,
+  summaryFile = process.env.GITHUB_STEP_SUMMARY,
+) {
+  if (summaryFile) fs.appendFileSync(summaryFile, markdown);
+  else process.stdout.write(markdown);
+}
+
+export async function createHousekeeperWorkflowPlan(
+  optionsInput = {},
+  clientInput,
+) {
+  const options = normalizeHousekeeperWorkflowOptions(optionsInput);
+  const client =
+    clientInput ||
+    new GitHubHousekeeperClient({
+      token: requiredString(process.env.GITHUB_TOKEN, "GitHub token"),
+    });
+  const plan = await collectGitHubHousekeeperInventory({
+    client,
+    repository: options.repository,
+    targetBranch: options.targetBranch,
+    observedAt: options.observedAt,
+    staleDays: options.staleDays,
+    policy: workflowPolicy(options),
+  });
+  const receipt = await applyGitHubHousekeeperPlan({
+    client,
+    plan,
+    dryRun: true,
+    appliedAt: options.appliedAt,
+    staleDays: options.staleDays,
+    maxActions: options.maxActions,
+  });
+  return { options, plan, receipt };
+}
+
+export function selectHousekeeperActions(plan, scope, maxActions) {
+  if (!VALID_SCOPES.has(scope))
+    throw new Error(`scope must be branches or pull-requests, got: ${scope}`);
+  return plan.actions
+    .slice(0, positiveInteger(maxActions, 20, "max-actions"))
+    .filter((action) =>
+      scope === "branches"
+        ? action.kind === "delete-branch"
+        : action.kind.endsWith("-pull-request"),
+    );
+}
+
+export async function applyHousekeeperWorkflowScope({
+  options: optionsInput = {},
+  plan,
+  scope,
+  client: clientInput,
+}) {
+  const options = normalizeHousekeeperWorkflowOptions(optionsInput);
+  if (options.mode !== "apply" || !options.applyEnabled) {
+    throw new Error("scope apply requires mode=apply and apply-enabled=true");
+  }
+  if (
+    plan.repository !== options.repository ||
+    plan.target.name !== options.targetBranch
+  ) {
+    throw new Error(
+      "plan repository or target branch does not match current workflow inputs",
+    );
+  }
+  const client =
+    clientInput ||
+    new GitHubHousekeeperClient({
+      token: requiredString(process.env.GITHUB_TOKEN, "GitHub token"),
+    });
+  const scopedPlan = {
+    ...plan,
+    actions: selectHousekeeperActions(plan, scope, options.maxActions),
+  };
+  const receipt = await applyGitHubHousekeeperPlan({
+    client,
+    plan: scopedPlan,
+    dryRun: false,
+    appliedAt: options.appliedAt,
+    staleDays: options.staleDays,
+    maxActions: Math.max(1, scopedPlan.actions.length),
+  });
+  return { options, plan, scopedPlan, receipt };
+}
+
+async function planCommand() {
+  const result = await createHousekeeperWorkflowPlan();
+  const planPath = path.join(result.options.outputDirectory, "plan.json");
+  const reportPath = path.join(result.options.outputDirectory, "report.md");
+  const receiptPath = path.join(
+    result.options.outputDirectory,
+    "report-receipt.json",
+  );
+  const report = renderHousekeeperWorkflowReport(result.plan, result.receipt, {
+    mode: result.options.mode,
+  });
+  writeJson(planPath, result.plan);
+  writeJson(receiptPath, result.receipt);
+  writeText(reportPath, report);
+  appendSummary(report);
+  writeOutputs({
+    "plan-path": planPath,
+    "report-path": reportPath,
+    "report-receipt-path": receiptPath,
+    "plan-root": result.plan.planRoot,
+    "report-receipt-root": result.receipt.receiptRoot,
+    "action-count": result.plan.actions.length,
+    "branch-action-count": result.plan.actions.filter(
+      (action) => action.kind === "delete-branch",
+    ).length,
+    "pull-request-action-count": result.plan.actions.filter((action) =>
+      action.kind.endsWith("-pull-request"),
+    ).length,
+    outcome:
+      result.plan.actions.length === 0
+        ? "no-actions"
+        : `${result.options.mode}-ready`,
+  });
+}
+
+async function applyCommand(scope) {
+  const planPath = path.resolve(
+    requiredString(process.env.HOUSEKEEPER_PLAN_PATH, "HOUSEKEEPER_PLAN_PATH"),
+  );
+  const plan = JSON.parse(fs.readFileSync(planPath, "utf8"));
+  const result = await applyHousekeeperWorkflowScope({ plan, scope });
+  const receiptPath = path.join(
+    result.options.outputDirectory,
+    `${scope}-receipt.json`,
+  );
+  const reportPath = path.join(
+    result.options.outputDirectory,
+    `${scope}-report.md`,
+  );
+  const report = renderHousekeeperWorkflowReport(result.plan, result.receipt, {
+    mode: result.options.mode,
+    scope,
+  });
+  writeJson(receiptPath, result.receipt);
+  writeText(reportPath, report);
+  appendSummary(report);
+  writeOutputs({
+    "receipt-path": receiptPath,
+    "report-path": reportPath,
+    "receipt-root": result.receipt.receiptRoot,
+    "outcome-count": result.receipt.outcomes.length,
+    "selected-action-count": result.scopedPlan.actions.length,
+    outcome: result.scopedPlan.actions.length === 0 ? "no-actions" : "applied",
+  });
+}
+
+async function main() {
+  const command = process.argv[2];
+  if (command === "plan") return planCommand();
+  if (command === "apply")
+    return applyCommand(requiredString(process.argv[3], "scope"));
+  throw new Error(
+    "usage: engineering-housekeeper-workflow.mjs plan | apply <branches|pull-requests>",
+  );
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}

package/scripts/generate-channel-promotion-workflow.mjs

@@ -20,6 +20,7 @@ const internalInputs = new Set([
   "promotion-publication-channel",
   "promotion-target-ref",
   "promotion-override-used",
+  "publication-authority-workflow-path",
 ]);
 
 function blockBetween(source, start, end) {
@@ -116,6 +117,9 @@ function forwardedInputs(inputNames, { includeInternal = true, unsupportedInputs
       if (name === "promotion-override-used") {
         return `      ${name}: \${{ needs.resolve-promotion.outputs.override-used == 'true' }}`;
       }
+      if (name === "publication-authority-workflow-path") {
+        return "      publication-authority-workflow-path: .github/workflows/.release-candidate-promote.yml";
+      }
       return routed
         ? `      ${name}: \${{ needs.resolve-promotion.outputs.${routed} }}`
         : `      ${name}: \${{ inputs.${name} }}`;
@@ -255,15 +259,13 @@ jobs:
             exit 1
           fi
 
-          remote_url="https://github.com/\${repository}.git"
-          refs="$(git ls-remote "\${remote_url}" "refs/heads/\${ref}" "refs/tags/\${ref}" "refs/tags/\${ref}^{}")"
-          head_sha="$(printf '%s\\n' "\${refs}" | awk -v name="refs/heads/\${ref}" '$2 == name { print tolower($1) }')"
-          tag_sha="$(printf '%s\\n' "\${refs}" | awk -v peeled="refs/tags/\${ref}^{}" -v name="refs/tags/\${ref}" '$2 == peeled { print tolower($1); found=1 } $2 == name && !found { fallback=tolower($1) } END { if (!found && fallback != "") print fallback }')"
-          if [[ -n "\${head_sha}" && -n "\${tag_sha}" && "\${head_sha}" != "\${tag_sha}" ]]; then
-            echo "::error::Promotion router ref is ambiguous between branch and tag"
-            exit 1
+          if [[ "\${ref}" =~ ^[0-9A-Fa-f]{40}$ ]]; then sha="\${ref,,}"; else
+            remote_url="https://github.com/\${repository}.git"; refs="$(git ls-remote "\${remote_url}" "refs/heads/\${ref}" "refs/tags/\${ref}" "refs/tags/\${ref}^{}")"
+            head_sha="$(printf '%s\\n' "\${refs}" | awk -v name="refs/heads/\${ref}" '$2 == name { print tolower($1) }')"
+            tag_sha="$(printf '%s\\n' "\${refs}" | awk -v peeled="refs/tags/\${ref}^{}" -v name="refs/tags/\${ref}" '$2 == peeled { print tolower($1); found=1 } $2 == name && !found { fallback=tolower($1) } END { if (!found && fallback != "") print fallback }')"
+            if [[ -n "\${head_sha}" && -n "\${tag_sha}" && "\${head_sha}" != "\${tag_sha}" ]]; then echo "::error::Promotion router ref is ambiguous between branch and tag"; exit 1; fi
+            sha="\${head_sha:-\${tag_sha}}"
           fi
-          sha="\${head_sha:-\${tag_sha}}"
           if [[ ! "\${sha}" =~ ^[0-9a-f]{40}$ ]]; then
             echo "::error::Promotion router ref did not resolve to one exact commit SHA"
             exit 1

package/scripts/generate-site-bundle.mjs

@@ -332,11 +332,16 @@ function capabilityGroup(id) {
   return id;
 }
 
-function publicSurfaceLifecycle({ owner, maturity, nonDuplicationRationale }) {
+function publicSurfaceLifecycle({
+  owner,
+  maturity,
+  nonDuplicationRationale,
+  introducedVersion = "pre-3.0.2-alpha.4",
+}) {
   return {
     owner,
     maturity,
-    introducedVersion: "pre-3.0.2-alpha.4",
+    introducedVersion,
     compatibilityPromise: "preserved-through-the-v3-major-line",
     deprecationReplacement: "",
     sunsetCondition: "explicit-breaking-change-review-in-a-future-major-line",
@@ -360,12 +365,16 @@ const manualMetaById = new Map(Object.entries({
   "auditable-demo": { capabilityGroup: "reusable-build", audience: ["consumer", "agent"], maturity: "preview", order: 207 },
   "binary-distribution": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "stable", order: 110 },
   "publish-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator"], maturity: "stable", order: 120 },
+  "release-tail-contract": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent", "maintainer"], maturity: "draft", order: 122 },
+  "release-tail-provider-plane": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent", "maintainer"], maturity: "preview", order: 123 },
+  "publication-rehearsal": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent", "maintainer"], maturity: "preview", order: 124 },
   "release-activation-transaction": { capabilityGroup: "release-passport-trust", audience: ["release-operator", "agent"], maturity: "preview", order: 125 },
   "release-candidate": { capabilityGroup: "reusable-build", audience: ["release-operator", "consumer"], maturity: "stable", order: 130 },
   "stable-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer"], maturity: "preview", order: 135 },
   "dev-qualification-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 136 },
   "dev-alpha-candidate-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 137 },
   "observed-evidence-patrol": { capabilityGroup: "governance-versioning", audience: ["release-operator", "consumer", "agent"], maturity: "preview", order: 140 },
+  "engineering-housekeeper": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer", "agent"], maturity: "preview", order: 145 },
   "reusable-build-surface": { capabilityGroup: "reusable-build", audience: ["consumer", "release-operator"], maturity: "stable", order: 200 },
   "lifecycle-protocol": { capabilityGroup: "reusable-build", audience: ["consumer", "developer"], maturity: "stable", order: 210 },
   "runtime-train-validation": { capabilityGroup: "governance-versioning", audience: ["maintainer", "consumer"], maturity: "stable", order: 220 },
@@ -514,16 +523,18 @@ function buildCapabilityRegistry({ docs, pages, cliRegistry, manualRegistry, nod
 
 function workflowCapabilityGroup(entry) {
   if (entry.id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
+  if (entry.id === "release-tail") return capabilityGroup("release-passport-trust");
   if (["web-surface", "release-propagation"].includes(entry.id)) return capabilityGroup("site-and-propagation");
   if (["build", "release-candidate-promote", "publication-artifact", "paper-release"].includes(entry.id)) return capabilityGroup("reusable-build");
   if (["buildchain-ref-promotion", "release-line-bootstrap"].includes(entry.id)) return capabilityGroup("release-passport-trust");
-  if (entry.id.includes("patrol") || entry.id.includes("dev-pr-auto-merge") || entry.id.includes("dev-delivery-warrant") || entry.id.includes("buildchain-dev-delivery")) return capabilityGroup("governance-versioning");
+  if (entry.id.includes("patrol") || entry.id.includes("housekeeper") || entry.id.includes("dev-pr-auto-merge") || entry.id.includes("dev-delivery-warrant") || entry.id.includes("buildchain-dev-delivery")) return capabilityGroup("governance-versioning");
   if (entry.status === "repository-internal" || entry.status === "compatibility-fixture") return capabilityGroup("api-cli-reference");
   return capabilityGroup("api-cli-reference");
 }
 
 function actionCapabilityGroup(id) {
   if (id === "github-artifact-attestation") return capabilityGroup("release-passport-trust");
+  if (id === "release-tail") return capabilityGroup("release-passport-trust");
   if (id === "promote-buildchain-ref") return capabilityGroup("release-passport-trust");
   if (id === "run-lifecycle" || id === "validate-config") return capabilityGroup("reusable-build");
   if (id === "report-buildchain-issue") return capabilityGroup("observability-diagnostics");
@@ -727,6 +738,7 @@ function buildSiteBundle() {
       "docs/dev-qualification-patrol.md",
       "docs/dev-alpha-candidate-patrol.md",
       "docs/observed-evidence-patrol.md",
+      "docs/engineering-housekeeper.md",
       "docs/release-governance.md",
       "docs/release-passport.md",
       "docs/controller-evidence.md",
@@ -776,6 +788,7 @@ function buildSiteBundle() {
         ["release-candidate-promote", "release-governance"],
         ["paper-release", "reusable-build"],
         ["release-propagation", "release-propagation"],
+        ["release-tail", "release-tail-provider-plane"],
         ["dev-pr-auto-merge", "dev-governance"],
         ["buildchain-dev-delivery", "dev-governance"],
         ["github-governance-audit", "dev-governance"],
@@ -785,6 +798,10 @@ function buildSiteBundle() {
         ["buildchain-patrol-daily", "repository-patrol"],
         ["buildchain-patrol-weekly", "repository-patrol"],
         ["buildchain-patrol-monthly", "repository-patrol"],
+        ["engineering-housekeeper", "repository-patrol"],
+        ["engineering-housekeeper-daily", "repository-patrol"],
+        ["engineering-housekeeper-weekly", "repository-patrol"],
+        ["engineering-housekeeper-monthly", "repository-patrol"],
         ["stable-candidate-patrol", "repository-patrol"],
         ["dev-qualification-patrol", "repository-patrol"],
         ["dev-alpha-candidate-patrol", "repository-patrol"],
@@ -802,8 +819,13 @@ function buildSiteBundle() {
         ["candidate-lab", "repository-internal"],
         ["build-surface-fixture", "repository-internal"],
         ["buildchain-stable-candidate-qualification", "repository-internal"],
+        ["engineering-housekeeper", "preview"],
+        ["engineering-housekeeper-daily", "preview"],
+        ["engineering-housekeeper-weekly", "preview"],
+        ["engineering-housekeeper-monthly", "preview"],
         ["self-hosted-runner-smoke", "compatibility-fixture"],
       ]);
+      const engineeringHousekeeper = entry.id.startsWith("engineering-housekeeper");
       return {
         ...entry,
         surface: surfaceById.get(entry.id) || (entry.path.includes("/.") ? "reusable-workflow" : "repository-workflow"),
@@ -815,7 +837,10 @@ function buildSiteBundle() {
         ...publicSurfaceLifecycle({
           owner: "buildchain-workflows",
           maturity: statusById.get(entry.id) || "active",
-          nonDuplicationRationale: "Existing workflow identity retained for caller compatibility and repository orchestration.",
+          introducedVersion: engineeringHousekeeper ? packageJson.version : undefined,
+          nonDuplicationRationale: engineeringHousekeeper
+            ? "One reusable policy and evidence boundary owns Engineering Housekeeper execution; scheduled callers contain cadence values only."
+            : "Existing workflow identity retained for caller compatibility and repository orchestration.",
         }),
       };
     }),
@@ -901,6 +926,9 @@ function buildSiteBundle() {
       "buildchain.release.json",
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
+      "schemas/publication-rehearsal-capsule-v1.schema.json",
+      "schemas/release-tail-capabilities-v1.schema.json",
+      "schemas/release-tail-provider-bindings-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/kfd-support-projection-v1.schema.json",
@@ -936,6 +964,9 @@ function buildSiteBundle() {
       "artifact-schemas.json",
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
+      "schemas/publication-rehearsal-capsule-v1.schema.json",
+      "schemas/release-tail-capabilities-v1.schema.json",
+      "schemas/release-tail-provider-bindings-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/kfd-support-projection-v1.schema.json",
@@ -1067,6 +1098,9 @@ function buildSiteBundle() {
       "artifact-schemas.json",
       "release-passport-check-manifest.json",
       "schemas/release-passport-v1.schema.json",
+      "schemas/publication-rehearsal-capsule-v1.schema.json",
+      "schemas/release-tail-capabilities-v1.schema.json",
+      "schemas/release-tail-provider-bindings-v1.schema.json",
       "schemas/kfd-agent-hub-adoption.schema.json",
       "schemas/kfd-product-gate-input-v1.schema.json",
       "schemas/kfd-support-projection-v1.schema.json",
@@ -1242,6 +1276,15 @@ function buildSiteBundle() {
     "artifact-schemas.json": artifactSchemas,
     "release-passport-check-manifest.json": createReleasePassportCheckManifest(),
     "schemas/release-passport-v1.schema.json": RELEASE_PASSPORT_SCHEMA,
+    "schemas/publication-rehearsal-capsule-v1.schema.json": readJson(
+      "contracts/publication-rehearsal-capsule-v1.schema.json",
+    ),
+    "schemas/release-tail-capabilities-v1.schema.json": readJson(
+      "contracts/release-tail-capabilities-v1.schema.json",
+    ),
+    "schemas/release-tail-provider-bindings-v1.schema.json": readJson(
+      "contracts/release-tail-provider-bindings-v1.schema.json",
+    ),
     "schemas/kfd-agent-hub-adoption.schema.json": KFD_AGENT_HUB_ADOPTION_SCHEMA,
     "schemas/kfd-product-gate-input-v1.schema.json": KFD_PRODUCT_GATE_INPUT_SCHEMA,
     "schemas/kfd-support-projection-v1.schema.json": KFD_SUPPORT_PROJECTION_SCHEMA,

package/scripts/init-repo.mjs

@@ -4,6 +4,12 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { BUILDCHAIN_CONFIG_PATH } from "../packages/core/buildchain-layout.js";
 import { detectPackageManager, assertPackageManager } from "../packages/core/package-manager.js";
+import {
+  PUBLICATION_REHEARSAL_WORKFLOW_PATH,
+  appendPublicationRehearsalToml,
+  mergePublicationRehearsalAgentInstructions,
+  publicationRehearsalWorkflow,
+} from "../packages/core/publication-rehearsal-projection.js";
 
 const BUILDCHAIN_WORKFLOW_REF = "kungfu-systems/buildchain/.github/workflows/.build.yml@v3";
 const DEFAULT_PUBLICATION_LATEX_IMAGE = "ghcr.io/kungfu-systems/build-images/latex-pdf-builder";
@@ -401,6 +407,13 @@ function writeIfAllowed(filePath, content, { force }) {
   return filePath;
 }
 
+function writeManagedAgentEntry(filePath, current) {
+  const content = mergePublicationRehearsalAgentInstructions(current);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return filePath;
+}
+
 export function initBuildchainRepo({
   cwd = process.cwd(),
   type = "package",
@@ -411,7 +424,7 @@ export function initBuildchainRepo({
 } = {}) {
   const resolvedCwd = path.resolve(cwd);
   const manager = detectOrDefaultPackageManager(resolvedCwd, packageManager);
-  const toml = (() => {
+  const toml = appendPublicationRehearsalToml((() => {
     if (type === "package") {
       return packageToml(resolvedCwd, manager);
     }
@@ -431,7 +444,12 @@ export function initBuildchainRepo({
       return anchoredPackageToml(resolvedCwd, manager);
     }
     throw new Error("init --type must be one of package, native, web-surface, infra-contract, publication-artifact, or anchored-package");
-  })();
+  })());
+
+  const agentsPath = path.join(resolvedCwd, "AGENTS.md");
+  const currentAgents = fs.existsSync(agentsPath)
+    ? fs.readFileSync(agentsPath, "utf8")
+    : "";
 
   const written = [
     writeIfAllowed(path.join(resolvedCwd, BUILDCHAIN_CONFIG_PATH), toml, { force }),
@@ -446,6 +464,12 @@ export function initBuildchainRepo({
           }),
       { force },
     ),
+    writeIfAllowed(
+      path.join(resolvedCwd, PUBLICATION_REHEARSAL_WORKFLOW_PATH),
+      publicationRehearsalWorkflow("v3"),
+      { force },
+    ),
+    writeManagedAgentEntry(agentsPath, currentAgents),
   ];
 
   if (type === "anchored-package" && !fs.existsSync(path.join(resolvedCwd, "release.json"))) {

package/scripts/inspect-artifact-signing-requests.mjs

@@ -82,6 +82,10 @@ export function inspectArtifactSigningRequests({
       if (seen.has(key))
         throw new Error(`duplicate artifact signing request: ${key}`);
       seen.add(key);
+      const {
+        entitlementsProfile = "none",
+        entitlementsPaths = [],
+      } = request.signature;
       const item = {
         id: request.artifact.id,
         slug: safeId(request.artifact.id),
@@ -104,6 +108,8 @@ export function inspectArtifactSigningRequests({
         sourceSha: request.source.sha,
         sourceTreeSha: request.source.treeSha,
         transportFormat: request.artifact.transport?.format || "",
+        entitlementsProfile,
+        entitlementsPaths: entitlementsPaths.join(","),
       };
       if (request.signature.profile === "detached-signature-v1")
         matrices.detached.push(item);