@kungfu-tech/buildchain 3.0.9-alpha.8 → 4.0.0-alpha.0

package/docs/next-development-transition.md

@@ -1,119 +0,0 @@
----
-status: preview
-period: ongoing
-theme: next-development-transition
-doc_type: generated-contract-guidance
-source_level: generated-from-node-contract
-confidence: high
-sensitivity: public
-evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-11
----
-
-# Next-development Transition
-
-This document is generated from
-`packages/core/next-development-transition.js` and
-`packages/core/next-development-controller.js` and
-`packages/core/next-development-projection.js`. Edit those sources and run
-`node scripts/generate-next-development-guidance.mjs`; direct edits fail the
-projection drift check.
-
-## Contract
-
-- Contract: `kungfu-buildchain-next-development-transition/v1`
-- Durable controller: `kungfu-buildchain-next-development-controller/v1`
-- ADR: [ADR 0002](../architecture/decisions/0002-next-development-transition.md)
-- States: `planned`, `waiting-anchor`, `materialized`, `pr-pending`, `merged`, `verified`
-- Legal version models: `semver/auto` and `anchored/manual`
-- Invariant: A completed Alpha remains successful and its refs remain immutable while the next-development transition is incomplete.
-
-An Alpha publication is terminal success independently of this transition.
-The idempotency key is a deterministic hash of the completed-Alpha root,
-repository, legal model, and sorted declared paths. Incomplete Dev preparation
-therefore cannot relabel Alpha N as failed, and replay cannot select a different
-Alpha or path set.
-
-## Durable controller
-
-`scheduleNextDevelopmentController` atomically creates one child for the
-repository and completed-Alpha root. Identical wakes reuse it. The store
-boundary requires read, create-if-absent, and compare-and-swap operations; the
-controller root fences every checkpoint. Materialization uses an operation key
-derived from the child, exact current protected Dev SHA, and reviewed target,
-so a fresh runner can recover an already-created commit instead of rebuilding
-the Alpha candidate or depending on the original runner workspace.
-
-Before opening the protected version PR, the controller reads Dev again. A
-moved head makes the prepared attempt `superseded`; the following wake
-regenerates only declared version material from that latest SHA. After merge,
-`verified` remains unreachable until protected Dev readback contains the
-prepared commit and its target version, source roots, and derived roots exactly
-match the checkpoint. The executor surface contains no Alpha publication, tag,
-release, or package operation.
-
-Alpha finalization no longer treats a non-fast-forward Dev update as successful
-bookkeeping. It requires an exact checkout of the current Dev head, regenerates
-the declared version lifecycle there, and uses a non-force merge or reusable
-protected version PR. Candidate Patrol ignores both the generated preparation
-commit and its two-parent integration commit. Before a later product candidate
-can settle, Patrol reads every prepared version path at the candidate SHA and
-requires the exact reserved blob identities; missing or stale state blocks
-before a Release Cut or heavy candidate build.
-
-## Version models
-
-`semver/auto` increments the Alpha sequence on the same semantic patch. For
-example, completed `1.4.2-alpha.7` plans `1.4.2-alpha.8`. It must not accept an anchor or an
-operator-selected target.
-
-`anchored/manual` enters `waiting-anchor` until the caller provides both a
-semantic target and the exact digest of the configured anchor manifest. The
-adapter verifies the manifest already present in the checkout; it never invents
-or edits upstream anchor facts. `semver/manual` and `anchored/auto` are
-invalid.
-
-## Hosted self-dogfood and adoption
-
-`.github/workflows/buildchain-alpha-self-dogfood.yml` calls the same public
-`build.yml@v3-alpha` router as a consumer. After the hosted build succeeds, one
-runner uses the real version-state adapter and checkpoints an injected transient
-durable-state write failure. A separate runner restores the adapter operation
-without rebuilding Alpha, supersedes it when protected Dev moves, and preserves
-`pr-pending` while the protected PR is delayed. The final artifact roots the
-exact runtime SHA, controller transaction, both legal version-model outcomes,
-and an exact hosted protected Dev readback. Stable qualification recomputes and
-rejects evidence that omits or drifts any of those bindings.
-
-Production consumers, including Kungfu, adopt the proved contract through
-`kungfu-systems/buildchain/.github/workflows/build.yml@v3`. The evidence retains
-the exact resolved SHA for audit, but the committed production coordinate is the
-floating major contract rather than an exact-SHA pin.
-
-## Local adapter
-
-From a normal Buildchain checkout:
-
-```sh
-node scripts/next-development-transition.mjs materialize --cwd . --input <request.json>
-```
-
-The command prints a rooted plan and performs no write by default. `--write`
-may change only regular, non-symlink source files listed by `version.files`
-in the loaded Buildchain config. The rooted adapter contract separately names
-`version.derived_files` as allowed changes, `version.manifest` as read-only,
-`BUILDCHAIN_VERSION` as the target input, `lifecycle.version-state` as the
-derived-material stage, and `lifecycle.verify` as the truth gate. The
-reference writer fails closed when derived files exist because transaction
-execution is outside this contract slice. It performs no Git operation, ref
-update, network request, provider call, lifecycle command, or anchor edit.
-
-Preparing development state creates no tag, Release, public package, or
-candidate. Those public effects remain outside the local adapter contract.
-
-The request schema is
-`contracts/next-development-request-v1.schema.json`; the durable record schema
-is `contracts/next-development-transition-v1.schema.json`. Positive and
-negative examples live under
-`contracts/fixtures/next-development-transition-v1/`.

package/docs/publication-rehearsal.md

@@ -1,94 +0,0 @@
----
-status: preview
-period: 2026-08-08
-theme: buildchain-publication-rehearsal
-doc_type: product-manual
-source_level: local-files
-confidence: high
-sensitivity: public
-evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-08
-ai_provenance:
-  model_family: GPT-5
-  product: Codex
-  generated_at: 2026-08-08
-  visible_context: Public rehearsal capsule runtime, release-tail provider plane, CLI, Action, workflow, and generated consumer surfaces.
-  invisible_context_boundary: No credentials, private provider state, signed URLs, or external publication receipts were read.
----
-
-# Publication rehearsal
-
-Buildchain publication rehearsal runs the deterministic release tail locally
-from one `kungfu.buildchain.publication-rehearsal-capsule/v1` document. The
-normative rule is [ADR 0001](../architecture/decisions/0001-release-local-constructibility.md):
-every non-external release behavior must be locally constructible, and no
-semantic path may depend on GitHub runner state.
-
-The machine-readable shape is
-[`publication-rehearsal-capsule-v1.schema.json`](../contracts/publication-rehearsal-capsule-v1.schema.json).
-
-## Exact local command
-
-Run from the repository root after restoring the content-addressed candidate:
-
-```sh
-buildchain release-tail rehearse \
-  --capsule "$PWD/.buildchain/publication/rehearsal-capsule.json" \
-  --capsule-root "$PWD/.buildchain/publication/candidate" \
-  --mode simulate \
-  --state "$PWD/.buildchain/publication/rehearsal-state.json" \
-  --evidence "$PWD/.buildchain/publication/rehearsal-evidence.json"
-```
-
-Use `--mode replay` only when the capsule contains a complete recorded
-provider-response sequence. Both modes produce rooted evidence with
-`externalPublicationClaimed: false`.
-
-## Daily fixture and sealed-candidate modes
-
-For daily development, build a synthetic capsule with
-`createPublicationRehearsalCapsule`, use synthetic files and provider
-observations, and run `--mode simulate` or `--mode replay`. This fixture mode is
-for deterministic regression evidence only.
-
-Before publication qualification, restore the exact sealed candidate bytes,
-Passport, policy roots, initial transaction and recorded observations named by
-the retained capsule, then run the exact command above. Preserve the resulting
-binding root, transaction root, state root, receipt roots and evidence root.
-These roots qualify deterministic construction only; external publication and
-public readback still require their own authorities.
-
-## Capsule contents
-
-The capsule root commits to the release-tail declaration, ordered policy roots,
-Passport path/root, initial durable transaction, complete file inventory,
-data-only provider bindings, recorded observations, portable platform policy,
-declared environment keys, and the exact list of external effects. Every input
-file is a regular non-symlink file under the explicit absolute capsule root and
-must match its size and SHA-256 root.
-
-The CLI never reads `GITHUB_*`, infers a runner workspace, selects behavior from
-`process.platform`, or accepts executable hooks. An explicit environment JSON
-object must match the capsule declaration exactly.
-
-## Hosted parity
-
-The reusable `release-tail.yml` workflow passes the explicit capsule to the
-`actions/release-tail` wrapper. The wrapper supplies only GitHub/HTTP transport
-and declared secret inputs, then invokes the same
-`executePublicationRehearsal` public core used locally. Provider requests,
-responses, failures, transaction roots, receipt roots, and the final evidence
-root are retained together.
-
-Simulation or replay is development evidence. Provider mode can record real
-external observations, but it still does not replace Release Passport,
-attestation, registry, activation, public-readback, or protected-delivery
-authority.
-
-## Failure handling
-
-Diagnostics use
-`kungfu.buildchain.publication-rehearsal-diagnostic/v1`. Preserve the capsule,
-diagnostic root, binding root, and exact failed files. Repair the shared core or
-capsule locally and rerun before spending another hosted runner attempt.