Migrating from v3 to 4.0

What changes

This guide prepares an existing adopter for 4.0.0. It is not evidence that a particular project has completed migration. Keep the currently approved baseline until the replacement has been reviewed and accepted. The release notes record the verified scope and known limitations.

The method still follows design, implementation, verification, review and documented decisions. The change is a more explicit boundary between business meaning, permitted execution and observed results. The kit also tightens installer recovery, assessment failure handling and public-document generation. It does not install a business-intent workspace or a production authorization service.

Existing integration	Migration action	Acceptance evidence
Copied instructions and operating card	Reconcile with current normative controls; preserve binding project rules and stack-specific commands.	Named owner reviews conflicts and the effective project instructions.
Local hooks	Review the selected adapter and verify actual host registration, event scope, output delivery and blocking semantics.	Harmless passing and adverse probes in the adopted host, not just a script exit code.
Repository checks	Retain required controls; identify exact check contexts, candidate scope and authorized exceptions.	Actual candidate results plus an assessment of effective server settings and visibility limits.
Documentation-sync integration	Use the complete wrapper/helper pair and committed mapping policy; update any old report parser.	Known mapped drift blocks; unreadable policy/history is unassessed; the intended clean case passes.
Copied/generated documentation	Declare publication sources and generated-file ownership; review the rendered audience boundary.	Reproducible generation, navigation/build checks and human content review.
Informal business-to-development handover	Pin accepted intent, context, glossary, profile, permitted effects and expected evidence.	The appropriate owner approves the exact package, not an evolving chat summary.
Future automated adapter	Treat the v1 schemas as structural records only.	Receiver-side authorization, reference resolution and adverse acceptance tests before real effects.

Why migrate deliberately

An installed file does not prove that a control ran. A passed check does not prove that every required check was selected. A documentation page does not approve the behavior it describes.

Record these distinctions during migration: installed, configured, runtime-verified, and approved for this use. Each assessment also needs an outcome: passed, failed, unassessed, or an explicitly justified inapplicability. An exception remains visible as an exception and cannot override a non-waivable obligation.

The governed factory model explains the surrounding roles and boundaries. The Business Intent Lifecycle explains the collaboration experience: AI proposes; the BA reviews first; the accountable business owner accepts meaning; engineering returns evidence for the candidate.

How to migrate

1. Inventory the approved baseline

Identify the project and repository revision, selected kit revision, installed local changes, host/runtime versions, existing checks and effective repository policy. Record data classification, approved model routes, business/technical/release owners and outstanding exceptions. Do not infer the deployed system's revision from a local checkout.

Keep a recoverable, access-controlled copy of the files and configuration in scope, including uncommitted changes where authorized. A Git commit does not capture untracked files or server settings. Do not export credentials or private records into a public migration log.

Choose a bounded migration window. Quiesce other writers and consumers while installing; individual file replacement is not atomic activation of an entire method bundle.

2. Inspect a complete pinned kit

Use Bash and Python 3.9+ with a complete kit checkout. The shell installer requires its adjacent Python implementation. These are kit prerequisites, not a requirement to rewrite the application in Python.

From that kit, preview the explicitly authorized target:

bash setup/bootstrap.sh /path/to/authorized-project --dry-run

First trial installation and an upgrade with deliberately edited local files in a disposable project. Review the plan before a real installation. Workflow templates are opt-in; inspect the installer's options and the proposed workflow before selecting them.

The synthetic scripts/adoption-smoke.sh probe checks a Go/JS dry-run and literal reference-stack tokens in the proposed instruction template. Matching lines require review; zero matches are not universal stack compatibility. A missing expected plan entry is unassessed. This probe does not install or activate anything in a real project.

3. Install, reconcile and retain evidence

After approving the inspected target and plan, run the same installer without --dry-run. Check its reported outcome and the actual resulting files.

• Existing CLAUDE.md and .claude/settings.json are preserved. Merge relevant changes manually; do not replace project commands or unrelated host settings with defaults.
• Unedited checksum-owned files can be upgraded. Edited files remain local, with proposed .s4u-new or numbered .s4u-new.N alternatives for review.
• Existing POSIX modes are preserved. The checksum receipt is not ownership of permissions; ACLs, extended attributes and filesystem ownership are outside the installer guarantee.
• .claude/.s4u-manifest records file checksum ownership. .claude/.s4u-kit-version identifies the kit version. Neither proves that proposals were merged, settings were activated, or the project conforms to the method.

Resolve each proposal explicitly: accepted, adapted with rationale, or retained local version with an owner and effect assessment. Keep unresolved items visible.

See installation and recovery for the actual recovery contract. A retained .s4u-install.lock requires investigation. Distinguish an active installer, precommit recovery, and a committed installation with incomplete cleanup. Inspect the journal, originals and real files together; never delete a lock merely to make a retry proceed.

4. Requalify integrations with changed behavior

Hooks and permissions. The supplied adapters target Claude. Another host needs a verified adapter. Plain successful output from the supplied advisory hooks is debug output, not proof of a model-visible reminder. The pre-push adapter covers recognized tool events, not every route to pushing code. The settings reference is an unapplied example, not a complete effective permission policy or a revocation of inherited permissions. See Appendix E.

Gate deployment. Gate scripts are not installed into the target project by bootstrap. Invoke them from the complete pinned kit or maintain a separately reviewed integration with all required helpers. Copying templates/scripts/check-doc-sync.sh without adjacent doc_sync_gate.py is unsupported.

Committed documentation policy. The documentation-sync gate reads docs/doc-pointers.yaml and mapped document existence from the pinned HEAD, not dirty workspace files. An absent committed mapping is explicitly inert. A project requiring the gate must protect policy presence and changes; deleting the mapping is not an authorized opt-out.

Do not rely on DOC_SYNC_BLOCKING: the current gate does not read that flag. Audit old flag-dependent integrations before replacing the gate. Activation depends on committed mapping presence and actual invocation; a caller expecting the flag to make a mapped assessment advisory can instead encounter blocking.

Its --base comparison is tip-to-tip, not an automatically selected merge base. The protected caller owns the correct comparison range. The --dry-run N output is now a JSON historical co-change proxy, not a false-positive estimate or permission to activate blocking. Update consumers of the older text output. A skip marker logs an assessed-drift exception but does not authenticate its approver. See the documentation-sync contract.

Server policy. Check names, workflow files and CODEOWNERS are not effective enforcement by themselves. Assess the actual repository against its reviewed policy, including bypass and visibility limits. The supplied repository-config checker is read-only; its fixture tests do not establish a customer's settings. Keep missing access unassessed.

Public documentation. For this kit, edit admitted canonical sources and regenerate; do not edit generated pages. The publication manifest allows sources, while the generated receipt tracks owned outputs. Neither establishes that all allowed prose is safe or accurate. Review HTML, search data and assets as well as Markdown.

5. Pin handover identities without inventing a runtime

The method version, project profile revision, protocol version and application version are separate identities. Updating defaults applies to eligible new work, not automatically to an in-flight mandate.

The candidate pack under contracts/v1/ describes context manifests, method profiles, execution mandates and result receipts. Its README defines the cross-record obligations. The examples are synthetic and unresolved; never dispatch them to a real system.

Schema validation alone cannot resolve a source, authenticate an approver, establish current permission, enforce revocation or prove complete receipt coverage. An automated adapter must implement those checks, including tenant/project equality, exact immutable references, approved model/capability selection, inherited check inventories and current fencing.

Until such an adapter is accepted, use an explicit human-controlled handover with equivalent scoped records and approvals. Do not label manual coordination an implemented authorization service.

Existing work remains pinned unless its owner approves a specific migration. New knowledge from a changing legacy system is a proposed amendment to affected intent/context, not a silent replacement of the baseline. For slow-moving legacy, urgent-fix notifications and periodic reconciliation may be sufficient; record the coverage limits. A new integration or side effect still needs engineering and review when the runtime has no supported extension for it.

6. Run a real bounded adoption cycle

Use setup/ADOPTION-TRIAL.md with one capability, named participants and agreed acceptance examples. Measure clarification delay, business/BA effort, meaningful defects caught, rework and cost—not only generated code or PR volume.

Include adverse cases appropriate to the selected scope: stale approved intent, a failing required check, unavailable evidence, or an incompatible integration. For any future automated adapter, also test replay, cross-project references, stale fences, missing receipt coverage and unauthorized waivers at its real admission/consumption boundary.

The owner decides what the evidence permits next. A successful synthetic trial is not a customer-system result, and an author-run trial is not independent external validation.

Evidence and completion

For kit maintainers, the repository CLAUDE.md and .github/workflows/canon-ci.yml identify the verification workflow. It includes shell/Python regressions, contract fixtures, canonical consistency, context budgets, inventory/classification checks, generated freshness, sidebar coverage, Node tests, typechecking and a production site build. Run these against the actual candidate; a checklist is not an execution receipt.

A project's migration record should identify:

• Exact before/after kit and project revisions, retained local proposals, applicable profile and approved scope.
• Tests actually selected/executed, subjects and outcomes; known failures, unassessed obligations and permitted exceptions.
• Effective host and server configuration assessments, approvers, recovery evidence and remaining limitations.
• The human adoption decision, separately from business acceptance, release and behavioral activation.

Do not declare completion while a mandatory obligation is unassessed. Optional future capabilities can remain absent if the accepted scope does not depend on them.

Recovery is not automatic downgrade

The installer's precommit recovery concerns its own selected local files. It does not revert server settings, model routes, deployed applications, data changes or external effects. After a successful migration, a rollback is a new controlled change: inspect the current state, restore only the approved compatible scope, preserve intervening work and reverify.

For in-flight work, decide explicitly whether to complete on the pinned baseline, drain, migrate, compensate or stop for human handling. Restoring old code or instructions cannot unsend a message or reverse a disclosure. Keep the compatible recovery path and authority visible before activation.