Buildchain Golden Path

status: active period: ongoing theme: buildchain-golden-path doc_type: technical-guide source_level: local-files confidence: high sensitivity: public evidence_grade: A review_state: self-reviewed last_reviewed: 2026-08-01 ai_provenance: model_family: GPT-5 product: Codex generated_at: 2026-08-01 invisible_context: not asserted

Buildchain Golden Path

This path is for a repository maintainer adopting Buildchain for the first time. It takes about 15–30 minutes and ends with five inspectable outcomes: an exact package pin, a declared project type, a valid local configuration, a thin reusable workflow caller, and a Release Passport inspection.

Use this page for the first successful pass. Move to the advanced manuals only after the local checks below are green.

1. Create a clean consumer and install an exact version

consumer_dir="$(mktemp -d)"
cd "$consumer_dir"
npm init -y
buildchain_version="$(npm view @kungfu-tech/buildchain version)"
pnpm add -D "@kungfu-tech/buildchain@$buildchain_version"
pnpm exec buildchain --version

The package manager records the exact resolved version in package.json and the lockfile. Review that version before committing it; do not leave a floating range in a release repository.

2. Choose the project type and initialize

Start with package for a Node package. Other supported types are native, web-surface, infra-contract, publication-artifact, and anchored-package.

pnpm exec buildchain init --type package --package-manager pnpm

Inspect the two generated files before continuing:

sed -n '1,220p' .buildchain/buildchain.toml
sed -n '1,220p' .github/workflows/build.yml

buildchain.toml owns repository lifecycle declarations. The workflow is a thin caller of Buildchain’s reusable workflow; it is not a second release implementation.

3. Validate the local contract

pnpm exec buildchain validate \
  --require-version-state \
  --require-lifecycle-stages install,build,verify
pnpm exec buildchain doctor --json

If the generated lifecycle commands do not match the repository, edit only .buildchain/buildchain.toml, then rerun both checks. See Lifecycle Protocol for the normative fields.

4. Inspect the reusable workflow and release dry-run

The generated caller should contain one reusable uses: edge and a manual buildchain-ref input for bounded train validation:

rg -n 'uses:|buildchain-ref:' .github/workflows/build.yml
pnpm exec buildchain release --dry-run \
  --target-ref alpha/v3/v3.0 \
  --json

The dry-run explains legal source refs, tags, version state, and publication effects. It does not move refs, edit files, or publish packages.

5. Create and inspect a local Release Passport example

This example creates a source-bound local Passport through the public Node API, then reads it through the CLI. It is learning evidence, not publication authority.

mkdir -p .buildchain/golden-path
node --input-type=module <<'EOF'
import fs from "node:fs";
import { createReleasePassport } from "@kungfu-tech/buildchain";

const passport = createReleasePassport({
  repository: "example/consumer",
  tag: "v0.1.0-alpha.0",
  sourceSha: "a".repeat(40),
  assets: [{ name: "consumer.tgz", sha256: "b".repeat(64) }],
});
fs.writeFileSync(
  ".buildchain/golden-path/buildchain.release.json",
  `${JSON.stringify(passport, null, 2)}\n`,
);
EOF

pnpm exec buildchain inspect release \
  --passport .buildchain/golden-path/buildchain.release.json \
  --json

For a real release, the protected Buildchain workflow creates the Passport from the exact source, artifact, controller, and publication evidence. See Release Passport; do not promote this local example.

You are done when

• the dependency and lockfile contain one exact Buildchain version;
• .buildchain/buildchain.toml declares the intended project type and lifecycle;
• validate and doctor succeed;
• .github/workflows/build.yml remains a thin reusable-workflow caller;
• the release dry-run and local Passport inspection both return structured output.

The repository test pnpm run check:golden-path reproduces this path in a new temporary consumer using the locally packed Buildchain package.

Choose the next manual

Troubleshooting

• already exists: initialization is no-overwrite by default. Inspect the existing files; use --force only for an intentional replacement.
• missing lifecycle stage: add the named stage to .buildchain/buildchain.toml; do not weaken the validation command.
• package release-age policy: add a temporary, package-and-version-specific minimumReleaseAgeExclude, then remove it after the normal window.
• unsure about syntax: run buildchain <path> --help. Help is intercepted before command dispatch and is side-effect free at every governed path.

Small glossary

• project type: the repository shape selected by buildchain init.
• lifecycle: repository-owned install, build, verify, and publish commands.
• reusable workflow: Buildchain-owned GitHub Actions control plane called by a thin consumer workflow.
• Release Passport: source- and artifact-bound release evidence, not a release trigger.
• train ref: a temporary validation runtime; never a production dependency.