semantic-integration

name	semantic-integration
description	Use when integrating substantially diverged Git branches and merge or rebase is inadequate because it produces broad structural conflicts, or because mechanical application would place source changes into structures the target architecture has replaced and thereby lose their intent. Do not use when direct application and localized conflict resolution can preserve both branches' intended behavior.

Generated from blueprint.yaml. Do not edit this block by hand.

Instruction Interfaces:

These are LLM-readable instruction surfaces. Read and follow them directly; do not invoke the MCP server for them.

• git-workflow.interface.default@1 — Check branch and ownership boundaries first, then perform only explicitly authorized and exactly scoped Git mutations.

Semantic integration

REQUIRED INTERFACE: Use git-workflow.interface.default@1 before any Git mutation. Proceed only when it reports that the named branch and worktree are safe for the requested mutation. Treat any reported safety concern, unrelated change, or required approval as a stop condition until resolved by the user.

Freeze exact source and target tips, then integrate through a separate integration branch. Treat the target as the current architectural authority and every observable source effect as evidence that must be resolved. Keep source unchanged and do not move target until the approved closure. Do not silently select only changes that appear relevant.

Core mechanism

The first branch is target; the second branch is source. The mechanism is:

1. Create an isolated integration branch from target.
2. Determine what source intended and account for every observable source effect.
3. Recreate each accepted effect as new commits against target's current architecture. Do not merge source content into the integration tree.
4. Prove that the reconstructed tree preserves accepted source behavior and target guarantees.
5. Create a vacuous merge on the integration branch whose tree remains exactly the reconstructed tree and whose second parent is the frozen source tip.
6. Validate that exact merge commit, obtain closure approval, and fast-forward target to it.

Thus semantic reconstruction combines content; the final vacuous merge changes only ancestry. It records which frozen source history was integrated without mechanically applying that history's tree or patches.

Read references/git/run-ledger-template.md at the start. Keep one concise run ledger at a user-approved location and update it at phase boundaries, after each slice, and whenever a stall or deviation changes the plan. The ledger is the workflow state and preservation proof, not a transcript of commands.

Inputs

Require explicit roles:

• target: branch whose current architecture and guarantees must remain authoritative.
• source: branch whose intended effects must be preserved, adapted, superseded, or explicitly rejected.

Closure is not selectable: semantic integration always finishes through a vacuous merge commit that retains the semantic integration tree and records the frozen source tip as its other parent. Rebasing is permitted only to refresh the isolated semantic commits onto an approved target tip before constructing that merge marker; it never substitutes for merge closure.

Never infer the roles from branch order or names. Never rewrite either branch. Keep source fixed and do not move target before approved closure.

Phase 0: Freeze and recover

Before content changes:

1. Verify the repository, named current branch, and worktree state.
2. Resolve and record exact target and source commit IDs and their merge base.
3. Inspect attached worktrees. Report unrelated or uncommitted changes without stashing, deleting, or modifying them.
4. Create recovery refs for both frozen tips. Add a portable bundle when risk is high, branches may later be deleted, or the user requests one.
5. Create a dedicated integration branch from the frozen target.
6. Identify repository-owned validation entrypoints without running expensive suites yet.

Stop if an input ref moves unexpectedly. Ask whether to retain the frozen run or restart from the new tip.

Phase 1: Establish the preservation contract

Write short, evidence-based statements of:

• what the target currently guarantees and which architecture must survive;
• what the source was trying to add, remove, repair, or restructure.

Build four linked inventories:

1. A source-only commit ledger. For every commit, derive its purpose from the patch rather than its message alone. Cite at least one concrete diff anchor - a changed path plus a relevant symbol, test, configuration key, migration, or deletion - and record affected modules and dependencies on other source commits.
2. A merge-base-to-source endpoint inventory. Cover additions, modifications, deletions, renames, file modes, dependencies, configuration, public interfaces, tests, fixtures, generated artifacts, migrations, and persistent state effects.
3. A merge-base-to-target protection inventory. Index every target-only commit and endpoint effect that the integration must retain. Keep entries concise because the integration branch already starts from target.
4. A changed-on-both inventory. Give every path, interface, dependency, test, migration, or state surface changed by both branches an explicit semantic resolution and evidence; clean textual application is not sufficient.

Commit history, endpoint state, and overlap are independent checks. None may replace another. Where practical, record existing continuous-integration evidence or run bounded baseline checks on both frozen tips. Separate pre-existing failures from integration failures.

Gate 1 - preservation contract

Present frozen tips, both intent statements, all inventories, baseline evidence, and unresolved questions. Do not plan reconstruction until the user approves.

Phase 2: Plan semantic slices

Group work by coherent behavior, not chronology alone. For each slice record:

• source commits and endpoint items resolved;
• intended observable behavior;
• target modules likely to change;
• direct preservation versus architectural adaptation;
• focused validation evidence;
• dependencies, planned paths or modules, active-time estimate, and a hard stop.

Give every source commit exactly one final disposition:

• preserved: materially the same behavior remains;
• adapted: the behavior remains through a target-native implementation;
• superseded: the target already provides an equal or stronger result;
• rejected: the effect is intentionally excluded.

Every superseded or rejected source commit, endpoint item, or source test requires concrete evidence, consequences, and explicit user approval. Uncertainty remains unresolved; it never means irrelevant.

Prefer the smallest slices that remain coherent. Do not force one integration commit per source commit, and do not create batches so broad that failures lose attribution.

Gate 2 - reconstruction authority

Present the slice plan, proposed dispositions, validation plan, estimates, and expected conflict areas. Do not edit integration content until approved.

Phase 3: Reconstruct in slices

For each approved slice:

1. Reconstruct accepted behavior against the target's current architecture. Express every content change as a new semantic integration commit; never use a content merge or mechanical cherry-pick from source as a shortcut.
2. Treat source tests as requirements: carry them over, adapt them, replace them with stronger coverage, or obtain approval to reject them.
3. Run the cheapest focused check capable of testing the slice.
4. Commit one coherent checkpoint with normal hooks enabled.
5. Map its source commits and endpoint items to the integration commit and evidence immediately.
6. Report completed coverage, elapsed active time, and the next slice.

Stop on an unknown architectural choice, an accepted effect that cannot be preserved, unexpected repository changes, or evidence that invalidates the plan. Fix and revalidate an unproven slice before proceeding.

Maintain one source-test row per changed source test or test file. Record the resulting assertion, its disposition, focused result, and evidence that the repository's actual runner collects it. A green full run does not prove that a nested or custom-named test was collected.

If shared fixtures, runners, installers, schemas, migrations, or other cross-cutting test infrastructure changes, run the complete affected subsystem before the repository-wide gate. Do not discover predictable stale expectations one file at a time through repeated full runs.

Phase 4: Prove completeness

Require this traceability for every accepted source effect:

source commit -> intended behavior -> endpoint items -> target modules -> integration commit -> evidence

No source commit, source endpoint, target protection, changed-on-both item, or source-test row may remain unresolved.

Perform two bounded, independent audits, in parallel when independent agents are available:

1. Source-preservation audit: search for missing behavior, tests, files, deletions, interfaces, dependencies, migrations, and side effects.
2. Target-regression audit: search for weakened guarantees, architectural regressions, accidental compatibility layers, and validation gaps.

Give auditors the frozen refs, integration diff, and ledger rather than a desired verdict. If independent agents are unavailable, perform two explicitly separate passes and record the lack of independence as a residual limitation requiring explicit user acceptance at Gate 3. Resolve findings with focused checks.

Prepare the exact vacuous-merge candidate before final validation. First establish the approved target tip. If target moved from its frozen tip, stop, inventory and approve the new target and overlap effects, then rebase only the semantic integration commits onto that tip and refresh affected slice evidence and both audits. The resulting semantic tip must contain every approved target effect before candidate construction.

On the integration branch, create one vacuous merge whose first parent is the completed semantic integration tip and whose second parent is the frozen source tip. Use an ancestry-recording strategy that keeps the current integration tree, such as git merge -s ours --no-ff <frozen-source>; do not confuse this with the -X ours conflict preference. Prove that the candidate tree exactly equals its first-parent tree and that the approved target tip is an ancestor of the first parent. The merge message must name the frozen source tip, semantic integration tip, and run ledger. This vacuous merge commit is the closure candidate.

Refresh affected accounting and both audits after any rebase conflict or newly approved target delta. Record the exact closure-candidate commit and tree, then run the repository's complete required integration gates once from that committed state. Record commands, results, durations, skips, warnings, and environmental limitations. Any later change to the candidate commit or tree, or any target movement other than the authorized fast-forward to that exact candidate, invalidates those results and Gate 3; refresh them before closure.

Gate 3 - closure authority

Present accounting completeness, audit findings and resolutions, final validation, residual risks, elapsed time, and exact proposed vacuous-merge closure. Do not alter target history until the user approves.

Phase 5: Close

Verify that target still names the approved tip, then fast-forward it to the exact tested closure candidate. This fast-forward is the only permitted target mutation and must create no post-gate commit. Verify the vacuous merge's parents, unchanged tree, source pointer, target ancestry, and message evidence before and after the fast-forward.

After closure verify that target equals the tested closure-candidate commit and tree, expected ancestry holds, the worktree is clean, and recovery evidence remains available. Do not delete branches or push without separate explicit authorization.

Assurance without drag

• Generate commit and endpoint inventories once; reuse them throughout.
• Deep-read changed interfaces, tests, configuration, dependencies, migrations, stateful behavior, conflict areas, and unclear dispositions. Do not default to line-by-line re-analysis of an already-accounted patch.
• Run focused checks per slice, complete affected-subsystem checks after cross-cutting changes, and repository-wide gates only for the final candidate unless diagnosis requires a rerun.
• Run independent audits concurrently when possible.
• Keep ledger entries evidence-linked and concise; never paste full patches or command logs.
• Use five percent of active integration time as a diagnostic target for control overhead: ledger maintenance, approval packaging, and progress reporting beyond the semantic analysis, reconstruction, and validation the merge itself needs. If overhead grows beyond that, compress prose and reporting, but never reduce accounting or assurance coverage merely to meet the target.

Progress and deviation

Treat progress monitoring as a lightweight control loop, not another assurance audit, approval gate, or artifact:

1. Observe accounting completed, active time, current blocker, retries, validation state, and unplanned scope.
2. Compare them with the approved slice, estimate, and hard stops.
3. Choose one action: continue, split the slice, narrow or change validation, revise the affected plan, or stop for user input.

Reuse the existing ledger rows and evidence. Do not regenerate inventories, repeat passed checks, or write a separate progress document merely to monitor the run.

Report at phase boundaries and after each slice. Also report when 30 active minutes pass without closing a slice or ledger item, or when a phase reaches twice its estimate.

A progress report contains only current phase, completed versus total accounting, current slice or blocker, active time versus estimate, validation state, whether the plan remains credible, and the next adjustment.

On a stall, stop accumulating process work. Decide whether the slice is too broad, an architecture assumption is wrong, validation is mis-scoped, or user input is required. Replan only the affected portion.

At Gate 2 set configurable slice, phase, total-active-time, and repeated-failure limits. Stop and require reapproval when the same blocker fails twice, a limit is reached, repository state drifts, or work expands materially beyond approved paths, modules, or behavior. Do not normalize scope drift as implementation detail.

Non-negotiable safeguards

• Never modify, reset, delete, rebase, or force-update source, and never rewrite either frozen input commit. Do not move target before Gate 3; at closure only fast-forward it to the exact tested candidate.
• Never discard, stash, or overwrite unrelated changes.
• Never bypass hooks or required checks without explicit authorization.
• Never classify an uncertain source effect as irrelevant.
• Never claim preservation solely because target tests pass.
• Never retain Gate 3 approval after the tested candidate changes or target moves, except for the authorized fast-forward to that exact candidate.
• Never attach to target, delete branches, or push through implied approval.

Completion requires frozen recovery refs, complete commit and endpoint accounting, resolved source-test evidence, two clean assurance audits, accepted final validation, target-tree equality, correct closure ancestry, a clean worktree, and enough ledger evidence to investigate a later-discovered omission.