refactor: unify monorepo structure (ADR-0009)

Rename Layer 1 from shared-utils to utils, collapse per-project
AGENTS.md to a single root contract, and lock in the unified
project shape across the workspace.

Layer 1 rename
- Folder: projects/shared-utils/ -> projects/utils/
- Distribution: llm-patch-shared -> llm-patch-utils (0.1.0 -> 0.2.0)
- Import package: llm_patch_shared -> llm_patch_utils
- All 26 .py source files updated; engine + wiki-agent pyproject deps
  switched to llm-patch-utils.

AGENTS contract
- Deleted projects/{llm-patch,utils,wiki-agent}/AGENTS.md.
- Rewrote root AGENTS.md as the single agent contract.
- Added .github/instructions/utils-boundary.instructions.md with
  applyTo: projects/utils/** preserving the stdlib-only rule.
- Updated engine-boundary, usecase-boundary, python-style instructions.

Tooling
- pyproject.toml: [tool.uv.sources], isort known-first-party.
- .pre-commit-config.yaml: mypy-shared-utils -> mypy-utils.
- .github/workflows/{ci,release}.yml: matrix + tag glob updates.
- .github/pull_request_template.md: dist label + AGENTS reference.
- tools/check_layering.py: LAYERS + PROJECT_PACKAGE map updated.
- tools/scaffold_project.py: stops emitting per-project AGENTS.md;
  uses llm-patch-utils dependency.
- Makefile: test-shared -> test-utils.

Documentation
- SPEC.md: layered-architecture diagram, R-1.3/R-1.4 wording, naming
  conventions, glossary, new section 1.1 Project Shape, section 9
  rewritten to drop AGENTS.md from scaffold artifacts.
- README.md: workspace layout + project table + adding-a-use-case.
- ADR-0009: full MADR record of the rename + AGENTS collapse.
- ADR-0001/0002/0004/0005: status callouts referencing ADR-0009;
  historical bodies preserved by convention.
- docs/EXTENDING.md, docs/REGISTRY_PROTOCOL.md, projects/wiki-agent/README.md:
  prose updates.
- projects/utils/{README,CHANGELOG}.md updated; CHANGELOG records the
  breaking rename in [0.2.0].
- docs/adr/README.md index: added ADR-0008 + ADR-0009; retitled
  ADR-0005.

Verification
- python tools/check_layering.py -> OK
- engine: 464 passed, 12 skipped
- utils:  2 passed
- wiki-agent: 46 passed
- Get-ChildItem -Recurse -Filter AGENTS.md -> exactly 1 (root)

No behavioural changes. Public engine API unchanged.

Author: seismael

.github/instructions/engine-boundary.instructions.md

@@ -1,6 +1,6 @@
 ---
 applyTo: "projects/llm-patch/**"
-description: "Engine boundary rules: no imports from use-cases; preserve public API; preserve test baseline 216 passed / 3 skipped."
+description: "Engine boundary rules: no imports from use-cases; preserve public API; preserve test baseline 464 passed / 12 skipped."
 ---
 
 # Engine Boundary Rules
@@ -14,15 +14,16 @@ implement the engine layer of the architecture in
 
 - **Do not import** from `llm_patch_wiki_agent` or any other use-case
   package. Dependency direction is one-way (use-cases → engine).
-- **Do not import** from `llm_patch_shared` until that dependency is
-  explicitly added via ADR. Today the engine has no shared-utils dep.
+- **May import** from `llm_patch_utils` for shared error types only
+  (per [ADR-0005](../../docs/adr/0005-engine-shared-errors.md)). Any
+  broader engine usage of utils helpers requires a new ADR.
 - **Do not edit** existing ABCs in `core/interfaces.py` to add a new
   capability. Add a new ABC or a new Strategy implementation instead
   (Open/Closed).
 - **Preserve the public API**: anything currently re-exported from
   `src/llm_patch/__init__.py` stays re-exported (additions OK, removals
   require a major bump + ADR + deprecation).
-- **Preserve the test baseline**: `216 passed, 3 skipped`. Any PR that
+- **Preserve the test baseline**: `464 passed, 12 skipped`. Any PR that
   changes the count must justify the change in its description.
 
 ## When Adding a New Source / Generator / Storage / Provider / Runtime

.github/instructions/python-style.instructions.md

@@ -40,7 +40,7 @@ from [SPEC.md](../../SPEC.md). Where this file and `SPEC.md` disagree,
 
 ## Errors
 
-- Derive new exception types from `llm_patch_shared.errors.LlmPatchError`
+- Derive new exception types from `llm_patch_utils.errors.LlmPatchError`
   (or one of its subclasses). Never raise bare `Exception`.
 - Catch the narrowest exception possible. Don't swallow exceptions
   silently — log or re-raise.

.github/instructions/usecase-boundary.instructions.md

@@ -33,6 +33,6 @@ implement the use-case layer of the architecture in
 ## Allowed Runtime Dependencies
 
 - `llm-patch` (workspace).
-- `llm-patch-shared` (workspace).
+- `llm-patch-utils` (workspace).
 - `click>=8.0`.
 - Anything else requires an ADR.

.github/instructions/utils-boundary.instructions.md

@@ -0,0 +1,42 @@
+---
+applyTo: "projects/utils/**"
+description: "Utils boundary rules: stdlib-only; no imports from engine or use-cases; new runtime deps require an ADR."
+---
+
+# Utils Boundary Rules — `llm-patch-utils`
+
+These rules apply to every file under `projects/utils/`. They implement
+Layer 1 (Utilities) of the architecture in
+[SPEC.md §1](../../SPEC.md#1-architectural-layering),
+[ADR-0002](../../docs/adr/0002-layered-architecture.md), and
+[ADR-0009](../../docs/adr/0009-monorepo-structural-unification.md).
+
+## Hard Rules
+
+- **Stdlib only**. Adding any third-party runtime dependency requires
+  an ADR.
+- **Never import** from `llm_patch` or any `llm_patch_<usecase>`
+  package. Dependencies flow downward only (utils ← engine ← use-cases).
+- **No domain logic, no I/O at import time, no network**. This package
+  hosts genuinely cross-cutting primitives only (logging adapters,
+  config helpers, telemetry hooks, common error types).
+- **Public API is sacred**: anything re-exported from
+  `src/llm_patch_utils/__init__.py` is part of the published surface.
+  Removing or renaming a public symbol requires a major version bump,
+  an ADR, and a deprecation cycle.
+
+## When Adding a New Symbol
+
+1. Confirm two or more downstream projects actually need it. If only
+   one needs it, keep the helper inside that project instead.
+2. Add a unit test in `tests/`.
+3. Re-export the symbol from `src/llm_patch_utils/__init__.py` and add
+   it to `__all__`.
+4. Bump the version in `pyproject.toml` per SemVer and add a
+   `[Unreleased]` entry to `CHANGELOG.md`.
+
+## Test
+
+```pwsh
+uv run --package llm-patch-utils pytest -q
+```

.github/pull_request_template.md

@@ -1,6 +1,6 @@
 <!--
 Thanks for contributing! Please confirm the items below before requesting review.
-See SPEC.md and the per-project AGENTS.md for the full rules.
+See SPEC.md and the root AGENTS.md for the full rules.
 -->
 
 ## What & Why
@@ -10,13 +10,13 @@ See SPEC.md and the per-project AGENTS.md for the full rules.
 ## Affected Project(s)
 
 - [ ] `llm-patch` (engine)
-- [ ] `llm-patch-shared`
+- [ ] `llm-patch-utils`
 - [ ] `llm-patch-wiki-agent`
 - [ ] tooling / docs / CI only
 
 ## Checklist
 
-- [ ] Read the relevant `AGENTS.md` (root + per-project).
+- [ ] Read the root [AGENTS.md](../AGENTS.md) and the relevant `.github/instructions/*.instructions.md`.
 - [ ] Tests added/updated; **engine baseline preserved** (or change justified below).
 - [ ] `make check` passes locally (`lint + typecheck + check-layering + test`).
 - [ ] Public API change? → updated `__init__.py` `__all__`, `CHANGELOG.md`, and bumped version per SemVer.

.github/workflows/ci.yml

@@ -31,8 +31,8 @@ jobs:
       - name: Mypy (engine)
         working-directory: projects/llm-patch
         run: uv run mypy src
-      - name: Mypy (shared-utils)
-        working-directory: projects/shared-utils
+      - name: Mypy (utils)
+        working-directory: projects/utils
         run: uv run mypy src
       - name: Mypy (wiki-agent)
         working-directory: projects/wiki-agent
@@ -47,7 +47,7 @@ jobs:
         python: ["3.11", "3.12"]
         project:
           - llm-patch
-          - llm-patch-shared
+          - llm-patch-utils
           - llm-patch-wiki-agent
     steps:
       - uses: actions/checkout@v4
@@ -63,8 +63,8 @@ jobs:
           if [ "${{ matrix.project }}" = "llm-patch" ]; then
             cd projects/llm-patch
             uv run pytest -q
-          elif [ "${{ matrix.project }}" = "llm-patch-shared" ]; then
-            cd projects/shared-utils
+          elif [ "${{ matrix.project }}" = "llm-patch-utils" ]; then
+            cd projects/utils
             uv run pytest -q
           else
             cd projects/wiki-agent

.github/workflows/release.yml

@@ -5,7 +5,7 @@ on:
   push:
     tags:
       - "llm-patch-v*"
-      - "llm-patch-shared-v*"
+      - "llm-patch-utils-v*"
       - "llm-patch-wiki-agent-v*"
 
 jobs:

.pre-commit-config.yaml

@@ -23,12 +23,12 @@ repos:
         language: system
         pass_filenames: false
         files: '^projects/llm-patch/.+\.py$'
-      - id: mypy-shared-utils
-        name: mypy-shared-utils
-        entry: uv run --package llm-patch-shared mypy --config-file projects/shared-utils/pyproject.toml projects/shared-utils/src projects/shared-utils/tests
+      - id: mypy-utils
+        name: mypy-utils
+        entry: uv run --package llm-patch-utils mypy --config-file projects/utils/pyproject.toml projects/utils/src projects/utils/tests
         language: system
         pass_filenames: false
-        files: '^projects/shared-utils/.+\.py$'
+        files: '^projects/utils/.+\.py$'
       - id: mypy-wiki-agent
         name: mypy-wiki-agent
         entry: uv run --package llm-patch-wiki-agent mypy --config-file projects/wiki-agent/pyproject.toml projects/wiki-agent/src projects/wiki-agent/tests

AGENTS.md

@@ -1,18 +1,22 @@
 # AGENTS — Root Contract
 
-This file is the **entry point** for any agent (human or AI) working in
-this repository. It is intentionally short. Authoritative rules live in
-[SPEC.md](SPEC.md). Per-project specifics live in each project's own
-`AGENTS.md` under [projects/](projects/).
+This file is the **single, authoritative agent contract** for the entire
+repository. It is intentionally short. Authoritative engineering rules
+live in [SPEC.md](SPEC.md). Scoped, machine-loaded rules live under
+[.github/instructions/](.github/instructions/) and are applied
+automatically by VS Code / Copilot via `applyTo` globs (see ADR-0009).
+
+There are **no per-project `AGENTS.md` files** — the same checklist and
+hard rules apply to every project under [projects/](projects/).
 
 ## Repository Shape
 
-This is a **uv workspace monorepo**. The structure is:
+This is a **uv workspace monorepo** with a unified per-project layout:
 
 ```
 projects/
   llm-patch/         engine — the generic Ingest → Compile → Attach → Use framework
-  shared-utils/      cross-project, stdlib-only utilities
+  utils/             cross-project, stdlib-only utilities (llm_patch_utils)
   wiki-agent/        first downstream use-case (wiki-specialized agent)
 docs/
   adr/               Architecture Decision Records (MADR format)
@@ -25,43 +29,70 @@ SPEC.md              the engineering specification (binding)
 AGENTS.md            this file
 ```
 
+Every `projects/<name>/` follows the same flat layout — see
+[SPEC.md §1.1 Project Shape](SPEC.md):
+
+```
+projects/<name>/
+  pyproject.toml      # name = "llm-patch[-<usecase>]"
+  README.md
+  CHANGELOG.md
+  src/<import_pkg>/   # llm_patch[_<usecase>]
+  tests/
+```
+
 ## Mandatory Pre-Change Checklist
 
 Before changing any file, the agent must:
 
-1. **Read the closest `AGENTS.md`** — the per-project file overrides /
-   refines this root file. If editing a use-case, read the use-case's
-   `AGENTS.md` and the engine's `AGENTS.md`.
+1. **Read this file** and the relevant scoped instructions under
+   [.github/instructions/](.github/instructions/) (engine boundary,
+   utils boundary, use-case boundary, python style, tests).
 2. **Re-read the relevant section of [SPEC.md](SPEC.md)** — especially
-   Dependency Direction and Public API Stability.
+   Dependency Direction (§1) and Public API Stability (§3).
 3. **Write or update tests first** — the project follows TDD for new
    public API. See SPEC §Testing.
 4. **Run `uv run --package <project> pytest -q`** for the affected
    project(s) and confirm baselines hold:
-   - `llm-patch` engine: `216 passed, 3 skipped`
-   - `llm-patch-shared`, `llm-patch-wiki-agent`: smoke tests pass.
+   - `llm-patch` engine: `464 passed, 12 skipped`.
+   - `llm-patch-utils`, `llm-patch-wiki-agent`: smoke tests pass.
 5. **Add an ADR** under [docs/adr/](docs/adr/) for any cross-cutting,
    architectural, or dependency-direction-affecting decision. Use
    [docs/adr/0000-template.md](docs/adr/0000-template.md).
 
 ## Hard Rules (do not violate without an ADR)
 
-- **Dependency direction is one-way**: use-cases → engine → shared-utils.
+- **Dependency direction is one-way**: use-cases → engine → utils.
   No reverse imports. Enforced by [tools/check_layering.py](tools/check_layering.py).
 - **Public API is sacred**: only symbols re-exported from a project's
   top-level `__init__.py` are public. Use-cases must consume only the
   public API of the engine.
 - **No behavior changes alongside structural changes** in the same PR.
 - **No module-level side effects** (no I/O, no network) at import time.
+- **No per-project `AGENTS.md`**: scoped rules belong in
+  `.github/instructions/*.instructions.md` with an `applyTo` glob.
+
+## Adding a New Use-Case Project
+
+```pwsh
+uv run python tools/scaffold_project.py <name>
+```
+
+This materializes the unified layout above. The new project consumes
+the engine via its public API and may depend on `llm-patch-utils`. See
+[SPEC.md §9](SPEC.md) and use [projects/wiki-agent/](projects/wiki-agent/)
+as the reference implementation.
 
 ## Where to Look for What
 
 | If you want to… | Read… |
 |---|---|
 | Understand the system architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
 | Understand the engineering rules | [SPEC.md](SPEC.md) |
-| Add a new use-case project | [tools/scaffold_project.py](tools/scaffold_project.py) + this file |
-| Change the engine | [projects/llm-patch/AGENTS.md](projects/llm-patch/AGENTS.md) |
-| Change shared utilities | [projects/shared-utils/AGENTS.md](projects/shared-utils/AGENTS.md) |
-| Change the wiki agent | [projects/wiki-agent/AGENTS.md](projects/wiki-agent/AGENTS.md) |
+| Add a new use-case project | [tools/scaffold_project.py](tools/scaffold_project.py) + [SPEC.md §9](SPEC.md) |
+| Change the engine | [.github/instructions/engine-boundary.instructions.md](.github/instructions/engine-boundary.instructions.md) |
+| Change utilities | [.github/instructions/utils-boundary.instructions.md](.github/instructions/utils-boundary.instructions.md) |
+| Change a use-case | [.github/instructions/usecase-boundary.instructions.md](.github/instructions/usecase-boundary.instructions.md) |
+| Write Python | [.github/instructions/python-style.instructions.md](.github/instructions/python-style.instructions.md) |
+| Write tests | [.github/instructions/tests.instructions.md](.github/instructions/tests.instructions.md) |
 | See past architectural decisions | [docs/adr/README.md](docs/adr/README.md) |

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help sync test test-engine test-shared test-wiki-agent lint typecheck check check-layering check-coverage build clean adr
+.PHONY: help sync test test-engine test-utils test-wiki-agent lint typecheck check check-layering check-coverage build clean adr
 
 # ─────────────────────────────────────────────────────────────
 #  llm-patch monorepo — workspace fan-out commands
@@ -22,13 +22,13 @@ sync: ## Sync the entire workspace
 test-engine: ## Run engine tests
 	cd projects/llm-patch && $(UV) run pytest -q
 
-test-shared: ## Run shared-utils smoke tests
-	cd projects/shared-utils && $(UV) run pytest -q
+test-utils: ## Run utils smoke tests
+	cd projects/utils && $(UV) run pytest -q
 
 test-wiki-agent: ## Run wiki-agent smoke tests
 	cd projects/wiki-agent && $(UV) run pytest -q
 
-test: test-engine test-shared test-wiki-agent ## Run tests for every workspace member
+test: test-engine test-utils test-wiki-agent ## Run tests for every workspace member
 
 # ── Quality ─────────────────────────────────────────────────
 
@@ -37,7 +37,7 @@ lint: ## Lint the entire workspace
 
 typecheck: ## Mypy strict for every project
 	cd projects/llm-patch && $(UV) run mypy src
-	cd projects/shared-utils && $(UV) run mypy src
+	cd projects/utils && $(UV) run mypy src
 	cd projects/wiki-agent && $(UV) run mypy src
 
 check-layering: ## Architectural fitness check (ADR-0002)
@@ -53,7 +53,7 @@ check: lint typecheck check-layering test check-coverage ## Lint + typecheck + l
 
 build: ## Build distributions for every project
 	cd projects/llm-patch && $(UV) build
-	cd projects/shared-utils && $(UV) build
+	cd projects/utils && $(UV) build
 	cd projects/wiki-agent && $(UV) build
 
 # ── ADR helper ──────────────────────────────────────────────