@kungfu-tech/buildchain 4.0.10-alpha.0 → 4.1.0-alpha.0

package/AGENTS.md

@@ -1,3 +1,22 @@
+---
+status: active
+period: ongoing
+theme: buildchain-layered-architecture
+doc_type: implementation-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-10
+  visible_context: Buildchain 4.1 source, architecture registries and local validation.
+  invisible_context_boundary: No unpublished release or external consumer qualification is claimed.
+---
+
 # AGENTS.md
 
 This file orients coding agents and people working with Buildchain. It is a
@@ -38,7 +57,7 @@ For new repositories, prefer the CLI:
 ```sh
 npx @kungfu-tech/buildchain init --type package
 npx @kungfu-tech/buildchain validate --require-version-state
-npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.1
 ```
 
 For governed Paper repositories, scaffold or migrate the repository once, then
@@ -64,6 +83,10 @@ contracts retain their bounded, non-persistent validation mechanisms; see
 
 ## Building this repo
 
+Read [Code organization](docs/code-organization.md) before changing implementation
+layout. Keep workflows, action adapters, JavaScript modules and Rust domains in
+their declared responsibility layers. No historical compatibility entry is retained.
+
 Buildchain is a pnpm workspace running on Node 24:
 
 ```sh
@@ -111,15 +134,22 @@ called only by the public reusable workflow and tests. `version-state`,
 `publish`, provider, signing, release, credential, AWS, and production-reuse
 effects remain excluded.
 
-Buildchain v4 workflow calls persisted in tracked source use only `@v4` or
+External Buildchain v4 workflow calls persisted in tracked source use only `@v4` or
 `@v4-alpha` and retain matching stable and alpha contract locks.
 A source-persisted exact commit SHA, exact default, repository-variable indirection, nested
 composite indirection, missing lock, or stale selected lock fails consumer
 admission. Exact resolved SHAs remain evidence and runtime data, never a durable
 selector.
 
-If public workflow recursion prevents candidate validation, publish the exact
-candidate at `train/v4/v4.0/<capability>`, keep the thin caller on `@v4-alpha`,
+Buildchain's own promotion callers invoke the same public promotion workflow by
+repository-relative path, binding the caller and public API to the same commit.
+Admission verifies the defining repository, exact Git commit, committed invocation
+files, and both channel contract locks. This source-owned composition is confined
+to `public-release-promote.yml`; it does not change the Stage Capsule public
+floating-channel dogfood rule above. See `docs/release-promotion-request.md`.
+
+If public Stage Capsule workflow recursion prevents candidate validation, publish the exact
+candidate at `train/v4/v4.1/<capability>`, keep the thin caller on `@v4-alpha`,
 and pass the train only through the trusted non-persistent runtime input. Fix
 failures in the train/public contract; never solve recursion with an internal exception.
 Never use a persisted train/SHA selector. After qualification and protected
@@ -140,7 +170,7 @@ handoff in
 
 - Open pull requests against the relevant `dev/*` channel branch.
 - If a Buildchain change needs downstream validation before stable refs move,
-  publish a `train/v3/v3.0/<capability>` ref and include the validation request
+  publish a `train/v4/v4.1/<capability>` ref and include the validation request
   described in [`docs/runtime-train-validation.md`](docs/runtime-train-validation.md).
   After validation succeeds, do not leave the train as a pending merge item:
   merge the pull request into the active `dev/*` mainline and run the requested

package/CONTRIBUTING.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-07
+last_reviewed: 2026-09-10
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-07
+  generated_at: 2026-09-10
   visible_context: Repository contribution rules and implementation naming and release transition changes.
   invisible_context_boundary: No private credentials or unpublished external release state.
 ---
@@ -47,26 +47,16 @@ repository itself is a Node/pnpm workspace.
 
 ## Repository layout
 
-- `.github/workflows` - repository checks, reusable workflows, and Buildchain
-  self-promotion.
-- `.github/retrospectives` - time-bounded engineering reviews and maintenance
-  handoff records. Start with the latest record before broad consolidation work.
-- `actions` - the active GitHub Actions surface:
-  `validate-config`, `run-lifecycle`, `promote-buildchain-ref`, and
-  `report-buildchain-issue`.
-- `bin` - the published `buildchain` command-line entrypoint.
-- `docs` - release governance, lifecycle, reusable workflow, web-surface, and
-  CLI documentation.
-- `fixtures` - safe shape fixtures used by tests and reusable workflow checks.
-- `packages/core` - shared ESM library code used by CLI and scripts.
-- `scripts` - local and workflow runtime scripts.
-- `tests` - Node test runner suites and inventory contracts.
-
-Standalone historical `action-*` repositories are not mirrored here as active
-actions. See [`docs/migration-inventory.md`](docs/migration-inventory.md).
-
-The current consolidation handoff is
-[`2026-07-10-buildchain-consolidation.md`](.github/retrospectives/2026-07-10-buildchain-consolidation.md).
+The [code organization contract](docs/code-organization.md) defines the layers.
+Consumer APIs and hosted job boundaries live in `.github/workflows`; semantic
+node adapters live in `actions/<capability>/<group>/<operation>`; JavaScript business logic
+lives in `packages/core/<capability>`; authoritative Rust domains and the native
+host live in `crates`. `bin` contains the CLI entry, and `scripts` contains only
+repository tooling. Schemas, ownership declarations and tests live in
+`contracts`, `architecture` and `tests`.
+
+Do not add historical aliases or compatibility forwarders. Update every owned
+caller and generated artifact when moving a contract or implementation.
 
 ## Build and verification
 
@@ -106,15 +96,14 @@ category vocabulary is enforced by `architecture/workflow-taxonomy.json`:
 Categories are only `build`, `release`, and `ops`. Register the identity, role,
 category, purpose, owner, lifecycle status, invocation, and rationale before
 adding its derived filename. The [Workflow Catalog](docs/workflow-catalog.md)
-lists every allowed path and compatibility exception. Existing public aliases
-are generated from their canonical implementations; self workflows have one
-event entry. A matching prefix alone does not admit an unregistered workflow.
+lists every canonical API and component path; self workflows have one
+event entry. Retired paths have no generated aliases. A matching prefix alone does not admit an unregistered workflow.
 
 Run `pnpm run generate:workflows`, `pnpm run check:workflows`, then the full
 `pnpm run check`. The required Verify lifecycle runs this gate on PRs, merge
 queue candidates, and pushes. Policy, enforcement, and ownership changes require
-independent `@kungfu-origin` review. Keep published floating consumers on their
-registered legacy paths until the selected channel actually ships the new path.
+independent `@kungfu-origin` review. A development merge does not publish a floating channel. Consumers adopt the
+new API only after that channel publishes it and their contract locks are refreshed.
 
 ## Generated files
 
@@ -157,7 +146,7 @@ release/vX/vX.Y -> publish-gate/major
   `docs/*`, `ci/*`, or `refactor/*` branches and open a PR into the target dev
   line.
 - Repositories may call
-  `.github/workflows/dev-pr-auto-merge.yml` from their own scheduled or manual
+  `.github/workflows/public-ops-dev-auto-merge.yml` from their own scheduled or manual
   wrapper to merge ready, conflict-free dev PRs. The wrapper is policy-gated:
   required checks, ready/block labels, same-repository heads, approvals,
   branch prefixes, max merges, and dry-run are all declared inputs.
@@ -190,7 +179,7 @@ Name implementation directories, scripts, functions, and runtime work directorie
 for their responsibility. Product generation prefixes such as `v4-` are rejected
 by `pnpm run check:implementation-naming`, including nested JavaScript bindings
 and Rust declarations. `architecture/implementation-naming.json` records the
-explicit relocation and public export aliases. Published schema identities, hash
+current implementation identities and prohibited generation prefixes. Published schema identities, hash
 domains, selectors, runner labels, API compatibility keys, and exact historical
 evidence keep their established identities; they do not name new implementations.
 

package/README.md

@@ -1,5 +1,28 @@
+---
+status: active
+period: ongoing
+theme: buildchain-layered-architecture
+doc_type: implementation-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-10
+  visible_context: Buildchain 4.1 source, architecture registries and local validation.
+  invisible_context_boundary: No unpublished release or external consumer qualification is claimed.
+---
+
 # Buildchain
 
+Development: **4.1.0-alpha.0** on `dev/v4/v4.1`. This development version has
+not been published. See [Code organization](docs/code-organization.md) for the
+workflow → action → JavaScript/Rust implementation layers.
+
 <!-- buildchain-auditable-demo:start -->
 
 ## Buildchain beginner bootstrap
@@ -37,9 +60,9 @@ This exact standalone-binary scenario proves deterministic local bootstrap behav
 [![Buildchain Release Passport: passed](https://buildchain.libkungfu.dev/badges/v1/buildchain-release-passport/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da.svg)](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)
 [![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6e7781.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)
-[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)
-[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)
-[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)
+[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-verify.yml)
+[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/self-release-promote.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/self-release-promote.yml)
+[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/self-build-binary-distribution.yml)
 <!-- buildchain:badges:end -->
 
 Buildchain Release Passport is a mature product release record for artifacts
@@ -216,7 +239,7 @@ Consumers can report Buildchain-owned workflow failures directly to the
 Buildchain repository with a scoped issue-write token:
 
 ```yaml
-- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v4
+- uses: kungfu-systems/buildchain/actions/governance/incident/report@v4
   if: failure()
   with:
     token: ${{ steps.buildchain-issue-token.outputs.token }}
@@ -283,30 +306,33 @@ plus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These
 gates preserve product-owned qualification and support decisions; they do not
 turn a schema-valid record into certification or shipped support.
 
-Buildchain's action registry contains fourteen active entries. Six are
-direct consumer integration actions:
+Reusable workflows are the primary consumer API. The generated action registry
+indexes the capability/group/operation hierarchy and marks direct action contracts.
+The direct consumer integration actions are:
 
-- `actions/validate-config`
-- `actions/run-lifecycle`
-- `actions/promote-buildchain-ref`
-- `actions/report-buildchain-issue`
-- `actions/release-tail`
-- `actions/release-candidate-promote`
+- `actions/build/lifecycle/validate`
+- `actions/build/lifecycle/run`
+- `actions/release/promotion/ref`
+- `actions/governance/incident/report`
+- `actions/release/tail/settle`
+- `actions/release/promotion/candidate`
 
-Two additional release-authority components are also registered and versioned:
+Three additional release-authority components are also registered and versioned:
 
-- `actions/github-artifact-attestation`
-- `actions/macos-credential-island`
+- `actions/build/artifact/prepare-attestation`
+- `actions/build/artifact/seal-attestation`
+- `actions/build/credential/macos-island`
 
-Six shared build components have explicit ownership in
+Seven shared build components have explicit ownership in
 `architecture/build-orchestration.json`:
 
-- [`actions/build-lifecycle-stage`](actions/build-lifecycle-stage/action.yml)
-- [`actions/build-signing-request`](actions/build-signing-request/action.yml)
-- [`actions/build-verification-evidence`](actions/build-verification-evidence/action.yml)
-- [`actions/build-attestation-policy`](actions/build-attestation-policy/action.yml)
-- [`actions/build-agent-hub-evidence`](actions/build-agent-hub-evidence/action.yml)
-- [`actions/build-artifact-transfer`](actions/build-artifact-transfer/action.yml)
+- [`actions/build/lifecycle/plan`](actions/build/lifecycle/plan/action.yml)
+- [`actions/build/lifecycle/prepare`](actions/build/lifecycle/prepare/action.yml)
+- [`actions/build/lifecycle/stage`](actions/build/lifecycle/stage/action.yml)
+- [`actions/build/artifact/transfer`](actions/build/artifact/transfer/action.yml)
+- [`actions/build/artifact/sign`](actions/build/artifact/sign/action.yml)
+- [`actions/build/artifact/attest`](actions/build/artifact/attest/action.yml)
+- [`actions/build/artifact/finalize`](actions/build/artifact/finalize/action.yml)
 
 `dist/site/workflow-registry.json#actions` is the machine-readable inventory;
 this split keeps the older four-action consumer snapshot from being mistaken for
@@ -314,14 +340,14 @@ the complete current registry.
 
 The active reusable workflow surfaces are:
 
-- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile
+- `.github/workflows/.build-gate-profile.yml` for project-neutral Shifu Gate profile
   planning, capability-aware runner dispatch, receipt validation, and one
   stable aggregate check;
-- `.github/workflows/.auditable-demo.yml` for exact-artifact demo
+- `.github/workflows/.build-demo-adapter.yml` for exact-artifact demo
   qualification, transcript-bound renderer smoke, optional media rendering
   from the exact passing Gate bundle, and opt-in content-addressed web-delivery
   profiles with independently verified rendition roles;
-- `.github/workflows/.declarative-auditable-demo.yml` for standalone binary
+- `.github/workflows/public-build-demo.yml` for standalone binary
   consumers that provide only a versioned multi-demo argv scenario and exact
   same-run binary artifact coordinates; Buildchain owns isolated native
   capture, Gate, Release Passport, materialization, and protected README PRs;
@@ -329,10 +355,10 @@ The active reusable workflow surfaces are:
   artifact contracts;
 - `.github/workflows/build.yml` for the single-config channel router that uses
   `vN-alpha` during development/prerelease work and `vN` for stable releases;
-- `.github/workflows/release-candidate-promote.yml` for post-merge
+- `.github/workflows/public-release-promote.yml` for post-merge
   promote-only publication from a PR-stage release candidate, without a second
   heavy build;
-- `.github/workflows/.web-surface.yml` for preview, staging, production, and
+- `.github/workflows/public-release-web.yml` for preview, staging, production, and
   cleanup plans for site/app repositories;
 - `.github/workflows/self-release-promote.yml` for protected release
   promotion and version-state transactions;
@@ -343,7 +369,7 @@ Stable consumers should reference actions and workflows through floating major
 refs after reviewing the exact release passport:
 
 ```yaml
-uses: kungfu-systems/buildchain/actions/validate-config@v4
+uses: kungfu-systems/buildchain/actions/build/lifecycle/validate@v4
 ```
 
 ```yaml
@@ -351,7 +377,7 @@ uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4
 ```
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4
+uses: kungfu-systems/buildchain/.github/workflows/public-release-promote.yml@v4
 ```
 
 ## Release Model

package/actions/build/artifact/prepare-attestation/README.md

@@ -0,0 +1,26 @@
+---
+status: active
+period: ongoing
+theme: github-artifact-attestation
+doc_type: action-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-10
+  visible_context: Action metadata and attestation transaction source.
+  invisible_context_boundary: No hosted publication qualification is claimed.
+---
+
+# Prepare a GitHub artifact attestation
+
+Validate the exact subject bytes, platform manifest, release Passport and signer policy before calling the external attestation action. The action runs on Node 24 and verifies the selected Buildchain runtime commit.
+
+Supply `runtime-sha`, `subject-path`, `platform-manifest-path`, `release-passport-path` and `policy-json`. The outputs include the verified subject digest, predicate path and `preparation-json` consumed by the sealing action.
+
+Use the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact input/output contract; [`seal-attestation`](../seal-attestation/README.md) verifies the provider result.

package/actions/build/artifact/seal-attestation/README.md

@@ -0,0 +1,26 @@
+---
+status: active
+period: ongoing
+theme: github-artifact-attestation
+doc_type: action-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-10
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-10
+  visible_context: Action metadata and attestation transaction source.
+  invisible_context_boundary: No hosted publication qualification is claimed.
+---
+
+# Seal a GitHub artifact attestation
+
+Verify the external provider result against the preparation record and unchanged subject bytes, then retain the attestation bundle and rooted evidence. The action runs on Node 24 and rechecks the exact selected runtime commit.
+
+Supply `runtime-sha`, `preparation-json`, `bundle-path`, `attestation-id`, `attestation-url` and an explicit read `token`. The outputs identify the retained bundle digest and evidence root. Provider failure or subject drift prevents sealing.
+
+Use the public reusable artifact-attestation workflow for the complete credential and provider boundary. [`action.yml`](action.yml) defines the exact contract; [`prepare-attestation`](../prepare-attestation/README.md) owns pre-provider validation.

package/actions/build/lifecycle/run/README.md

@@ -0,0 +1,71 @@
+# run-lifecycle
+
+Run a Buildchain lifecycle stage or an explicit command and write a deterministic
+artifact manifest.
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/build/lifecycle/run@v3
+  with:
+    stage: build
+    required: "true"
+    artifact-name: my-product-linux-x64-${{ github.sha }}
+    artifact-paths: |
+      dist
+      build/stage
+```
+
+When `command` is provided, it overrides `buildchain.toml` for that invocation.
+When `command` is empty, the action loads `buildchain.toml` and runs the named
+stage.
+
+`timeout-minutes` defaults to 120 and bounds either command source. A
+stage-specific `timeout_minutes` in `buildchain.toml` takes precedence. Timeout
+errors identify the lifecycle stage and platform so a hung self-hosted build can
+be diagnosed after the runner is released.
+
+The action writes both a full manifest and a compact summary. It also exposes
+the summary as outputs for reusable workflow callers:
+
+For a `build` stage, paths selected by `[[signing.artifacts]]` for the current
+`platform-id` are automatically included in the lifecycle manifest even when
+they sit outside `artifact-paths`. This binds every byte sent to the signing
+authority without changing which ordinary product paths the caller uploads.
+
+| Output | Meaning |
+| --- | --- |
+| `manifest-path` | Full manifest path |
+| `summary-path` | Compact summary path |
+| `artifact-name` | Resolved artifact name |
+| `artifact-file-count` | Number of manifest files |
+| `artifact-total-bytes` | Total manifest bytes |
+| `artifact-summary-json` | One-line JSON summary |
+| `expected-artifacts-ok` | `true` when expectations passed |
+
+`expected-artifacts-json` can require exact paths, file count bounds, and a
+minimum byte total:
+
+```yaml
+with:
+  expected-artifacts-json: >-
+    {"minFiles":2,"requiredPaths":["dist/app.tar.gz","dist/checksums.txt"]}
+```
+
+For long native builds, set `sample-process-tree: "true"` and pass
+`process-summary-path`. The action wraps either the explicit `command` or the
+configured lifecycle stage with `buildchain sample process-tree`, then embeds
+the produced summary in the lifecycle diagnostics artifact:
+
+```yaml
+with:
+  stage: build
+  sample-process-tree: "true"
+  process-summary-path: .buildchain/diagnostics/process-summary.json
+```
+
+Custom wrappers can still pass an existing sampler report or summary with
+`process-summary-path`; the action reads it after the lifecycle command
+finishes, so commands may generate the file during the same invocation.
+Set `process-summary-required: "false"` when the summary is an optional sidecar,
+for example when a reusable workflow may skip an optional build stage.
+The diagnostics directory also includes `diagnostics-manifest.json`, a compact
+inventory of the diagnostics sidecars with byte counts and sha256 hashes.

package/actions/build/lifecycle/validate/README.md

@@ -0,0 +1,52 @@
+---
+status: active
+period: ongoing
+theme: buildchain-config-validation-action
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
+# validate-config
+
+Buildchain v3 action for validating `.buildchain/buildchain.toml` without running lifecycle
+commands.
+
+Use this action during repository migration when a heavyweight project needs to
+prove that its Buildchain version state and lifecycle declaration are ready, but
+the actual build should not run yet.
+
+## Usage
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/build/lifecycle/validate@v3
+  with:
+    require-version-state: "true"
+    require-lifecycle-stages: "install,build,verify"
+```
+
+The action checks:
+
+- `buildchain.toml` exists and uses schema `1`;
+- configured version-state files exist and expose a string version;
+- anchored/manual version strategy declarations and JSON/TOML anchor manifests
+  are structurally valid when configured;
+- web-surface project, channel, deploy adapter, retention, and staging security
+  declarations are structurally valid when configured;
+- required lifecycle stages are declared and structurally valid.
+
+It does not execute `lifecycle.install`, `lifecycle.build`, `lifecycle.verify`,
+or any other lifecycle command.
+
+Outputs include `project-type`, `project-name`, `project-site`, `channels`, and
+`deploy-adapters-json`, so callers can route site workflows without reparsing
+TOML in every repository.

package/actions/governance/incident/report/README.md

@@ -0,0 +1,107 @@
+---
+status: active
+period: ongoing
+theme: buildchain-consumer-issue-action
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
+# report-buildchain-issue
+
+Create or update a Buildchain repository issue from a consumer workflow or from
+Buildchain's own workflow-friction feedback loop.
+
+This action is intended for consumer repositories that need to report
+Buildchain-owned failures with enough evidence for maintainers to act. It
+requires a token that can write issues on the target Buildchain repository.
+For cross-repository consumers, generate that token with a GitHub App
+installation token or another scoped credential owned by the consumer
+organization.
+
+```yaml
+- uses: actions/create-github-app-token@v2
+  id: buildchain-issue-token
+  with:
+    app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}
+    private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}
+    owner: kungfu-systems
+    repositories: buildchain
+
+- uses: kungfu-systems/buildchain/actions/governance/incident/report@v3
+  if: failure()
+  with:
+    token: ${{ steps.buildchain-issue-token.outputs.token }}
+    summary: "Reusable build failed before artifact finalization"
+    failure-code: reusable-build-failed
+    buildchain-ref: ${{ inputs.buildchain-ref || 'v3' }}
+    diagnostics-path: .buildchain/artifacts/diagnostics.json
+```
+
+The action computes a stable fingerprint from the consumer repository,
+workflow, job, failure code, and Buildchain ref. When an open issue already
+exists for that fingerprint, it comments with the new run instead of opening a
+duplicate issue.
+
+By default issue reporting is fail-soft:
+
+- `fail-on-error: "false"` prevents a reporting outage from hiding the original
+  build failure.
+- transient GitHub API 429/5xx errors and connection failures are retried.
+- if a configured label is missing, issue creation is retried without labels.
+- if issue creation/commenting is still unavailable, the action writes the full
+  copyable issue title, fingerprint, and body into the workflow summary.
+- common token, private-key, password, and authorization values are redacted
+  before submission.
+
+Use `dry-run: "true"` to verify the computed fingerprint and body shape without
+calling GitHub.
+
+For Buildchain-owned workflow friction, use `report-kind: workflow-friction`.
+This uses a separate marker and default labels so duplicate PRs, duplicate
+builds, transient API failures, stale release-state, or missing RC evidence can
+be grouped without mixing with consumer failure reports:
+
+```yaml
+permissions:
+  issues: write
+
+steps:
+  - uses: actions/create-github-app-token@v2
+    id: buildchain-issue-token
+    with:
+      app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}
+      private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}
+      owner: kungfu-systems
+      repositories: buildchain
+
+  - uses: kungfu-systems/buildchain/actions/governance/incident/report@v3
+    if: failure()
+    with:
+      token: ${{ steps.buildchain-issue-token.outputs.token || secrets.BUILDCHAIN_ISSUE_TOKEN || secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token }}
+      report-kind: workflow-friction
+      target-repository: kungfu-systems/buildchain
+      repository: ${{ github.repository }}
+      workflow: ${{ github.workflow }}
+      run-id: ${{ github.run_id }}
+      run-attempt: ${{ github.run_attempt }}
+      channel: alpha/v3/v3.0
+      source-sha: ${{ github.sha }}
+      friction-class: duplicate-build
+      related-runs-json: ${{ steps.classify.outputs.related-runs-json }}
+      heavy-builds-json: ${{ steps.classify.outputs.heavy-builds-json }}
+      comment-cooldown-hours: "24"
+```
+
+`comment-cooldown-hours` is optional. When it is greater than zero, Buildchain
+still deduplicates by fingerprint but skips adding another comment if the
+existing issue already received a recent update.