Cut and publish Blueprint 4.1.0 from one exact converged release candidate

[taco3064]

Goal

Cut and publish @kekkai/blueprint@4.1.0 from one exact, release-converged main candidate.

This is the single release-convergence ledger for 4.1.0. Completing this issue means all of the following are true:

1. the pending 4.1 changesets have been editorially consolidated into an accurate 4.1 release narrative;
2. the repository has a Changesets-generated 4.1.0 version commit on main;
3. that exact 4.1.0 main SHA has a verified CI-produced packed candidate;
4. the complete 4.1 live field matrix passes against that exact candidate with zero release blockers and records blueprint/field-convergence = success;
5. v4.1.0 points at that same converged SHA;
6. publication uses either the normal tag-push path or the explicitly authorized recovery path, while still publishing the exact converged candidate with provenance and creating the matching GitHub Release.

Do not split changeset cleanup, versioning, convergence, tag creation, or publication into separate release tickets. They are one outcome: 4.1.0 exists publicly only after one exact candidate has passed the complete release authority chain.

Current release-preparation baseline: main@26e04a40939f200a4e90288c4e92e281e960b4a0, package version 4.0.0.

Evidence

4.1 product scope is already implemented on main

The work intended for this minor release is complete:

• Preserve canonical governance in greenfield adoption and establish module-first runway #500 — greenfield adoption preserves canonical governance and opens a module-first modules: [] runway;
• Add first-class upgrade/remove lifecycle with cumulative adopter upgrade plans #501 — first-class cumulative upgrade / provenance-aware remove lifecycle;
• Surface GitHub Discussions as a live evidence feed on the docs site #505 — GitHub Discussions evidence feed on the docs site;
• Restore provable alignment between main docs and the public product contract #516 — public docs/runtime/API/release-identity alignment;
• The upgrade → remove lifecycle dead-ends on a real 3.2 adoption #517 — the real 3.2 adoption lifecycle dead ends are repaired and replayed end to end.

#517 is the strongest lifecycle oracle before versioning. Its final replay used the accepted tree that later landed on main and proved, on a disposable sky-1945@3a3c50a adoption:

3.1 refusal
→ lift to 3.2
→ packed candidate upgrade
→ review-retired-module-private
→ doctor complete
→ project lint / 617 tests / build
→ unwire real Blueprint references
→ remove
→ project lint / 617 tests / build

without the three original workarounds: no literal-alias rewrite, no added vitest.config.*, and no manual config deletion.

That replay is a pre-release product oracle. It does not replace the final field convergence required on the Changesets-generated 4.1.0 main SHA.

Pending release inputs

main still reports package version 4.0.0. The pending package changesets are:

• .changeset/greenfield-module-first-runway.md — minor
• .changeset/upgrade-remove-lifecycle.md — minor
• .changeset/enforce-documented-config-contract.md — patch
• .changeset/doctor-proves-written-alias.md — patch
• .changeset/preserve-migrated-config-source.md — patch

The two minor entries make the intended next version 4.1.0.

One known editorial correction is required before versioning: preserve-migrated-config-source.md currently says comments “stay as written”. #517 established the stricter truth: every comment is preserved, but a comment nested inside a retired module value may be re-emitted where that retired property stood. Release notes must not claim byte-position preservation that the product does not provide.

The final 4.1 framing should describe the release at product level before the generated change headings. The release story is:

• Greenfield posture: proven-empty React/Vue projects can enter either LF or MF from the canonical preset governance without an invented domain model.
• Lifecycle: adoption is no longer one-way; upgrade and remove are first-class lifecycle operations with provenance and fail-closed completion.
• Evidence: deterministic migration does everything Blueprint can prove, semantic judgment remains explicit, and completion is bound to Doctor/Inspect plus real-adopter evidence rather than optimistic state changes.

Release authority already exists in the repository

.agents/docs/field-triage.md defines the release sequence:

changeset cleanup
→ npx changeset version
→ reviewed 4.1.0 version commit on main
→ successful exact-main CI candidate artifact
→ field repair(s), if needed, through the normal PR chain
→ successful final exact-main CI candidate artifact
→ full field convergence on that exact final candidate
→ blueprint/field-convergence = success on that exact SHA
→ publish that exact candidate either by normal tag push or, when its embedded release tooling is obsolete, by the reviewed recovery path

Release publication requires:

• tag semver = package.json.version;
• a valid Changesets version commit establishing the release version;
• all pending .changeset/*.md consumed;
• the final publish candidate to have successful exact-SHA field convergence authority;
• a later tooling commit must not inherit or receive a copy of that candidate's field status;
• npm provenance that truthfully identifies the actual publishing workflow and the original candidate artifact;
• GitHub Release notes generated from the converged candidate's matching CHANGELOG.md section.

The Changesets version commit is the release-version origin, not the product freeze point. Field findings may be repaired afterwards within the same unpublished version. The final candidate that passes full field convergence is the product freeze point.

The release-convergence ticket is allowed to be the human-readable ledger. The exact commit status remains the machine authority.

Adopter upgrade assessment for 4.1

4.1 still requires adopter-side semantic work for a supported historical case after deterministic code has done everything it can prove.

The existing lifecycle catalog intentionally carries:

• supportedFrom: 3.2.0;
• deterministic legacy-unit-shape migration introduced in 4.0;
• review-retired-module-private for configurations whose 3.2 source declared retired module.private;
• LIFECYCLE_SINCE = 4.1.0.

Do not rewrite introducedIn to 4.1 merely because the lifecycle command ships in 4.1. The operation describes the historical semantic change it repairs. #517 proved that the 4.1 lifecycle can execute that historical responsibility correctly.

Before versioning, re-run the catalog/release assessment against the final main source. If no new semantic requirement exists beyond the current catalog, record that conclusion in this ticket instead of inventing an empty 4.1 operation.

Execution Protocol — Skills and GitHub Actions

This ticket deliberately spans preparation, versioning, live convergence, and publication, but one skill does not own the whole release. Handoffs are explicit.

Stage 0 — Shape is complete

Owner: shape-ticket

This issue is the shaped release contract. Shape does not edit release files, run field agents, create the version commit, tag, or publish.

Re-enter shape-ticket only for:

• post-Accept review of a release-preparation/version PR;
• a material release-contract question discovered during delivery that current repository evidence cannot resolve;
• final decision-fidelity review after a repaired release candidate changes the shaped outcome.

Do not use Shape as the runner for routine release steps.

---

Stage 1 — Prepare Changesets and assemble the 4.1.0 version candidate

Owner: deliver-ticket

Trigger deliver-ticket when the owner asks to start/continue #521 release preparation.

Delivery must:

1. branch from current origin/main;
2. review and edit the pending 4.1 changesets;
3. perform the adopter-upgrade assessment;
4. run npx changeset version;
5. review package.json, package-lock.json, consumed changesets, and generated CHANGELOG.md;
6. hoist the 4.1 release-framing passage;
7. run focused checks needed for the release-input edits;
8. stage the complete version candidate and run the pre-commit fixer;
9. record the candidate tree with git write-tree.

At this point do not commit yet.

Acceptance handoff

Owner: accept-ticket

A fresh reviewer receives:

• Cut and publish Blueprint 4.1.0 from one exact converged release candidate #521;
• base commit;
• staged candidate tree;
• complete diff;
• focused evidence.

It must return ACCEPTED before the version candidate is committed.

If it returns CHANGES_REQUIRED, Delivery repairs the uncommitted candidate and requests Acceptance again under the normal two-round rule. A repaired candidate receives a new tree identity.

Commit and PR

After ACCEPTED, deliver-ticket must:

• prove git write-tree still equals the accepted tree immediately before commit;
• commit the accepted tree as one commit;
• push normally through Husky;
• prove HEAD^{tree} equals the accepted tree;
• open/update one draft PR for Cut and publish Blueprint 4.1.0 from one exact converged release candidate #521.

GitHub Action automatically triggered here: CI

Trigger:

pull_request → main

Workflow:

.github/workflows/ci.yml

The PR CI owns:

• Mergeability preflight;
• Ubuntu full deterministic gate;
• Windows full deterministic gate;
• Node 18 distribution floor;
• ESLint 10 compatibility;
• operational-contract proof;
• documentation proof;
• deterministic topology replay;
• changed-production mutation planning/shards/aggregate;
• final PR verification.

Do not manually substitute local full-suite reruns for this exact-head PR authority.

If CI finds a defect, deliver-ticket treats the repair as a new candidate:

repair
→ focused evidence
→ accept-ticket
→ commit exact accepted tree
→ push
→ new exact-head PR CI

Shaper handoff

After current-head PR CI is green and the committed tree is still the accepted tree:

Owner: shape-ticket

Shape performs decision-fidelity review of:

• changeset semantics;
• 4.1 release framing;
• adopter-upgrade assessment;
• semver/version result;
• no unapproved scope expansion.

Only after Shaper reports APPROVED may the version PR be merged.

GitHub cannot record a formal APPROVE when the repository owner reviews their own PR; in that case a PR review comment carrying the explicit Shaper APPROVED verdict is the durable review.

---

Stage 2 — Merge the version PR and establish the exact 4.1.0 main candidate

Owner: deliver-ticket for the merge/handoff only when the owner explicitly authorizes that merge. Otherwise the owner merges.

The merge commit on main becomes the only candidate eligible to start release convergence.

GitHub Actions automatically triggered by the main push

A. CI

Trigger:

push → main

Workflow:

.github/workflows/ci.yml

On a main push, CI runs the deterministic gates:

• preflight;
• Ubuntu;
• Windows;
• Node 18;
• ESLint 10;
• operational-contract proof;
• documentation proof;
• deterministic topology replay.

Mutation jobs are PR-only and therefore do not run on the main push.

If and only if those deterministic main gates succeed, the Pack exact main candidate job runs and creates:

blueprint-candidate-<full-main-SHA>
  ├─ candidate.json
  └─ exact npm pack tarball

with 30-day artifact retention.

That CI-produced candidate is the only package artifact allowed for final field convergence.

B. Docs

Trigger:

push → main

Workflow:

.github/workflows/docs.yml

It builds TypeDoc + VitePress, runs docs checks, and deploys GitHub Pages.

This is expected after the version merge. It is not the release gate and does not replace field convergence.

C. Evidence feed

Workflow:

.github/workflows/evidence-feed.yml

It triggers on a main push only when workers/evidence-feed/** or the workflow itself changed.

A normal version-only release PR should not trigger a production Worker deploy. Do not modify evidence-feed files merely to make a release action run.

D. Terrain

Workflow:

.github/workflows/terrain.yml

Terrain is weekly or workflow_dispatch only. It is explicitly an upstream-template drift detector and not part of the PR or release gate.

Do not manually run Terrain as a substitute for the 4.1 field matrix. Run it manually only when separately investigating upstream template drift.

Gate to leave Stage 2

Do not begin authoritative field convergence until:

• the exact 4.1.0 main CI run is successful;
• the blueprint-candidate-<SHA> artifact exists;
• candidate.json identifies that same full main SHA and version 4.1.0.

If product/source or package inputs change after this point, stop. That creates a new product candidate and the older candidate remains historical evidence only. A later release-tooling-only commit does not become the product candidate and does not inherit field authority; after an older candidate has completed full convergence, such a tooling commit may publish that exact older candidate only through the Stage 5 recovery path.

---

Stage 3 — Select and run the full live release matrix

Scope owner: field-validation

Invoke field-validation after the exact successful 4.1.0 main candidate exists.

This skill owns only:

• full versus affected judgment;
• exact target roles;
• preservation of this ticket’s required scenario set;
• blast-radius reasoning after a repair.

For the initial/final 4.1 convergence, the answer is full convergence and the required set is the 16 scenarios authorized below.

field-validation does not stage candidates, invoke Agent CLIs, run Doctor/Inspect, write statuses, or publish.

Execution owner: repository field tooling + available live Agent runtime

Use the repository-owned candidate and field tooling to execute the selected scenarios.

For repository-owned greenfield controls, scripts/field-run.mjs already owns the starter fixture and supports:

--agents claude|codex
--topology layer-first|module-first
--candidate <candidate.json>

For #521 release authority, Agent-vendor diversity is not a hard gate. The authority is the scenario contract, exact candidate identity, independent fresh execution, visible postconditions, and reviewed evidence. A/B repeats may use the same available Agent runtime as long as they use independent disposable target copies and do not reuse mutated state or hidden prior answers.

For the pinned real-world adoption, sky transformation, and 3.2 lifecycle roles, use the repository field harness where it fits or the ticket-authorized explicit/manual matrix when the harness does not encode that role. In either case:

• every run uses the exact CI candidate;
• A/B repeats use independent disposable target copies;
• the report names the actual Agent/runtime used and does not relabel one runtime as another;
• no registry package may replace the candidate;
• post-Agent Doctor/Inspect stay visible;
• native project gates and required positive/negative controls are recorded;
• evidence must be durable, not left only in a temporary working directory.

2026-09-22 owner decision for 4.1: the earlier Codex+Claude pairing in this ticket was a diversity/stress-testing strategy, not a product compatibility guarantee. Requiring a paid external Agent vendor as a publication dependency makes release authority depend on account availability rather than Blueprint correctness. For this 4.1 release, two independent functional repeats per role are sufficient. This is a #521 release-contract clarification only; it does not change product source or the exact candidate bytes.

Because candidate 90d2a27c913ca95a29b498e94b90831534a06c92 already completed the 16 functional roles as independent A/B fresh runs, changing this ticket's authorization does not itself require another field execution. The existing 90d2a27 evidence may be recorded if each executed run maps one-to-one to the revised identifiers below and the reviewed report remains truthful about the single Agent runtime used.

This stage is not a GitHub Action. It is live Agent validation against the already-produced CI artifact.

Finding / repair loop

When a field finding appears:

1. classify it under the field-triage standard;
2. only a real release-blocking Blueprint defect enters repair;
3. use deliver-ticket for the repair PR;
4. repair PR follows the normal:
   accept-ticket → commit → PR CI → shape-ticket chain;
5. after merge, a new main SHA receives a new CI candidate;
6. invoke field-validation again to decide affected replay scope.

A successful affected replay records only repair evidence. It can never finish #521 and can never set final release authority.

After every blocker is repaired, run the complete 16-scenario full matrix again on one exact final candidate.

---

Stage 4 — Record field convergence on the exact 4.1.0 SHA

Owner: repository convergence recorder, after human review of the evidence.

Prepare the reviewed evidence JSON authorized by this ticket and run:

npm run field:converge -- record \
  --candidate <downloaded-candidate>/candidate.json \
  --evidence <round-evidence.json> \
  --issue 521

This is not a GitHub Action. The recorder itself:

• independently resolves/downloads the exact CI candidate;
• verifies candidate identity;
• verifies exact set equality for requiredScenarios and scenarios;
• derives release-blocker count from the reviewed findings;
• posts the durable convergence comment to Cut and publish Blueprint 4.1.0 from one exact converged release candidate #521;
• writes the commit status:

blueprint/field-convergence = success

on the exact candidate SHA.

For final authority it must prove:

scope = full
result = success
matrixComplete = true
releaseBlockers = 0
candidateSha = exact 4.1.0 main SHA

An affected record can produce only pending or failure.

Gate to leave Stage 4

Before tagging, independently check that the exact target SHA has blueprint/field-convergence = success and that its linked #521 evidence comment names the same full matrix and zero blockers.

---

Stage 5 — Publish the exact converged candidate

Owner: publication remains an explicit owner-authorized action. deliver-ticket may create/push a tag or invoke a publishing recovery run only when the owner explicitly authorizes publication.

The invariant is:

the bytes published to npm
=
the exact CI candidate that already has
blueprint/field-convergence = success

A newer release-tooling commit is not the product candidate and does not inherit the candidate's field status.

Path A — Normal tag-push publication

Use this when the converged candidate already contains the correct release workflow/gates.

Create:

v4.1.0

on the exact SHA that already has successful full field convergence and push the tag.

The tag-triggered .github/workflows/release.yml path:

1. checks out the tag target with full history;
2. runs lint / typecheck / tests / build / dist:verify;
3. requires tag semver = package.json.version;
4. requires a real Changesets version commit, matching changelog section, consumed changesets, and no pending package changesets;
5. requires exact-tag-SHA blueprint/field-convergence = success;
6. publishes npm with provenance;
7. creates GitHub Release notes from that candidate's CHANGELOG.md § 4.1.0.

Do not move the tag to a later tooling SHA merely to obtain newer release scripts. A later SHA has no field authority unless it independently completes convergence.

Path B — Recovery publication with newer release tooling

Use this only when the already converged candidate is valid but its embedded release workflow/gate is obsolete, so a normal tag-triggered run cannot publish it correctly.

The recovery entry is the workflow_dispatch path of the same .github/workflows/release.yml, executed from current main. It must keep these identities separate:

candidate SHA = product/release bytes with field authority
tooling SHA   = newer main commit that performs recovery publication

Recovery requirements:

• the candidate is an ancestor of the tooling SHA;
• the candidate comes from a successful main CI run;
• its unique exact-SHA CI artifact is still available and unexpired;
• the artifact manifest, package identity, CI run, and tarball digest are independently reverified;
• the newer Changesets and field gates are run against a clean detached checkout of the original candidate;
• the exact candidate must still own the full successful blueprint/field-convergence status;
• an existing stable tag must resolve to the candidate; if missing, it may be created only after verification;
• publication uses the original downloaded CI tarball with no rebuild or repack;
• provenance must distinguish the original candidate/run/artifact from the newer recovery tooling workflow/run;
• the artifact, tag, and field authority are reverified immediately before npm publication;
• any mismatch or unverifiable provenance stops publication;
• GitHub Release notes come from the candidate's changelog;
• the tooling SHA never receives a copied field-convergence status.

The recovery flow is two-step:

workflow_dispatch from main
candidate_sha=<validated candidate>
candidate_run_id=<candidate CI run>
tag=v4.1.0
publish=false
→ review verification result

then explicit owner authorization:

same inputs
publish=true
→ reverify
→ create/verify tag at candidate
→ publish original tgz with provenance
→ create GitHub Release

A successful publish=false run is verification evidence only. It does not authorize an automatic second run.

4.1.0 recovery authorization

For the current 4.1.0 release, #521 explicitly authorizes recovery publication of:

candidate_sha = 90d2a27c913ca95a29b498e94b90831534a06c92
candidate_run_id = 35738770473
tag = v4.1.0
artifact SHA-256 = 9b8a1b84a499d57775883c4b261391a7d60d565a97cd7c8965b2e0604fc64023

because that exact candidate already owns successful full field convergence and the old embedded Changesets gate incorrectly rejects post-version field repairs.

Required sequence for this release:

merge reviewed recovery tooling
→ run recovery with publish=false against 90d2a27c...
→ review that verification run
→ owner explicitly authorizes publication
→ rerun with publish=true using the exact same candidate/run/tag inputs
→ verify public npm + GitHub Release

No new field run is required solely because the recovery tooling lives on a newer SHA. The product candidate remains 90d2a27c...; the tooling commit is only the publisher.

If recovery itself requires changing the candidate bytes, package version, or field evidence, stop. That creates a new product candidate and returns to Stage 2/3/4.

---

Stage 6 — Public publication verification and issue closure

Owner: release delivery / owner verification.

After the successful publication workflow is green, whether normal tag-push publication or the authorized recovery path, verify externally:

• npm public metadata resolves @kekkai/blueprint@4.1.0;
• provenance is present as produced by the release workflow;
• GitHub Release v4.1.0 exists;
• its release notes correspond to CHANGELOG.md § 4.1.0;
• tag v4.1.0 still resolves to the converged SHA.

Only then is #521 complete and may be closed as completed.

Action summary

Moment	Skill / owner	GitHub Action
Shape release contract	shape-ticket	none
Edit changesets + run changeset version	deliver-ticket	none yet
Review staged version tree	accept-ticket	none
Push version PR	deliver-ticket	CI via pull_request; includes mutation
Review green version PR	shape-ticket	no new Action
Merge version PR to main	explicit owner merge / authorized Delivery	CI via push main; deterministic gates + candidate pack. Docs via push main. Evidence-feed only if its paths changed
Select final live matrix	field-validation	none
Run full A/B live Agent matrix	repository field tooling + available Agent runtime(s)	none
Record convergence	field:converge recorder	writes commit status, not an Action
Repair a field blocker	deliver-ticket → accept-ticket → PR CI → shape-ticket	CI on repair PR, then CI/Docs again after merge
Publish converged candidate normally	explicit publication authority	Release (tag) via tag push
Verify obsolete-tooling recovery	explicit publication authority	Release (tag) via workflow_dispatch, publish=false
Publish through recovery after owner approval	explicit publication authority	same workflow, same candidate inputs, publish=true
Confirm npm/GitHub publication	delivery/owner verification	release Action already completed
Close #521	after public verification	none

Implementation Notes

1. Freeze and edit the release inputs before versioning

Treat the Changesets version commit as the release-version preparation point, not the product freeze point. The product freeze point is the final exact candidate that passes complete field convergence.

Before running npx changeset version:

• re-read every pending changeset against current main;
• remove stale implementation claims and duplicate narrative;
• correct the source-preservation wording described above;
• keep semver intent at minor → 4.1.0;
• ensure the upgrade/remove entry reflects the final The upgrade → remove lifecycle dead-ends on a real 3.2 adoption #517 semantics: Doctor proves Blueprint/Vitest alias forms, source-preserving migration, deletion precedence, platform-neutral path identity, and comment-only references are not live wiring;
• keep docs-only evidence-feed work out of package release claims unless it genuinely belongs in the package changelog;
• add or identify one concise 4.1 release-framing passage that can be hoisted above Changesets’ generated Major/Minor/Patch headings in CHANGELOG.md.

Then run npx changeset version, review the generated package/version/lock/changelog diff, hoist the release framing, and make that assembled release candidate pass independent Acceptance before committing it under the repository’s current candidate lifecycle.

Do not tag a feature commit that still says 4.0.0.

2. Merge the 4.1.0 version candidate and bind release evidence to main CI

After the accepted version PR passes exact-head CI and Shaper review, merge it to main.

The successful main workflow for that exact SHA must produce the authoritative blueprint-candidate-<SHA> artifact and candidate.json.

Release field validation must consume that CI artifact. A locally rebuilt tarball or the #517 replay tarball is diagnostic evidence only.

Any later product/source commit creates a new candidate and does not inherit convergence authority. A later release-tooling-only commit may publish an older already-converged candidate only through the Stage 5 recovery path, and must publish that candidate's original verified CI artifact rather than treating the tooling SHA as a new product candidate.

3. Full 4.1 field matrix

4.1 changes both established adoption behavior and two new release-headline surfaces. The final matrix keeps the same 16 functional roles previously authorized, but release authority is now expressed as independent A/B execution rather than a Codex-vs-Claude vendor pairing.

The exact requiredScenarios for this release are:

Established real-world adoption controls

1. repeat-a/vue-pure-admin
2. repeat-b/vue-pure-admin
3. repeat-a/react-ddd-feature-folder
4. repeat-b/react-ddd-feature-folder
5. repeat-a/realworld-react-fsd
6. repeat-b/realworld-react-fsd
7. repeat-a/vue-vben-admin-web-antd
8. repeat-b/vue-vben-admin-web-antd

Pinned targets remain:

• Vue Pure Admin — pure-admin/vue-pure-admin@8affa5e5db1e05532d8833359c5153545055fc9c
• React DDD Feature Folder Architecture — emunhoz/react-ddd-feature-folder-architecture@f8dd1f53819b23e6993dd0297ecba0eb654a4d72
• RealWorld React FSD — yurisldk/realworld-react-fsd@969709a379b13935b4e1caae0ad8cad548e5879a
• Vue Vben Admin — vbenjs/vue-vben-admin@3f2d8bc1f2586a79f83d7b79c79ba818f800846a, application apps/web-antd

Each A/B pair must start from independent fresh disposable copies. These remain adoption controls, not topology-conversion requirements. Adopter debt, supported model boundaries, and environment limits are not Blueprint defects by themselves.

Bidirectional topology controls

9. repeat-a/sky-1945-lf-mf-lf
10. repeat-b/sky-1945-lf-mf-lf

Pin: taco3064/sky-1945@3a3c50a478338bc392bcaeaf4a13b7009a610998, prepared with the same valid LF authority used by the established transformation control.

Both repeats must independently execute Blueprint-generated LF → MF → LF guidance and verify the intermediate and restored states. Do not substitute a hand-authored final config.

4.1 greenfield runway controls

11. repeat-a/new-layer-first
12. repeat-b/new-layer-first
13. repeat-a/new-module-first
14. repeat-b/new-module-first

Use the repository-owned field starter so the exact candidate and live-Agent harness remain the authority.

These controls specifically prove #500’s changed posture:

• the proven-empty starter takes the direct scaffold path rather than brownfield authoring;
• LF starts from complete canonical preset governance;
• MF starts from the same governance with modules: [], without inventing a domain module;
• Doctor/Inspect and emitted enforcement agree with the generated config;
• the executing Agent does not reinterpret the empty project into an unsupported architecture.

Framework-specific deterministic React/Vue coverage remains CI’s job; these live controls own the Agent-facing greenfield decision boundary rather than duplicating every fixture × runtime combination.

4.1 lifecycle controls

15. repeat-a/sky-1945-3.2-upgrade-remove
16. repeat-b/sky-1945-3.2-upgrade-remove

Start independently from sky-1945@3a3c50a478338bc392bcaeaf4a13b7009a610998, follow Blueprint’s own refusal to establish the supported 3.2 source, and use the exact 4.1.0 candidate throughout.

Each repeat must independently prove:

3.1 refusal changes nothing
→ establish 3.2 adoption
→ upgrade --dry-run changes nothing
→ upgrade performs deterministic migration and stops only for measured semantic work
→ Agent completes review-retired-module-private from the actual declaration site
→ upgrade completes only with inspect/doctor complete
→ migrated config retains defineBlueprint/preset/comments and remains semantically equivalent
→ native lint/test/build pass
→ unwire real Blueprint references
→ remove --dry-run reports no false self/comment conflict
→ remove deletes the Blueprint config and completes
→ native lint/test/build pass

None of #517’s original three workarounds may be used.

A successful pre-version #517 replay is a negative/positive oracle for this scenario, not release authority for the new version SHA.

4. Classify findings instead of flattening them

For every live scenario record:

• candidate SHA/version/tarball digest/workflow;
• exact target, repeat id, and actual Agent/runtime used;
• material diff and architecture decision;
• Doctor/Inspect/deps and emitted ESLint evidence as applicable;
• native project gates;
• Agent feedback;
• every finding’s classification and releaseBlocking disposition.

A mechanical failure, false green, unsafe mutation, contradictory guidance, or Blueprint defect that prevents completion is release-blocking.

Adopter debt, an explicitly supported model boundary, an environment limit, or a known unverified alias form outside #517’s scope is not automatically release-blocking. It still must be visible in the report.

If a release-blocking defect is repaired, an affected replay may prove the repair but writes only pending/failure. The final authority still requires the complete 16-scenario matrix on one exact candidate.

For candidate 90d2a27c913ca95a29b498e94b90831534a06c92, the reviewed R5/final report's A/B runs may be mapped directly to these repeat-a/* and repeat-b/* identifiers. This ticket edit does not mutate the candidate and does not invalidate those executions.

5. Record convergence on this issue

The final reviewed evidence JSON must use:

• scope: "full";
• result: "success";
• requiredScenarios equal to the exact 16 identifiers above;
• scenarios equal to that same non-duplicated set;
• zero findings with releaseBlocking: true;
• a durable HTTPS report URL.

Record it with the repository-owned convergence recorder against this issue.

The resulting blueprint/field-convergence = success status must be on the exact 4.1.0 main SHA that will be tagged.

6. Prove publication

Only after exact-SHA convergence success, use one of the Stage 5 publication paths.

For normal publication, tag the exact converged SHA and let the tag-push job publish.

For the current 4.1 recovery case, use the owner-authorized workflow_dispatch path from newer main tooling while keeping the product candidate fixed at 90d2a27c913ca95a29b498e94b90831534a06c92. The recovery path must first pass with publish=false; only a separately authorized publish=true run may create/verify v4.1.0, publish the original CI tarball, and create the GitHub Release.

Both paths must preserve the same final invariants:

• v4.1.0 resolves to the exact converged candidate SHA;
• the Changesets/version-origin gate and exact-candidate field gate both pass;
• npm publishes @kekkai/blueprint@4.1.0 with provenance;
• GitHub Release v4.1.0 exists and uses CHANGELOG.md § 4.1.0 from the candidate;
• public npm metadata resolves version 4.1.0.

Close this issue only after publication is observable. A green field matrix or verification-only recovery run without a successful publish is not completion.

Acceptance Criteria

Release inputs and versioning

• All pending 4.1 package changesets are reviewed against current main and contain no stale or overstated claim.
• The migrated-config changeset says comments are preserved without falsely claiming every comment remains at the same byte position.
• The release changelog opens with a concise 4.1 product framing before generated change headings.
• The adopter upgrade assessment is recorded: every provable migration stays deterministic, and any remaining semantic work is represented by the existing structured lifecycle catalog or a justified new operation.
• npx changeset version produces @kekkai/blueprint@4.1.0, updates the lockfile and CHANGELOG.md, and consumes every pending package changeset.
• The assembled version candidate receives independent Acceptance before its commit and passes exact-head CI / Shaper review before merge.
• The accepted version change is merged to main and the exact successful main workflow produces a verified 4.1.0 candidate artifact.

Full release convergence

• All 16 ticket-authorized required scenarios execute against the same exact 4.1.0 candidate.
• Each of the four pinned real-world adopter controls completes twice as independent A/B runs from fresh disposable target copies.
• The sky-1945 LF → MF → LF transformation control completes twice independently through Blueprint-generated guidance.
• The repository-owned greenfield starter completes twice independently under layer-first and twice independently under module-first.
• The sky-1945 3.2 → 4.1 upgrade → semantic completion → remove lifecycle completes twice independently without any The upgrade → remove lifecycle dead-ends on a real 3.2 adoption #517 workaround.
• The evidence truthfully records the actual Agent/runtime used for every repeat; vendor/model diversity is useful supplementary evidence but is not a 4.1 publication gate.
• Required Doctor/Inspect/deps, emitted ESLint controls, native gates, material diffs, Agent feedback, and evidence limitations are recorded for each applicable scenario.
• Every observation has a reviewed classification and release-blocking disposition.
• The final evidence is scope: full, result: success, matrix-complete, and has zero release blockers.
• npm run field:converge -- record records the evidence on this issue and creates blueprint/field-convergence = success on the exact candidate SHA.

Publication

• The publication path preserves the exact converged candidate; a newer tooling SHA does not inherit its field status.
• For this 4.1 recovery, a publish=false workflow_dispatch run verifies candidate 90d2a27c913ca95a29b498e94b90831534a06c92, CI run 35738770473, tag v4.1.0, the original artifact digest, Changesets origin, and exact-SHA field authority.
• The owner explicitly authorizes the subsequent publish=true run after reviewing the verification-only result.
• The publishing run re-verifies the same candidate/run/tag inputs immediately before publication and publishes the original CI tarball without rebuild/repack.
• v4.1.0 points to the exact converged candidate SHA.
• npm publishes @kekkai/blueprint@4.1.0 with provenance that truthfully identifies both the original candidate artifact/run and the recovery publisher workflow/tooling SHA.
• GitHub Release v4.1.0 exists and its notes come from the candidate's CHANGELOG.md § 4.1.0.
• Public npm metadata resolves @kekkai/blueprint version 4.1.0.
• This issue is closed only after those publication checks are true.

Out of Scope

• New 4.1 product features after this release ticket begins. A newly discovered release-blocking correctness defect is repaired because it blocks this outcome; unrelated enhancement work waits for a later release.
• Expanding the supported upgrade window below 3.2.0.
• Making Doctor execute adopter Vite/Vitest configs or proving helper/wrapper-built aliases that the static model intentionally leaves unverified.
• Treating adopter architecture debt or a documented model boundary as a release defect by itself.
• Replacing the exact-main CI candidate with a local rebuild for convergence.
• Treating an affected replay as final release authority.
• Publishing an alpha/RC instead of the requested stable 4.1.0.
• Introducing versioned documentation archives, a docs version picker, monorepo/Turbo migration, or other repository-organization work unrelated to cutting this release.

[taco3064]

Release-preparation finding

During the 4.1 adopter-upgrade assessment, found a release blocker:

A repository adopted on 4.0 can receive 4.1 through npm/Renovate before blueprint upgrade runs. Because lifecycle state did not exist before 4.1, .blueprint-lifecycle.json has never existed in Git, but current logic sees installed >= LIFECYCLE_SINCE and classifies the missing state as lost. init / upgrade / remove then refuse and instruct the adopter to restore a file that never existed.

Disposition: release-blocking.

Repair: #522, merged to main as f970fe5 (Shaper review cleared on exact head 20dcb54; exact-head CI run 35445218255 green)

Boundary:

• state previously recorded in Git and now missing remains fail-closed;
• history that cannot be established remains fail-closed;
• only a state proven never to have entered Git history may use the pre-lifecycle bootstrap path.

The repair is on main; release preparation resumes from main@f970fe5, and changeset version runs on that base.

[taco3064]

Adopter upgrade assessment — 4.1.0 (on main@f970fe5)

Question: does 4.1 require adopter-side semantic work after deterministic upgrade code has done everything Blueprint can prove?

Answer: no new semantic work. The supported historical case still carries its existing judgment: a 3.2 source that declared module.private still gets review-retired-module-private. 4.1 adds nothing on top of that. UPGRADE_CATALOG is unchanged:

• supportedFrom: 3.2.0;
• migration legacy-unit-shape, introduced in 4.0.0;
• operation review-retired-module-private, introduced in 4.0.0;
• LIFECYCLE_SINCE = 4.1.0.

No 4.1 operation is added, and no introducedIn is rewritten.

Measured against v4.0.0..main@f970fe5 (non-test src/):

• Presets: without modules, reactPreset() and vuePreset() emit the same layer-first governance as 4.0.0. modules is a new optional input.
• Config validation:
  • modules: [] is newly accepted.
  • framework ∈ vue | react | auto and a non-empty layer does are newly enforced. The published 3.2.0 and 4.0.0 types already required both fields to be present; only the non-empty does is new. Every preset and init-generated config satisfies both.
  • Only a hand-written config that broke that contract is affected, and it stops with an error that names the field. How it stops depends on what is installed:
    • with a pre-4.1 package installed, the pending upgrade is already recorded when the target reconciles, so the rerun resumes;
    • with 4.1 already installed (for example through Renovate), upgrade refuses before recording anything, and the rerun after the fix is a fresh start that needs a clean worktree.
  • Either way, the fix is the field the error names. This release does not introduce a judgment call there.
• Lint emission, inspect, impact: the changes apply only to the modules: [] runway. Existing layer-first and module-first configs emit the same rules.
• Generated Agent contracts and handbooks gain lifecycle and module-growth sections. init re-emits them deterministically during upgrade.
• Doctor alias proof (The upgrade → remove lifecycle dead-ends on a real 3.2 adoption #517): alias forms that were previously unverified are now proven. A readable alias that points somewhere else is a real misconfiguration that doctor reports, not a migration.
• Source-preserving 3.2 migration (The upgrade → remove lifecycle dead-ends on a real 3.2 adoption #517): this is the existing deterministic legacy-unit-shape path. review-retired-module-private still owns the judgment about the retired module.private, and The upgrade → remove lifecycle dead-ends on a real 3.2 adoption #517's replay proved the 4.1 lifecycle executes it.
• Lifecycle-state recovery (fix: date an adoption whose lifecycle state never entered Git from its installed package (Part of #521) #522): changes how a checkpoint is proven when state never entered reachable Git history. It adds no adopter judgment.

Recorded with the 4.1.0 version candidate: #524 (commit 6c43137, tree cd5fe54, base main@f970fe5). It replaces #523, whose exact-head CI failed dist-verify on an outdated non-Git fixture; #524 carries the same version diff plus that fixture fix.

[taco3064]

Release-preparation finding — NON-BLOCKING for 4.1.0

While reviewing the lifecycle catalog validator, found a generality gap in catalogProblems(): it validates only supportedFrom → current packageVersion. A dependency cycle at an intermediate release can therefore be hidden if a later release supersedes all members of the cycle, even though an adopter upgrading in stages can still stop on the broken release.

Disposition: non-blocking for 4.1.0. The actual 4.1 catalog contains no relation graph that reaches this defect, so no supported 4.1 upgrade path is affected.

Repair: #525. It will validate every represented release checkpoint and ship as a 4.1.1 patch. The repair must not merge before v4.1.0 publishes, because it changes src/ after the frozen Changesets version SHA and would correctly invalidate the 4.1.0 release gate.

[taco3064]

Correction: catalog validator finding is fixed in 4.1.0

This updates the earlier "Release-preparation finding — NON-BLOCKING for 4.1.0" about catalogProblems(). Pre-release verification findings are fixed before release, so this one ships in 4.1.0, not as a 4.1.1 patch.

• Found by: the resolve.routes route property on main CI (run 35451635513, a013952). It found the same gap again on PR CI (run 35453525471).
• Repair: chore(release): re-version 4.1.0 with a route-complete catalog validator and the field release gate (Part of #521) #528, the single PR that carries the rest of Cut and publish Blueprint 4.1.0 from one exact converged release candidate #521 release preparation:
  1. unversion to 4.0.0;
  2. validate supportedFrom → every operation release, reporting unresolvable-route;
  3. the exact-SHA field-convergence release gate, formerly ci(release): require exact-SHA field convergence before publishing (Part of #521) #527;
  4. re-version to 4.1.0.
• Superseded: fix: validate every catalog release checkpoint (#525) #526 (closed). Reject upgrade catalogs that are invalid at an intermediate release checkpoint #525 closes when chore(release): re-version 4.1.0 with a route-complete catalog validator and the field release gate (Part of #521) #528 merges.
• Measurement (acceptance): 200,000 generator samples show 0 accepted catalogs that fail any route, down from 12 before the fix. Seeds 1–1400 of the property give 0 failures.