tech-log-frontend/docs/operations/template-merge-2026-08-17.md

Template merge — main → feature/techlog-ui-migration

Record of how the frontend template sync on main was integrated into the TechLog UI migration branch, and of every decision taken to resolve a conflict.

Why this direction first

The template sync landed on main while the UI migration ran in a worktree. Two orders were possible.

Merging the feature branch into main first would have resolved 15 conflicts directly on the integration branch: a bad resolution would already be on main, and it would have to be repaired forward, on the branch other work depends on.

Merging main into the worktree first keeps the resolution where the UI work lives. Every gate runs against the resolved tree before anything reaches main, and a resolution that turns out wrong is discarded by resetting one feature branch. main is then only ever fast-forwarded, so it never holds a state that was not already proved in the worktree.

That is the order used here.

Starting state

merge base	325a2a0
main	bdee07a — chore: sync the frontend template from a0fbafb to 5434760, 1 commit, 101 files, +3116/−448
feature/techlog-ui-migration	0355b64 — 29 commits
files changed by main	101
files changed by the feature branch	423
overlap	23

Rollback refs were created before touching anything:

backup/ui-before-template-merge  → 0355b64
backup/main-before-ff            → bdee07a

Pre-merge baseline on the feature branch

Captured so that a pre-existing failure could not be mistaken for a merge regression.

Gate	Result
check:types	pass
lint	pass
verify:documentation	PASS_SCOPED
tests/unit + tests/component	1815 passed / 101 failed

The 101 failures were confined to tests/unit/ci-artifact-contract.test.ts (19) and tests/unit/ci-workflow-generation.test.ts (82) — sandbox subprocess gates that cannot run in this environment.

Conflicts and how each was decided

15 conflicts. The rule applied throughout: keep the template's mechanism, keep the product's content, and never invent a third state that neither branch would accept.

Deletions the UI migration made deliberately (2)

Path	Decision
src/presentation/examples/platform-overview-page.tsx	deletion kept
tests/visual/.../platform-overview-light-chromium-visual-linux.png	deletion kept

main modified both; the feature branch deleted them in c5c8b94. Nothing on the branch references either, so the deletion stands.

src/features/installed-feature-contracts.ts

The template introduced a product manifest: registries are composed from INSTALLED_PRODUCT_FEATURES so that narrowing the selection withdraws a feature's routes, operations, schemas and messages.

The manifest composition is kept for operations, schemas, mappers and invalidation. The route registry is deliberately not composed from contract.routes, because the reference feature still declares REFERENCE_RESOURCE_* routes whose screens this product deleted during the migration. Reducing over them would register paths with no component behind them — a typed deep link resolving to nothing.

The registry therefore lists the platform routes (empty on this branch) and TechLog's. This was caught by running the gates: the first resolution did compose from contract.routes, and tests/unit/product-features.test.ts rejected it.

ROUTE_FEATURE_OWNER was narrowed to registered routes for the same reason. Attributing an unregistered route to a feature claims the kill switch governs something no router can mount.

src/features/installed-feature-runtimes.tsx

The template gates the reference feature's route codecs and components on the manifest. This product deleted that feature's presentation layer, so the import does not resolve and there is nothing to gate. The gating was removed and the reason recorded in the file; it belongs back the day those screens return.

Consequence: this file no longer references the manifest, so it was moved to the exempt list in tests/unit/product-features.test.ts with the same note. tests/component/product-feature-switch.test.tsx was rewritten to hold the invariant that still applies here — no registered route without a component — which is exactly the trap the first resolution fell into.

src/features/installed-feature-adapters.ts

Both the manifest check and TechLog's input are kept. The reference feature's input stays Partial because the manifest may narrow it out; TechLog's is total because it is this product's own UI and is always installed. A build that narrows the reference feature out still ships TechLog.

src/features/installed-feature-messages.ts

The template's rationale — message keys stay total so message() cannot become partial — is kept, and TechLog's catalog is merged in on the same terms.

src/presentation/routes/app-router.tsx

The template looked the route definition and runtime component up by id inside the route element; this branch passes both as props from the grouped route contract. The prop-driven signature is kept.

The template's feature kill switch is adopted: a route whose owning feature the runtime document disabled renders the disabled surface instead of mounting. Withdrawing it from navigation alone would leave a working deep link. getRoute was dropped from the imports because the definition arrives as a prop.

vite.config.ts

Two independent additions — TechLog route chunking and routerBasePath — both kept. A brace was lost in the first concatenation and caught by check:types.

scripts/build-frontend.ts

Both new steps exist in the merged body, so the header comment was renumbered: runtime config becomes step 4, the TechLog serving boundary step 7, the release manifest step 8, and the inline step comments were corrected to match.

scripts/test-performance.ts

The template clicked a navigation link before measuring; this product measures its own landing route, which goto already reached, and has no targetLabel. The click was dropped. The template's lesson was kept as a comment because it applies to the next click that lands here: Playwright matches accessible names by substring, so a nav entry can also match a call to action and resolve to two links — a strict-mode violation that produces no performance evidence at all.

Derived baselines — recomputed, not chosen (3)

scripts/contracts/ci-gates.ts, tests/unit/task3-selective-integration.test.ts and tests/unit/ci-workflow-generation.test.ts each pin counts and a digest describing the gate contract. Neither side's numbers describe the merged config/ci/gates.json, so taking either would have been wrong. They were recomputed from the merged file:

Value	Result
canonical gate shape SHA-256	5063586d799f51de94c0f0ddaf9b75e180825bba5051bc309550425013ea81ef
gates	27
commands	82
command references	94
evidence artifact references	107
artifacts	128 (126 product + 2 from the template)

README.md, docs/accessibility/manual-checklist.md

The template enumerated its own example routes. Replacing them with generic prose broke verify:documentation, which requires both documents to name every installed route id — a rule the template sync itself introduced. Both documents now enumerate this product's 27 routes.

Result

Merge commit parents: 0355b64 (UI) and bdee07a (template).

Gates on the merged tree

Gate	Result
check:types	pass (6 projects)
lint	pass, --max-warnings=0
check:architecture	399 modules, 1232 dependencies, 12 fixtures pass
check:adapter-inventory	120 files, 5 importers of the shared abort primitive
check:remediation-ledger	25 dispositions, 0 open
check:diagnostics	8 diagnostics, 5 telemetry producers
check:i18n	197 keys, 4 locales
check:design-system	48 tokens
verify:documentation	PASS_SCOPED
test:integration	81 passed
test:recipes	17 passed
test:runtime-schema	40 passed
tests/unit + tests/component	1851 passed / 98 failed

The 98 failures are the same two sandbox files as the baseline — ci-workflow-generation (82) and ci-artifact-contract (16, down from 19). No file fails that did not fail before the merge.

Mistake made during this merge

git stash was run inside the worktree while the merge was still in progress, to compare a gate against the pre-merge tree. That removed MERGE_HEAD: the resolved content survived, but git no longer knew a merge was underway, and committing then would have produced a single-parent commit — leaving main off the ancestry and breaking the fast-forward that step 2 depends on. MERGE_HEAD was restored to bdee07a before committing, and the resulting commit has both parents.

To compare against a pre-merge state, use a separate checkout rather than stashing an in-progress merge.

Correction after review

Two of the resolutions above were wrong, and were fixed in a follow-up commit.

The template's demonstration screens — platform-overview-page, the UI and state galleries, the auth example and the reference feature's screens — exist to explain the template. A product replaces them with its domain, and deleting them is the expected end state, not a regression. Two gates were nevertheless coupled to them, and the first resolution accommodated that coupling instead of fixing it.

tests/unit/product-features.test.ts — a hard-coded exemption became a rule

The guard requires every installed registry to compose from the manifest. installed-feature-runtimes.tsx was added to its exempt list once the reference feature's presentation layer was gone. That silenced the guard for that file permanently.

It now derives its own scope: a registry must gate on the manifest when it imports a module belonging to a manifest-declared feature. A product whose registries compose only its own domain drops out of the rule honestly, and the guard fires again the moment a declared feature is imported without gating — verified by removing the manifest reference from installed-feature-adapters.ts and watching the guard fail. A counter asserts the sweep is still watching at least one file, so an empty scope cannot pass silently.

tests/component/product-feature-switch.test.tsx — coverage restored

The end-to-end kill-switch assertions were replaced with composition checks because the screens they rendered were gone. The mechanism under test is the ownership lookup plus isFeatureActive, which has nothing to do with which screens ship, so the ownership map is now the fixture: one real registered route is attributed to a real installed feature, and the router, shell, components and codecs are all the product's own. The deep-link half is asserted end to end again.

What that restoration exposed

The navigation-withdrawal half is not implemented in this product. It lives in the template's PrimaryNavigation, and this product does not render the template's AppShell at all — the public site header is a hand-written list of paths in src/features/tech-log/presentation/public/components/site-header.tsx, and the studio has its own shell.

So a disabled feature's route is refused by the router but its link would still be advertised. That is harmless only while no feature-owned route is navigable, which is true today and is now asserted. If that assertion fails, the header has to consult ROUTE_FEATURE_OWNER — or navigation has to move back onto NAVIGATION_ROUTES — before the route ships.

Follow-ups this merge deliberately did not decide

1. TechLog is outside the product manifest. It is composed directly rather than as a SelectableProductFeature, so the runtime kill switch does not govern it. That is defensible — a product's own domain is not an optional feature — but it means the switch governs nothing user-visible today.
2. The reference feature declares routes it cannot serve. Its screens were deleted with the rest of the demonstration UI, but its contract still declares REFERENCE_RESOURCE_* routes. Either the declarations go, or the feature does. TechLog does not import it (git grep reference-feature -- src/features/tech-log is empty), so removing it is a live option and FE-GATE-020 exists to prove it can be removed.
3. The public site header is not feature-aware. See above.