@kungfu-tech/buildchain 4.0.2-alpha.8 → 4.0.2

package/scripts/workflow-taxonomy.mjs

@@ -0,0 +1,507 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import {
+  parseWorkflowDocument,
+  parseYamlUses,
+} from "../packages/core/workflow-yaml-contract.js";
+
+export const TAXONOMY_PATH = "architecture/workflow-taxonomy.json";
+export const TAXONOMY_DOC = "docs/workflow-catalog.md";
+const ROLES = ["public", "component", "self"];
+const CATEGORIES = ["build", "release", "ops"];
+const SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
+const WORKFLOW = /^\.github\/workflows\/[.a-z0-9-]+\.ya?ml$/u;
+const VERSION_TOKEN = /(?:^|[.-])v\d+(?:[.-]|$)/iu;
+const PROTECTED = [
+  TAXONOMY_PATH,
+  "scripts/workflow-taxonomy.mjs",
+  "scripts/check-workflow-taxonomy.mjs",
+  "scripts/generate-workflow-taxonomy.mjs",
+  "scripts/check-workflows.sh",
+  "tests/workflow-taxonomy.test.mjs",
+  ".github/workflows/self-build-verify.yml",
+  "package.json",
+  ".buildchain/buildchain.toml",
+];
+
+export function workflowPath(entry) {
+  const prefix = entry.role === "component" ? "." : `${entry.role}-`;
+  return `.github/workflows/${prefix}${entry.category}-${entry.purpose}.yml`;
+}
+
+export function readWorkflowTaxonomy(root) {
+  const file = path.join(root, TAXONOMY_PATH);
+  return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null;
+}
+
+function validateEntryRole(entry, errors) {
+  if (!ROLES.includes(entry.role)) errors.push(`${entry.id}: invalid role`);
+  if (!CATEGORIES.includes(entry.category))
+    errors.push(`${entry.id}: invalid category`);
+  if (!SLUG.test(entry.purpose || ""))
+    errors.push(`${entry.id}: invalid purpose slug`);
+  if (VERSION_TOKEN.test(path.posix.basename(workflowPath(entry))))
+    errors.push(
+      `${entry.id}: workflow filenames cannot contain version tokens`,
+    );
+  for (const field of ["summary", "owner", "rationale"]) {
+    if (typeof entry[field] !== "string" || !entry[field].trim())
+      errors.push(`${entry.id}: missing ${field}`);
+  }
+  if (!["active", "preview", "compatibility", "retired"].includes(entry.status))
+    errors.push(`${entry.id}: invalid lifecycle status`);
+  if (
+    !["reusable", "dispatch-service", "repository"].includes(entry.invocation)
+  )
+    errors.push(`${entry.id}: invalid invocation`);
+  if ((entry.role === "self") !== (entry.invocation === "repository"))
+    errors.push(`${entry.id}: role and invocation disagree`);
+  if (entry.role === "component" && entry.invocation !== "reusable")
+    errors.push(`${entry.id}: component must be reusable`);
+}
+
+function validateMigration(policy, entry, declared, errors) {
+  if (entry.retiredAlias) {
+    if (
+      entry.compatibility ||
+      entry.retiredAlias.path !== entry.migration?.previousPath ||
+      !entry.retiredAlias.reason?.trim() ||
+      entry.retiredAlias.migrationGuide !== "docs/workflow-path-migration.md"
+    )
+      errors.push(`${entry.id}: invalid alias retirement record`);
+  }
+  if (entry.migration) {
+    if (
+      !WORKFLOW.test(entry.migration.previousPath || "") ||
+      !/^[a-f0-9]{64}$/u.test(entry.migration.originalSha256 || "")
+    )
+      errors.push(`${entry.id}: invalid exact migration identity`);
+    if (
+      policy.migrationSources?.[entry.migration.previousPath] !==
+      entry.migration.originalSha256
+    )
+      errors.push(
+        `${entry.id}: migration source is not in the reviewed baseline`,
+      );
+  }
+  if (entry.compatibility) {
+    const alias = entry.compatibility;
+    if (VERSION_TOKEN.test(path.posix.basename(alias.path || "")))
+      errors.push(
+        `${entry.id}: version-prefixed compatibility aliases are retired`,
+      );
+    if (entry.role === "self")
+      errors.push(
+        `${entry.id}: repository event wrappers cannot have duplicate aliases`,
+      );
+    if (
+      !WORKFLOW.test(alias.path || "") ||
+      alias.path !== entry.migration?.previousPath
+    )
+      errors.push(
+        `${entry.id}: compatibility must name one exact migrated path`,
+      );
+    if (!alias.reason?.trim() || !alias.removalCondition?.trim())
+      errors.push(
+        `${entry.id}: compatibility requires a reason and removal condition`,
+      );
+    declared.push(alias.path);
+  }
+}
+
+function validateEntries(policy, errors) {
+  if (policy?.schema !== "buildchain.workflow-taxonomy/v1")
+    errors.push("taxonomy schema is missing or unknown");
+  if (JSON.stringify(policy?.roles) !== JSON.stringify(ROLES))
+    errors.push("role vocabulary must be public/component/self");
+  if (JSON.stringify(policy?.categories) !== JSON.stringify(CATEGORIES))
+    errors.push("category vocabulary must be build/release/ops");
+  if (!/^[a-f0-9]{40}$/u.test(policy?.migrationBaseRevision || ""))
+    errors.push("migration baseline must be an exact commit");
+  if (!Array.isArray(policy?.entries) || !policy.entries.length) {
+    errors.push("taxonomy entries are missing");
+    return [];
+  }
+  const ids = new Set();
+  const paths = new Set();
+  for (const entry of policy.entries) {
+    if (!entry.id || ids.has(entry.id))
+      errors.push(`duplicate or missing identity: ${entry.id}`);
+    ids.add(entry.id);
+    validateEntryRole(entry, errors);
+    const canonical = workflowPath(entry);
+    const declared = [canonical];
+    validateMigration(policy, entry, declared, errors);
+    for (const file of declared) {
+      if (!WORKFLOW.test(file) || paths.has(file))
+        errors.push(`${entry.id}: invalid or duplicate path ${file}`);
+      paths.add(file);
+    }
+  }
+  return policy.entries;
+}
+
+export function discoverWorkflowFiles(root) {
+  const directory = path.join(root, ".github/workflows");
+  if (!fs.existsSync(directory)) return [];
+  const visit = (dir) =>
+    fs.readdirSync(dir, { withFileTypes: true }).flatMap((item) => {
+      const file = path.join(dir, item.name);
+      if (item.isDirectory()) return visit(file);
+      return /\.ya?ml$/iu.test(item.name)
+        ? [path.relative(root, file).split(path.sep).join("/")]
+        : [];
+    });
+  return visit(directory).sort();
+}
+
+function validateRepositoryReferences(file, document, text, declared, errors) {
+  const references = document.callJobs.flatMap((job) =>
+    Object.entries(job.with)
+      .filter(
+        ([key, value]) =>
+          /(?:source|handoff)-workflow-id$|(?:expected|candidate)-workflow-file$/u.test(
+            key,
+          ) && value.kind === "string",
+      )
+      .map(([, value]) => value.value),
+  );
+  for (const match of text.matchAll(
+    /\bgh workflow run ([.a-z0-9-]+\.ya?ml)\b/gu,
+  ))
+    references.push(match[1]);
+  for (const name of references) {
+    const target = name.startsWith(".github/")
+      ? name
+      : `.github/workflows/${name}`;
+    if (!declared.has(target))
+      errors.push(`${file}: dangling repository workflow reference ${name}`);
+  }
+}
+
+function validateWorkflow(root, entry, declared, errors) {
+  const file = workflowPath(entry);
+  const absolute = path.join(root, file);
+  if (!fs.existsSync(absolute) || !fs.lstatSync(absolute).isFile()) return;
+  const text = fs.readFileSync(absolute, "utf8");
+  if (
+    entry.retiredAlias &&
+    text.includes("BUILDCHAIN_INVOKED_WORKFLOW:") &&
+    !text.includes(`BUILDCHAIN_INVOKED_WORKFLOW: ${file}\n`)
+  )
+    errors.push(
+      `${file}: consumer admission must bind the canonical invoked workflow`,
+    );
+  const document = parseWorkflowDocument(text);
+  if (entry.role === "self")
+    validateRepositoryReferences(file, document, text, declared, errors);
+  const reusable = document.triggers.includes("workflow_call");
+  if ((entry.invocation === "reusable") !== reusable)
+    errors.push(`${file}: workflow_call does not match registered invocation`);
+  if (
+    entry.invocation === "dispatch-service" &&
+    !document.triggers.includes("workflow_dispatch")
+  )
+    errors.push(`${file}: dispatch service lacks workflow_dispatch`);
+  if (
+    entry.role !== "self" &&
+    document.triggers.some(
+      (trigger) => !["workflow_call", "workflow_dispatch"].includes(trigger),
+    )
+  )
+    errors.push(
+      `${file}: public/component entry has repository event triggers`,
+    );
+  if (entry.compatibility) {
+    const alias = path.join(root, entry.compatibility.path);
+    if (fs.existsSync(alias) && fs.readFileSync(alias, "utf8") !== text)
+      errors.push(
+        `${file}: compatibility implementation drift at ${entry.compatibility.path}`,
+      );
+  }
+  for (const call of parseYamlUses(text)) {
+    const remote = call.value.match(
+      /^kungfu-systems\/buildchain\/(\.github\/workflows\/[^@]+)@/u,
+    );
+    if (remote && VERSION_TOKEN.test(path.posix.basename(remote[1])))
+      errors.push(
+        `${file}:${call.line}: retired version-prefixed workflow call ${remote[1]}`,
+      );
+    const local = call.value.match(/^\.\/(\.github\/workflows\/[^@]+)$/u);
+    if (local && !declared.has(local[1]))
+      errors.push(
+        `${file}:${call.line}: dangling workflow reference ${local[1]}`,
+      );
+  }
+}
+
+function validateGateIntegration(root, errors) {
+  const read = (file) =>
+    fs.existsSync(path.join(root, file))
+      ? fs.readFileSync(path.join(root, file), "utf8")
+      : "";
+  const pkg = JSON.parse(read("package.json") || "{}");
+  const command = pkg.scripts?.["check:workflows"];
+  if (
+    command !==
+    "node scripts/check-workflow-taxonomy.mjs && bash scripts/check-workflows.sh"
+  )
+    errors.push(
+      "check:workflows must execute taxonomy before actionlint without a bypass",
+    );
+  if (
+    !/(?:^|&&)\s*pnpm run check:workflows\s*(?:&&|$)/u.test(
+      pkg.scripts?.check || "",
+    )
+  )
+    errors.push("required check chain does not enforce check:workflows");
+  const { parse: parseToml } = createRequire(import.meta.url)("smol-toml");
+  const config = parseToml(read(".buildchain/buildchain.toml"));
+  if (
+    !config.lifecycle?.verify?.commands?.includes(
+      "corepack pnpm@11.7.0 run check",
+    )
+  )
+    errors.push(
+      "declared verify lifecycle must execute the full required check",
+    );
+  const verify = read(".github/workflows/self-build-verify.yml");
+  const document = parseWorkflowDocument(verify);
+  for (const trigger of ["pull_request", "merge_group", "push"]) {
+    if (!document.triggers.some((item) => item.split(":")[0] === trigger))
+      errors.push(`required Verify workflow lacks ${trigger}`);
+  }
+  if (
+    !verify.includes("Run declared verify lifecycle") ||
+    !verify.includes("--required")
+  )
+    errors.push("required Verify lifecycle integration is missing");
+  const owners = read(".github/CODEOWNERS")
+    .split(/\r?\n/u)
+    .map((line) => line.trim());
+  for (const file of PROTECTED) {
+    if (!owners.includes(`/${file} @kungfu-origin`))
+      errors.push(`independent review ownership missing for ${file}`);
+  }
+  if (
+    !owners.includes("/.github/workflows/* @kungfu-origin") ||
+    !owners.includes("/.github/CODEOWNERS @kungfu-origin")
+  )
+    errors.push(
+      "workflow and CODEOWNERS review ownership must remain explicit",
+    );
+}
+
+export function checkWorkflowTaxonomy(
+  root,
+  { integration = true, documentation = true } = {},
+) {
+  const errors = [];
+  const policy = readWorkflowTaxonomy(root);
+  const entries = validateEntries(policy, errors);
+  if (errors.length) return { ok: false, errors };
+  const declared = new Set(
+    entries.flatMap((entry) => [
+      workflowPath(entry),
+      ...(entry.compatibility ? [entry.compatibility.path] : []),
+    ]),
+  );
+  const observed = new Set(discoverWorkflowFiles(root));
+  for (const file of observed) {
+    if (VERSION_TOKEN.test(path.posix.basename(file)))
+      errors.push(`workflow filenames cannot contain version tokens: ${file}`);
+    if (!declared.has(file)) errors.push(`unregistered workflow: ${file}`);
+    if (!fs.lstatSync(path.join(root, file)).isFile())
+      errors.push(`workflow must be a regular file: ${file}`);
+  }
+  for (const file of declared)
+    if (!observed.has(file))
+      errors.push(`registered workflow missing: ${file}`);
+  for (const entry of entries) validateWorkflow(root, entry, declared, errors);
+  if (integration) validateGateIntegration(root, errors);
+  if (documentation) {
+    const file = path.join(root, TAXONOMY_DOC);
+    if (
+      !fs.existsSync(file) ||
+      fs.readFileSync(file, "utf8") !== renderWorkflowCatalog(policy)
+    )
+      errors.push("generated workflow catalog is stale");
+  }
+  return {
+    ok: errors.length === 0,
+    canonicalCount: entries.length,
+    compatibilityCount: entries.filter((entry) => entry.compatibility).length,
+    fileCount: observed.size,
+    errors,
+  };
+}
+
+// Existing lane/debt baselines name immutable pre-migration identities. Count
+// one logical implementation only after proving every physical alias identical.
+export function projectWorkflowIdentities(root, workflows) {
+  const policy = readWorkflowTaxonomy(root);
+  if (!policy) return workflows;
+  const result = checkWorkflowTaxonomy(root, {
+    integration: false,
+    documentation: false,
+  });
+  if (!result.ok) throw new Error(result.errors.join("\n"));
+  const byPath = new Map(
+    workflows.map((workflow) => [workflow.path, workflow]),
+  );
+  return policy.entries
+    .map((entry) => {
+      const workflow = byPath.get(workflowPath(entry));
+      if (!workflow)
+        throw new Error(`missing canonical workflow: ${workflowPath(entry)}`);
+      return {
+        ...workflow,
+        path: entry.migration?.previousPath || workflow.path,
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function writeWorkflowSource(root, relative, text) {
+  const policy = readWorkflowTaxonomy(root);
+  const entry = policy?.entries.find(
+    (item) =>
+      workflowPath(item) === relative || item.compatibility?.path === relative,
+  );
+  if (policy?.entries.some((item) => item.retiredAlias?.path === relative))
+    throw new Error(`${relative}: cannot regenerate a retired workflow alias`);
+  const outputs = entry
+    ? [
+        workflowPath(entry),
+        ...(entry.compatibility ? [entry.compatibility.path] : []),
+      ]
+    : [relative];
+  for (const file of outputs) fs.writeFileSync(path.join(root, file), text);
+}
+
+export function rewriteRepositoryWorkflowPaths(root, text) {
+  for (const entry of readWorkflowTaxonomy(root)?.entries || []) {
+    if (entry.role === "self" && entry.migration)
+      text = text.replaceAll(entry.migration.previousPath, workflowPath(entry));
+    if (entry.retiredAlias)
+      text = text.replaceAll(entry.retiredAlias.path, workflowPath(entry));
+    if (entry.id === "build-surface-fixture")
+      text = text.replaceAll(
+        "build-surface-fixture.yml",
+        path.posix.basename(workflowPath(entry)),
+      );
+  }
+  return text;
+}
+
+// Historical inventories and debt ledgers retain their original identity. File
+// access resolves only explicitly retired aliases to the registered implementation.
+export function currentWorkflowPath(root, relative) {
+  const entry = readWorkflowTaxonomy(root)?.entries.find(
+    (item) => item.retiredAlias?.path === relative,
+  );
+  return entry ? workflowPath(entry) : relative;
+}
+
+export function workflowCompatibilityIdentity(root, relative, text) {
+  const entry = readWorkflowTaxonomy(root)?.entries.find(
+    (item) => workflowPath(item) === relative && item.compatibility,
+  );
+  if (!entry) return relative;
+  const source = text ?? fs.readFileSync(path.join(root, relative), "utf8");
+  if (
+    source !==
+    fs.readFileSync(path.join(root, entry.compatibility.path), "utf8")
+  )
+    throw new Error(`${relative}: compatibility implementation drift`);
+  return entry.compatibility.path;
+}
+
+export function renderWorkflowCatalog(policy) {
+  const lines = [
+    "---",
+    "status: active",
+    "period: ongoing",
+    "theme: workflow-taxonomy",
+    "doc_type: technical-reference",
+    "source_level: local-files",
+    "confidence: high",
+    "sensitivity: public",
+    "evidence_grade: B",
+    "review_state: unreviewed",
+    "last_reviewed: 2026-09-05",
+    "ai_provenance:",
+    "  model_family: GPT-6",
+    "  product: Codex",
+    "  generated_at: 2026-09-05",
+    "  visible_context: Repository workflow source and the approved naming scheme",
+    "  invisible_context_boundary: No credentials or unpublished provider configuration inspected",
+    "---",
+    "",
+    "# Workflow catalog",
+    "",
+    "Generated from `architecture/workflow-taxonomy.json`; edit that source, then run",
+    "`pnpm run generate:workflows`. Every YAML file, including compatibility paths,",
+    "is checked by the existing required workflow check.",
+    "",
+    "## Naming and ownership",
+    "",
+    "`public-<build|release|ops>-<purpose>.yml` is a consumer entry;",
+    "`.<build|release|ops>-<purpose>.yml` is an advanced component;",
+    "`self-<build|release|ops>-<purpose>.yml` is Buildchain's own automation.",
+    "Public is a product role, not GitHub access control. Dispatch services are",
+    "marked separately from reusable workflows. Keep workflow names, job IDs,",
+    "permissions, and trigger semantics stable during path migration.",
+    "",
+    "## Channel rollout",
+    "",
+    "Canonical names become callable on a channel only after that channel publishes",
+    "them. Existing `@v4`/`@v4-alpha` consumers keep their exact registered legacy",
+    "paths until provider readback proves canonical availability. New examples below",
+    "describe the target surface, not a claim that both channels already publish it.",
+    "Compatibility files are generated byte-identical projections, not independently",
+    "editable implementations. They retain full jobs to preserve called-workflow",
+    "identity, permission envelopes, and required check names without extra nesting.",
+    "",
+    "The controller registry records the actual source path separately from a migrated",
+    "repository controller contractPath. This preserves the established logical",
+    "contract identity while exposing its current execution source. New workflows",
+    "do not acquire historical identities. Public controllers retain their real",
+    "compatibility paths while those paths remain supported.",
+    "",
+    "## Adding or changing a workflow",
+    "",
+    "Register a stable identity, role, category, purpose, owner, lifecycle status,",
+    "invocation and concrete summary before creating its derived path. A new entry",
+    "must explain its scope in review. New aliases cannot be invented: compatibility",
+    "must name an exact migration source with a reason and removal condition.",
+    "The policy, generator, checker, tests, required CI chain and CODEOWNERS require",
+    "independent `kungfu-origin` review. No wildcard compatibility admission is allowed.",
+    "Workflow filenames cannot contain version tokens such as `v4` or `v5`.",
+    "Retired aliases cannot be recreated or called; see [path migration](workflow-path-migration.md).",
+    "",
+    "A role, category or implementation edit must preserve or deliberately update",
+    "all related declarations. Run `pnpm run generate:workflows` and",
+    "`pnpm run check:workflows`; the full `pnpm run check` remains required.",
+    "",
+  ];
+  for (const role of ROLES) {
+    lines.push(
+      `## ${role}`,
+      "",
+      "| Canonical workflow | Category | Invocation | Status | Purpose | Compatibility path |",
+      "| --- | --- | --- | --- | --- | --- |",
+    );
+    for (const entry of policy.entries
+      .filter((item) => item.role === role)
+      .sort((a, b) => workflowPath(a).localeCompare(workflowPath(b)))) {
+      const name = path.posix.basename(workflowPath(entry));
+      lines.push(
+        `| [${name}](../${workflowPath(entry)}) | ${entry.category} | ${entry.invocation} | ${entry.status} | ${entry.summary.replaceAll("|", "\\|")} | ${entry.compatibility ? `\`${path.posix.basename(entry.compatibility.path)}\`` : "—"} |`,
+      );
+    }
+    lines.push("");
+  }
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/templates/native-dev-delivery.yml

@@ -38,11 +38,8 @@ on:
       source-patch-root:
         description: "Semantic patch root"
         required: true
-      assignment-root:
-        description: "Native Assignment root"
-        required: true
-      initiative-root:
-        description: "Parent Initiative root"
+      native-roots-json:
+        description: "Machine-supplied Work sourceRoot or historical root pair"
         required: true
       plan-root:
         description: "Native qualification plan root"
@@ -117,8 +114,8 @@ jobs:
       delivery-warrant-mode: required
       handoff-workflow-id: native-dev-delivery.yml
       source-workflow-id: ${{ inputs.source-workflow-id || '' }}
-      assignment-root: ${{ github.event.client_payload.candidate.assignmentRoot || inputs.assignment-root }}
-      initiative-root: ${{ github.event.client_payload.candidate.initiativeRoot || inputs.initiative-root }}
+      assignment-root: ${{ github.event.client_payload.candidate.assignmentRoot || fromJSON(inputs.native-roots-json || '{}').assignmentRoot || '' }}
+      initiative-root: ${{ github.event.client_payload.candidate.initiativeRoot || fromJSON(inputs.native-roots-json || '{}').initiativeRoot || '' }}
       source-identity-root: ${{ github.event.client_payload.candidate.sourceIdentityRoot || inputs.source-identity-root }}
       source-patch-root: ${{ github.event.client_payload.candidate.sourcePatchRoot || inputs.source-patch-root }}
       plan-root: ${{ github.event.client_payload.candidate.planRoot || inputs.plan-root }}