From 23a0a59e13fd32a7ea9c483ff017fdbc4d44e584 Mon Sep 17 00:00:00 2001
From: Kjell Tore Guttormsen <hello@fromaitochitta.com>
Date: Fri, 3 Jul 2026 05:37:16 +0200
Subject: [PATCH] =?UTF-8?q?docs(shared):=20S4=20=E2=80=94=20document=20sub?=
 =?UTF-8?q?tree=20sync=20commands;=20R1=20realized?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi
---
 shared/README.md | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/shared/README.md b/shared/README.md
index 7671a1f..7fb0e11 100644
--- a/shared/README.md
+++ b/shared/README.md
@@ -36,9 +36,30 @@ so the only thing that differs is the agent framework itself.
 
 - **Nothing in here may import or depend on a specific agent framework.** If it does,
   it does not belong in `shared/`.
-- **Repo layout (decision R1, 2026-06-26):** the shared core lives here for now. When
-  work on the sibling repository begins, it will be extracted into its own repository
-  (e.g. `portfolio-optimiser-commons`) via `git subtree split`, and both implementation
-  repos will consume it. This defers cross-repo plumbing until it is actually needed.
+- **Repo layout (decision R1, realized 2026-07-03):** the shared core lives in its own
+  repository, [`portfolio-optimiser-commons`](https://git.fromaitochitta.com/ktg/portfolio-optimiser-commons)
+  — the **source of truth**. Each implementation repo consumes it as a **git subtree**
+  at this unchanged `shared/` path (so tests and the `PORTFOLIO_SHARED_ROOT` default
+  resolver are unaffected). Do not edit commons content anywhere else without syncing.
+
+## Subtree sync (run from the consuming repo's root)
+
+The remote is registered as `commons`
+(`ssh://git@git.fromaitochitta.com/ktg/portfolio-optimiser-commons.git`).
+
+- **Pull** upstream changes from commons into this repo:
+
+  ```sh
+  git subtree pull --prefix=shared commons main --squash
+  ```
+
+- **Push** local `shared/` edits (committed here first) back to commons:
+
+  ```sh
+  git subtree push --prefix=shared commons main
+  ```
+
+Edits should preferably land in commons first and be pulled; pushing from a consumer
+is for small fixes made in place. Either way, commons remains the source of truth.
 
 See the target picture for the full architecture: `docs/plan/2026-06-26-maalbilde-agentic-loop.md`.