100%

Section 06 - non-destructive merge (INV-5)

Goal

Convert base-layer upgrade from clobber-with-.bak to a true non-destructive MERGE via marker-based local-block preservation: the base layer stays read-only / file-a-bug-upstream by DEFAULT, but explicitly-marked local regions are preserved across upgrade. Honors both the completed plan’s deliberate read-only design AND INV-5’s “merge not clobber”. Project rules / plans / bug-tracker stay untouched; no in-use file is removed.

Implementation Sketch

Today universal/adapted/orilang-only land via pure OVERWRITE (apply.py:181-194, _backup_and_write apply.py:200); the 3-way merge was deliberately removed (plans/completed/harness-distribution s-ec477a80 base-layer-readonly). The marker-merge primitives extract_local_block / substitute_local_block (render.py:157-228) exist but are DEAD (not wired into apply). The SyncReport.merged / conflicts fields (classify.py:368-370) are defined but unused.

  • Wire the dormant MERGE_BEGIN/MERGE_END local-block primitives into sync_file (apply.py:120): on upgrade, a canonical asset overwrites EXCEPT for regions the consumer wrapped in local-block markers, which are extracted from the existing target file and re-substituted into the new canonical content.
  • Wire SyncReport.merged / conflicts (classify.py:368-370).
  • Keep local-scaffold (rules), preserve[] globs, and conservative stale-detection (already preserve project artifacts); confirm bug-tracker/plans stay out of the manifest categories (untouched).
  • The completed plan’s tests/test_overlay.py + tests/test_acceptance.py pin “base-layer = read-only clobber” as PASSING invariants (test_base_layer_is_read_only_overwrite_on_resync, test_universal_overwrites_consumer_edit_with_banner_no_conflicts). These must be CONSCIOUSLY REWRITTEN to the new merge policy with a HISTORY note stating the resolved policy (banner-read-only base + marked-local-block merge) so the rewrite reads as a deliberate policy change, NOT test-weakening (INVERTED-TDD).

Spec & Rule References

INV-5 (mission, per the approved fork: marker-based local-block merge). impl-hygiene.md §INVERTED-TDD (conscious-rewrite-with-HISTORY, not weakening). Depends on s-00 bootstrap.

Layer Coverage

Tooling-scope: L1-L11 N/A. L12 = tests/test_overlay.py (rewritten) driving a real re-sync that preserves a marked local block + overwrites the rest. pytest gate: tests/test_overlay.py, tests/test_apply.py, tests/test_acceptance.py.

Work Items

  • Wire the dormant MERGE_BEGIN/MERGE_END local-block primitives (render.py:157-228) into sync_file so marked local regions survive upgrade while the rest overwrites.
  • Wire SyncReport.merged/conflicts (classify.py:368-370).
  • Consciously rewrite test_overlay.py + test_acceptance.py read-only-clobber pins to the merge policy with a HISTORY note (not test-weakening).

Fresh intel (regenerated)

{ “schema_version”: 1, “target”: { “kind”: “plan-section”, “ref”: “installable-harness/s-b6307641” }, “generated_at”: “2026-06-25T16:16:51.125215+00:00”, “graph_state”: { “head_sha”: “b74d6b9a”, “last_code_import_at”: “2026-06-25T16:15:20.702Z”, “embedding_stale”: false, “insights_stale”: false, “cpg_stale”: false }, “surfaces”: {}, “summary”: “intel-package[plan-section:installable-harness/s-b6307641] agent-authored dossier”, “degraded”: false, “dossier”: { “objective_symbols”: [], “tiers”: {}, “agent_authored”: true, “difficulty”: { “class”: “routine”, “research_online”: false, “research_mode”: “auto”, “signals”: [], “plan_dir”: “/home/eric/projects/ori_lang/plans/installable-harness” } } }

(full dossier: non-destructive-merge—s-b6307641.intel.json)