@event4u/agent-config 5.0.0 → 5.2.0

package/docs/decisions/ADR-032-linked-projects-scope.md

@@ -0,0 +1,118 @@
+---
+adr: 032
+status: accepted
+date: 2026-05-29
+decision: linked-projects-scope-go-option-a
+supersedes: —
+superseded_by: —
+phase: v3.x · multi-project-scope evaluation
+type: structural
+review_date: 2027-05-29
+---
+
+# ADR-032 — Linked-projects scope: GO on opt-in auto-detection (Option A, passive awareness)
+
+## Status
+
+**Accepted** · 2026-05-29. Approves an opt-in auto-detection feature for
+IDE-attached sibling repositories, scoped to **passive awareness** (Option A).
+A same-day earlier draft recorded NO-GO; that verdict was reversed after the
+proactivity-gap argument (below). Time-boxed: review on **2027-05-29** or
+earlier if a kill-switch trigger fires.
+
+Not to be confused with [`ADR-029`](ADR-029-multi-workspace-deferred.md): that
+defers a restructure of the **package's own root layout**. This ADR is about
+the **agent's working scope over a sibling project repository**.
+
+## Context
+
+Developers routinely check out sibling repos that change together (e.g.
+`galawork-api` + `galawork-web`) and attach them in the IDE. Detection is
+deterministic from on-disk config (`.idea/modules.xml` + `vcs.xml`,
+`*.code-workspace`).
+
+A Phase-0 spike found Claude Code can already read/write a sibling outside its
+working directory **unconditionally** — no rule needed. An initial reading
+concluded the feature was therefore only an "awareness signal" a doc could
+deliver, and drafted NO-GO.
+
+## The reversal — proactivity gap
+
+That NO-GO mis-framed the value. The point is **not** capability (the agent can
+write everywhere); it is **proactivity**: the agent does **not** consider a
+sibling unless explicitly told, so cross-repo dependencies — an API change that
+breaks the frontend, a shared type that drifts — are missed by default. A
+manual doc/snippet presupposes the very awareness the target user lacks: the
+developer who needs this most is exactly the one who won't think to write the
+note. **Auto-detection is zero-knowledge** — it reads the relationship the
+developer already encoded by attaching the repo in their IDE.
+
+AI Council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 3 rounds + Karpathy
+peer-review, 2026-05-29) flipped to **GO** on this reasoning.
+
+## Decision — GO, scoped to Option A (passive awareness)
+
+Build an **opt-in** auto-detection feature:
+
+1. **Detect** IDE-attached siblings from on-disk config (config-driven only;
+   never arbitrary adjacent directories).
+2. **Opt-in once** per sibling; persist the choice **local-only** in
+   `.agent-settings.local.yml` (in agents/settings/) (gitignored, per-machine — sibling paths differ
+   per developer and must never be committed).
+3. **Behavioral directive** for in-scope siblings: proactively check cross-repo
+   impact on relevant changes (API contract, shared types) and **warn**.
+   **Do NOT bulk-include** the sibling's files (interpretation C — token
+   blowup — stays **out of scope**). Out-of-root writes still pass the host
+   agent's own permission gate.
+
+### A/B/C scoping
+
+- **A — passive awareness (CHOSEN):** know + warn, no bulk inclusion. Cheap, low risk.
+- **B — proactive dependency scanning:** auto-scan on every change. Deferred (needs heuristics).
+- **C — implicit inclusion of all sibling files:** **rejected** — token blowup, context pollution.
+
+### Fork resolutions
+
+- **Fork A** — `.agent-settings.local.yml` (in agents/settings/), deepest cascade layer reusing `_deep_merge` (not a bespoke override).
+- **Fork B** — key `linked_projects` (avoids ADR-007 "scope"/"workspace", ADR-029 "multi-workspace").
+- **Fork C** — cross-cwd writes documented, never auto-configured; host permission gate applies.
+
+## Consequences
+
+- New: detector (`scripts/_lib/linked_projects.py`), the
+  `.agent-settings.local.yml` (in agents/settings/) cascade layer, a committed-local lint, and the
+  `linked-projects-onboarding-gate` rule (tier-2b, **experimental**, **removable**).
+- The intra-repo module system (`enumerate_modules()`) is untouched.
+- Size never excludes a sibling — a real frontend (galawork-web ≈ 38k files)
+  must surface; it is flagged `large` (awareness only). The council's literal
+  "skip >20k files" guardrail was corrected: it conflated Option C's
+  file-inclusion cost with Option A, under which repo size is cost-irrelevant.
+- Per install decision **D2**, the installer does not touch the consumer
+  `.gitignore`; consumers gitignore `.agent-settings.local.yml` (in agents/settings/) themselves
+  (documented in the guide).
+
+## Kill-switch
+
+Experimental + removable by construction. If opt-in is consistently declined or
+siblings are never cited in practice, remove the rule. Signal stays local — no
+telemetry.
+
+## Open follow-ups
+
+- **Consumer detector reachability:** the detector lives in `scripts/_lib/`;
+  exposing it as an `agent-config` CLI subcommand for consumer installs is a
+  follow-up. Import-reachable in this repo / co-located maintainer setups today.
+- **Multi-agent verification:** only Claude Code was empirically validated.
+  Cursor / Augment / Copilot are unverified — the guide's manual snippet covers
+  them until an interactive per-IDE test is run.
+
+## Alternatives considered
+
+- **NO-GO + docs only** — rejected: a manual note fails the target user who lacks the awareness to write it.
+- **Build Option C** — rejected: token blowup.
+
+## References
+
+- [`docs/guides/cross-repo-linked-projects.md`](../guides/cross-repo-linked-projects.md)
+- [`ADR-007`](ADR-007-agent-discovery-scopes.md) — owns "scope"/"workspace".
+- [`ADR-029`](ADR-029-multi-workspace-deferred.md) — unrelated package-root multi-workspace defer.

package/docs/decisions/ADR-033-distribution-identity-npm-primary.md

@@ -0,0 +1,81 @@
+---
+adr: 033
+status: accepted
+date: 2026-05-29
+decision: distribution-identity-npm-primary
+supersedes: —
+superseded_by: —
+phase: distribution-identity
+type: structural
+review_date: 2026-08-29
+---
+
+# ADR-033 — Distribution identity: npm-primary, Packagist deprecated-in-place
+
+## Status
+
+**Accepted** · 2026-05-29. AI Council (claude-sonnet-4-5 + gpt-4o, analysis lens, 2026-05-29) converged on **npm-primary with Packagist deprecated-in-place**. No maintainer veto surfaced; the de-facto evidence and the operational-honesty argument both point to a single answer. Review date 2026-08-29.
+
+## Context
+
+External feedback rounds 10 / 12 / 13 returned to two recurring symptoms — *"Packagist still shows 1.0.4"* and *"two major bumps in six days with no breaking-change signal"*. A council deliberation (lens: analysis) re-framed both as **one distribution-identity question** the repo has answered in practice but never recorded:
+
+- **`package.json` at `5.1.0`** — the package is past the unified-setup 4.0.0 major and a subsequent 5.0.0 line; semver discipline (per `CONTRIBUTING.md § Versioning policy`) treats installer-layout changes as major, so the cadence is policy-correct.
+- **`scripts/release.py` invokes `npm publish` exclusively** — the only publish surface that ships from a release run.
+- **No `composer.json` exists in this repo** — the file was removed during the npm pivot (pre-3.x era). The Packagist `event4u/agent-config` 1.0.4 listing is a zombie pointing at a repository state that no longer exists.
+- **No automation syncs the Composer surface** — none has existed since the pivot. Pretending the channel is supported is a maintenance lie.
+- **ADR-027** already locks the changelog-machine path (`scripts/release.py` derives `CHANGELOG.md § Breaking` from Conventional Commits). The "no breaking-change signal" symptom is stale against that surface — what is missing is a one-click pointer for consumers.
+
+Council framing — two perspectives surfaced:
+
+**Lens A — Strategic / consumer-positioning.** A consumer who lands on Packagist sees 1.0.4 and installs an artefact the repo cannot support. The honest signal is deprecation; dual-track without resources is worse than a single declared channel.
+
+**Lens B — Technical / operational-honesty.** A channel is "supported" only if a release pipeline publishes to it. Composer/Packagist has had no such pipeline since the npm pivot. The simpler invariant — *one channel, one truth* — wins on every measurable axis: maintenance load, consumer trust, audit clarity.
+
+Both lenses converged.
+
+## Decision
+
+1. **The package is npm-primary.** The canonical install path is `npm install @event4u/agent-config` (and the consumer-facing `npx @event4u/agent-config install` wizard). All release tooling (`scripts/release.py`, `package.json`, `CONTRIBUTING.md § Versioning policy`) already aligns with this surface — this ADR records the policy, no code changes follow from the declaration itself.
+
+2. **Composer / Packagist is deprecated-in-place.** No `composer.json` ships from this repo; no PHP autoload surface is supported; the Packagist `event4u/agent-config` 1.0.4 listing is treated as legacy and gets a deprecation pointer through the only mechanism available to a deleted-composer-json repo: a registry-side claim/archive action by the maintainer. The corresponding human-owner item is surfaced in `docs/distribution/registries.md` (see Phase 2 of the [`road-to-distribution-identity.md`](../../agents/roadmaps/road-to-distribution-identity.md) roadmap).
+
+3. **Breaking-change communication uses `CHANGELOG.md § Breaking`.** ADR-027 locked the auto-generated changelog from Conventional Commits. This ADR adds one consumer-facing affordance — a README / distribution-doc pointer linking that section — so a consumer who sees a major-version bump has a one-click path to *what broke, what to do*. No new `BREAKING_CHANGES.md` file unless the maintainer prefers one.
+
+4. **Commit-subject hygiene is enforced in CI.** Because the changelog generator reads commit subjects verbatim, sloppy subjects (`leftover`, `wip`, `temp`, `fixup`, or sub-10-character one-word entries) leak directly into the public changelog. A CI lint (`task lint-commit-subjects` or sibling) rejects those subjects on PR. This is wired in Phase 3 of the same roadmap and is the one hygiene item that ties directly to distribution identity.
+
+## Consequences
+
+**Positive:**
+
+- The distribution story is **single-channel, single-truth**. Anyone scanning the package — consumer, contributor, auditor, package-registry crawler — gets one consistent answer.
+- The zombie Packagist listing no longer misdirects PHP-shop consumers (once the maintainer files the registry-side archive action).
+- Breaking-change discoverability is two clicks from the README: "release notes" → `CHANGELOG.md § Breaking`. No bespoke `BREAKING_CHANGES.md` to maintain.
+- CI catches sloppy commit subjects before they become public changelog lines — the changelog is as clean as the gate that feeds it.
+
+**Negative / accepted costs:**
+
+- A PHP-shop consumer who depends on the 1.0.4 Packagist release is left behind. Mitigation: clear deprecation notice + npm install pointer in the registry-side archive.
+- The maintainer must perform a one-time login at `packagist.org/packages/event4u/agent-config` to claim or archive the listing — autonomous tooling cannot do that.
+- Future re-entry into the Composer ecosystem would require a new ADR superseding this one. That cost is acceptable: a re-entry would be a strategic redirect, not a quiet re-add.
+
+**Operationally neutral:**
+
+- `scripts/release.py` already does the right thing; no script change follows from this ADR.
+- `CONTRIBUTING.md § Versioning policy` already does the right thing; no policy change follows from this ADR. The major bumps that prompted the feedback (4.0.0 unified-setup, 5.0.0 follow-up) were policy-correct under the existing rule.
+
+## Alternatives considered
+
+- **Dual-track with auto-sync.** Rejected. The repo carries no Composer surface to sync; restoring one would mean re-introducing a `composer.json` + a sync pipeline + a PHP-side autoload story, all to support a consumer base nobody has named. The carrying cost outweighs the demand signal.
+- **Dual-track without auto-sync (status quo).** Rejected. This is the failure mode that produced the external feedback in the first place — a stale 1.0.4 listing pretends a channel is supported when it is not. Operational-honesty argument carries.
+- **Re-introduce composer.json as a stub linking to npm.** Rejected. A stub on Packagist is still a Packagist artifact; consumers may still try to `composer require` it and hit a non-functional package. Registry-side archive is the cleaner signal.
+- **A bespoke `BREAKING_CHANGES.md` file.** Rejected by default; ADR-027 already locks the machine-generated changelog as the breaking-change surface. Maintainer may revisit if the changelog format proves insufficient for end-of-life or migration-guide-shape communication.
+
+## References
+
+- [`agents/roadmaps/road-to-distribution-identity.md`](../../agents/roadmaps/road-to-distribution-identity.md) — the work-item plan this ADR underwrites.
+- [`ADR-027-changelog-machine-vs-manual.md`](ADR-027-changelog-machine-vs-manual.md) — the prior decision locking the auto-generated changelog.
+- [`CONTRIBUTING.md § Versioning policy`](../../CONTRIBUTING.md) — the semver discipline this ADR confirms.
+- [`docs/distribution/registries.md`](../distribution/registries.md) — external-registry submission posture; this ADR adds a distribution-channel-identity section to that file.
+- `scripts/release.py` — the `npm publish` release pipeline.
+- External feedback rounds 10 / 12 / 13 (private session transcripts; convergence summary inlined above to keep this ADR self-contained).

package/docs/decisions/INDEX.md

@@ -35,6 +35,8 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
 | [ADR-029](ADR-029-multi-workspace-deferred.md) | Multi Workspace Deferred | accepted | 2026-05-25 | — |
 | [ADR-030](ADR-030-claude-code-command-projection.md) | Claude Code Command Projection | accepted | 2026-05-28 | — |
 | [ADR-031](ADR-031-validation-severity-tiers-and-projection-roundtrip.md) | Validation Severity Tiers And Projection Roundtrip | accepted | 2026-05-29 | — |
+| [ADR-032](ADR-032-linked-projects-scope.md) | Linked Projects Scope Go Option A | accepted | 2026-05-29 | — |
+| [ADR-033](ADR-033-distribution-identity-npm-primary.md) | Distribution Identity Npm Primary | accepted | 2026-05-29 | — |
 
 ## Unnumbered (legacy)
 

package/docs/distribution/registries.md

@@ -4,6 +4,35 @@ Track third-party registries / directories we want this package to surface in. S
 
 > **Authority** — Phase 2 of [`road-to-product-adoption.md`](../../agents/roadmaps/road-to-product-adoption.md). The autonomous roadmap pass cannot open PRs in third-party repos; this file is the handoff.
 
+## Distribution channels — npm-primary
+
+Per [`ADR-033`](../decisions/ADR-033-distribution-identity-npm-primary.md), the package is **npm-primary, Packagist deprecated-in-place**. Both lenses of the council deliberation (strategic / operational) converged on a single-channel posture: this is the canonical record of which registries we publish to vs. which we treat as legacy.
+
+| Channel | Status | Canonical install | Notes |
+|---|---|---|---|
+| npm — `@event4u/agent-config` | **Primary** | `npm install @event4u/agent-config` or `npx @event4u/agent-config install` | The release pipeline (`scripts/release.py`) runs `npm publish` exclusively; `package.json` is the source of truth for the published version. |
+| Packagist — `event4u/agent-config` | **Deprecated-in-place** | (do not install — see ADR-033) | The 1.0.4 listing is a legacy artefact from the pre-3.x repo namespace. No `composer.json` ships from this repo. Maintainer-side claim/archive action required (see below). |
+
+### Packagist deprecation — human-owner item
+
+The Packagist `event4u/agent-config` listing pins at 1.0.4 from a repository state that no longer exists. The autonomous pipeline cannot retire that listing — it requires a maintainer login at `packagist.org/packages/event4u/agent-config`. Two paths exist; either is acceptable per ADR-033.
+
+- [ ] **Claim + abandoned-flag the package.** Log in at packagist.org, claim the `event4u/agent-config` namespace, set the package to `abandoned` with the replacement pointer `event4u/agent-config` on npm (or the npm package URL as a body note where Packagist's abandoned-replacement field expects a Composer-namespace value, fall back to a `description` field redirect).
+- [ ] **OR: leave the listing as legacy + add a description-field redirect.** If claim is blocked or out of scope, edit the listing description to add a one-line `> Deprecated — install via npm: \`@event4u/agent-config\`` so any consumer who lands there sees the correct path.
+
+This item is **owner-owned**, not autonomous; the roadmap explicitly captures it as such (`road-to-distribution-identity.md` Phase 2 Step 1). Mark the chosen path with `[x]` once executed.
+
+### Breaking-change communication
+
+Major-version bumps are policy-correct per [`CONTRIBUTING.md § Versioning policy`](../../CONTRIBUTING.md) (semver — installer-layout changes are major). The auto-generated `CHANGELOG.md § Breaking` section is the **single source of truth** for breaking changes; [`ADR-027`](../decisions/ADR-027-changelog-machine-vs-manual.md) locks the machine-generated path.
+
+Consumers who see a major-version bump should follow:
+
+1. [`CHANGELOG.md § Breaking`](../../CHANGELOG.md#breaking) — the diff between the prior and the new major. Every breaking change carries a Conventional-Commits subject prefixed `feat!:` or with a `BREAKING CHANGE:` footer.
+2. The release-line link in the GitHub release entry for the new version (links the auto-generated changelog section).
+
+No bespoke `BREAKING_CHANGES.md` is maintained — the changelog is the authoritative surface.
+
 ## Submission status
 
 | # | Registry | URL | Submission shape | Status | PR link |

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 77 rules. No configuration needed.
+This is enforced automatically by 78 rules. No configuration needed.
 
 ---
 

package/docs/guides/cross-repo-linked-projects.md

@@ -0,0 +1,86 @@
+# Working across linked sibling projects
+
+When two repositories change together — an API and its frontend, a service and
+a shared library — a change in one can silently break the other. The agent can
+already read and write a sibling repo, but it won't **proactively consider** one
+unless it knows the sibling is relevant. This feature closes that gap: it
+detects the sibling your IDE already attached and, after a one-time opt-in,
+makes the agent flag cross-repo impact by default.
+
+> **Scope — passive awareness (Option A).** The agent gains *awareness*: it
+> warns about cross-repo impact on relevant changes and can read/edit the
+> sibling on demand. It does **not** bulk-load the sibling's files into context
+> (that would blow up token cost). See
+> [ADR-032](../decisions/ADR-032-linked-projects-scope.md). Unrelated to
+> [ADR-029](../decisions/ADR-029-multi-workspace-deferred.md) (package root
+> layout).
+
+## Auto-detection (Claude Code — verified)
+
+If you attach a sibling repo in your IDE, the agent detects it from on-disk
+config and prompts **once** to opt it in:
+
+- **PhpStorm / IntelliJ** — a sibling attached via `.idea/modules.xml` /
+  `.idea/vcs.xml` (e.g. `../galawork-web`).
+- **VS Code** — folders in a `*.code-workspace`.
+
+On the first turn (and on a new attachment) the agent asks per detected sibling:
+include / decline / always / never-ask. Your choice is stored **local-only** in
+`.agent-settings.local.yml` (in agents/settings/) (gitignored, per-machine — see below). A declined
+sibling is never prompted again.
+
+Once a sibling is in scope, the agent proactively checks it for impact when a
+change here may affect it (API contract, shared types) and warns you — without
+loading its files wholesale. Large siblings (a real frontend easily exceeds
+20 000 files) are flagged `large` and surfaced as awareness only, never skipped.
+
+## Manual setup (other agents / any editor)
+
+Auto-detection is verified for Claude Code only. For Cursor, Augment, Copilot,
+or any editor without IDE attachment, add the sibling by hand to
+`.agent-settings.local.yml` (in agents/settings/):
+
+~~~yaml
+linked_projects:
+  - path: /abs/path/to/web   # or a path relative to the project
+    include: true
+~~~
+
+Or, if your agent reads a rules file, drop a short note there:
+
+~~~markdown
+## Linked sibling project: ../web
+
+`../web` changes alongside this repo. When an API/contract or shared-type
+change here may affect it, check `../web` for impact and warn. Don't load its
+files wholesale; access specific files on demand.
+~~~
+
+## Keep it local, never committed
+
+`.agent-settings.local.yml` (in agents/settings/) is **gitignored on purpose** — sibling paths are
+per-developer and per-machine. The installer does **not** touch your
+`.gitignore` (decision D2 — you own your ignore file), so if your project does
+not already ignore it, add:
+
+~~~gitignore
+.agent-settings.local.yml
+~~~
+
+## Validate it works
+
+Ask the agent:
+
+> Read `package.json` (or `composer.json`) from the linked sibling and tell me the project name.
+
+If it reports the name, cross-repo access works. An out-of-root edit will prompt
+for confirmation, then succeed — that is expected (the agent's permission gate
+still applies).
+
+## Tell us what works
+
+Auto-detection is verified for Claude Code only. If you use Cursor, Augment, or
+Copilot, please report whether the rule note alone worked, you needed to add the
+folder to the IDE workspace, or neither — that evidence is the trigger to extend
+verified auto-detection to your agent. See
+[ADR-032](../decisions/ADR-032-linked-projects-scope.md).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.0.0",
+    "version": "5.2.0",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_lib/agent_settings.py

@@ -61,6 +61,21 @@ from . import user_global_paths
 logger = logging.getLogger(__name__)
 
 DEFAULT_PROJECT_FILE = ".agent-settings.yml"
+#: Per-machine override file. Gitignored. A SINGLE project-level file living
+#: under ``agents/settings/`` (with the rest of the project's settings layer,
+#: not at the repo root). It is appended as the deepest cascade layer so a
+#: developer's local values override every committed ``.agent-settings.yml``
+#: without ever being committed. Missing file is harmless (read as {}).
+LOCAL_PROJECT_FILE = ".agent-settings.local.yml"
+#: Project-relative directory the local override lives in.
+LOCAL_PROJECT_SUBDIR = ("agents", "settings")
+
+
+def _local_settings_path(project_root: Path) -> Path:
+    """Single local override: ``<root>/agents/settings/.agent-settings.local.yml``."""
+    return project_root.joinpath(*LOCAL_PROJECT_SUBDIR, LOCAL_PROJECT_FILE)
+
+
 DEFAULT_TEAM_FILE = ".agent-project-settings.yml"
 USER_GLOBAL_FILENAME = "agent-settings.yml"
 
@@ -415,12 +430,12 @@ def _resolve_cascade_paths(
     """
     if cwd is None:
         legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
-        return [legacy]
+        return [legacy, _local_settings_path(legacy.parent)]
 
     root = find_project_root(cwd)
     if root is None:
         legacy = Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE)
-        return [legacy]
+        return [legacy, _local_settings_path(legacy.parent)]
 
     cwd_resolved = cwd.resolve()
     # Build the chain root → … → cwd (shallowest first, deepest last).
@@ -435,7 +450,9 @@ def _resolve_cascade_paths(
             break
         cursor = parent
     chain.reverse()
-    return [d / DEFAULT_PROJECT_FILE for d in chain]
+    # Committed cascade root → cwd, then the single project-level local override
+    # under agents/settings/ as the deepest (winning) layer.
+    return [d / DEFAULT_PROJECT_FILE for d in chain] + [_local_settings_path(root)]
 
 
 def load_agent_settings(

package/scripts/_lib/linked_projects.py

@@ -0,0 +1,238 @@
+"""Detect IDE-attached sibling projects (linked-projects scope, Option A).
+
+Pure, dependency-free detector. Reads on-disk IDE config the developer already
+created by attaching a sibling repo, and returns the sibling project roots that
+sit *outside* the current project. Config-driven only — never guesses from
+arbitrary adjacent directories.
+
+Sources:
+  * PhpStorm / IntelliJ  — ``.idea/modules.xml`` (``<module fileurl>``) and
+    ``.idea/vcs.xml`` (``<mapping directory>``).
+  * VS Code              — ``*.code-workspace`` (``folders[].path``).
+
+Guardrails (per the linked-projects council, Option A):
+  * a candidate must resolve OUTSIDE the project root, exist, and contain a
+    ``.git/`` directory;
+  * a candidate whose file count exceeds ``max_files`` (default 20000) is
+    **flagged** ``large: true`` — NOT excluded. Under Option A the agent only
+    carries a passive awareness note and never bulk-includes sibling files, so
+    repo size is cost-irrelevant to detection; a real frontend repo routinely
+    exceeds 20000 files (excluding node_modules) and must still be surfaced.
+    The flag lets the awareness note say "large repo — check targeted impact,
+    do not scan the whole tree";
+  * the bloat directories ``node_modules``/``.git``/``dist``/``build``/
+    ``.venv``/``target`` are never descended into while counting.
+
+The detector returns awareness candidates; it does NOT include any sibling
+files in context and does NOT persist anything. Opt-in + persistence is the
+caller's job.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+#: File-count ceiling above which a sibling is skipped (token-blowup guard).
+DEFAULT_MAX_FILES = 20000
+
+#: Directories never descended into while counting a sibling's size.
+SKIP_DIRS: frozenset[str] = frozenset(
+    {"node_modules", ".git", "dist", "build", ".venv", "target", ".idea"}
+)
+
+
+def detect_linked_projects(
+    project_root: Path | str,
+    *,
+    max_files: int = DEFAULT_MAX_FILES,
+) -> list[dict[str, Any]]:
+    """Return IDE-attached sibling projects outside ``project_root``.
+
+    Each entry is ``{"path": <absolute str>, "detected_via": <source>,
+    "large": <bool>}`` where source is one of ``phpstorm_modules`` /
+    ``phpstorm_vcs`` / ``vscode_workspace`` and ``large`` is true when the
+    sibling's file count (excluding bloat dirs) exceeds ``max_files``. Results
+    are de-duplicated by resolved path (first source wins) and sorted by path.
+    Size never excludes — see the module docstring.
+    """
+    root = Path(project_root).resolve()
+    if not root.is_dir():
+        logger.info("linked_projects: project_root %s is not a directory", root)
+        return []
+
+    candidates: list[tuple[Path, str]] = []
+    candidates.extend((p, "phpstorm_modules") for p in _phpstorm_modules(root))
+    candidates.extend((p, "phpstorm_vcs") for p in _phpstorm_vcs(root))
+    candidates.extend((p, "vscode_workspace") for p in _vscode_workspace(root))
+
+    seen: set[Path] = set()
+    out: list[dict[str, Any]] = []
+    for path, source in candidates:
+        try:
+            resolved = path.resolve()
+        except OSError:
+            logger.info("linked_projects: cannot resolve %s", path)
+            continue
+        if resolved in seen:
+            continue
+        if not _is_valid_sibling(resolved, root):
+            continue
+        large = _exceeds_size(resolved, max_files)
+        if large:
+            logger.info(
+                "linked_projects: %s exceeds %d files — flagged large (awareness only)",
+                resolved,
+                max_files,
+            )
+        seen.add(resolved)
+        out.append(
+            {"path": str(resolved), "detected_via": source, "large": large}
+        )
+
+    out.sort(key=lambda e: e["path"])
+    return out
+
+
+def _is_valid_sibling(candidate: Path, root: Path) -> bool:
+    """A sibling must be outside the project root, exist, and be a git repo."""
+    try:
+        if candidate == root or root in candidate.parents:
+            return False  # inside the project — that's the module system's job
+        if candidate in root.parents:
+            return False  # an ancestor of the project, not a sibling
+        if not candidate.is_dir():
+            logger.info("linked_projects: candidate missing/not-a-dir %s", candidate)
+            return False
+        if not (candidate / ".git").exists():
+            logger.info("linked_projects: candidate not a git repo %s", candidate)
+            return False
+    except OSError:
+        logger.info("linked_projects: unreadable candidate %s", candidate)
+        return False
+    return True
+
+
+def _exceeds_size(candidate: Path, max_files: int) -> bool:
+    """True if the tree (minus SKIP_DIRS) holds more than ``max_files`` files."""
+    import os
+
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(candidate):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        count += len(filenames)
+        if count > max_files:
+            return True
+    return False
+
+
+def _phpstorm_modules(root: Path) -> list[Path]:
+    """Sibling roots from ``.idea/modules.xml`` ``<module fileurl>`` entries."""
+    path = root / ".idea" / "modules.xml"
+    elems = _iter_xml_attrs(path, "module", ("fileurl", "filepath"))
+    out: list[Path] = []
+    for attrs in elems:
+        raw = attrs.get("fileurl") or attrs.get("filepath")
+        if not raw:
+            continue
+        resolved = _resolve_idea_url(raw, root)
+        if resolved is None:
+            continue
+        # raw points at <sibling>/.idea/<name>.iml → sibling is .idea's parent.
+        if resolved.parent.name == ".idea":
+            out.append(resolved.parent.parent)
+        else:
+            out.append(resolved)
+    return out
+
+
+def _phpstorm_vcs(root: Path) -> list[Path]:
+    """Sibling roots from ``.idea/vcs.xml`` ``<mapping directory>`` entries."""
+    path = root / ".idea" / "vcs.xml"
+    out: list[Path] = []
+    for attrs in _iter_xml_attrs(path, "mapping", ("directory",)):
+        raw = attrs.get("directory")
+        if not raw:
+            continue
+        resolved = _resolve_idea_url(raw, root)
+        if resolved is not None:
+            out.append(resolved)
+    return out
+
+
+def _vscode_workspace(root: Path) -> list[Path]:
+    """Sibling roots from ``*.code-workspace`` ``folders[].path`` entries."""
+    out: list[Path] = []
+    try:
+        workspaces = sorted(root.glob("*.code-workspace"))
+    except OSError:
+        return out
+    for ws in workspaces:
+        data = _read_jsonc(ws)
+        if not isinstance(data, dict):
+            continue
+        folders = data.get("folders")
+        if not isinstance(folders, list):
+            continue
+        for folder in folders:
+            if not isinstance(folder, dict):
+                continue
+            rel = folder.get("path")
+            if not isinstance(rel, str) or not rel.strip():
+                continue
+            out.append((root / rel).resolve())
+    return out
+
+
+def _resolve_idea_url(raw: str, root: Path) -> Path | None:
+    """Resolve a PhpStorm path token to an absolute Path, or None."""
+    value = raw.strip()
+    if value.startswith("file://"):
+        value = value[len("file://") :]
+    value = value.replace("$PROJECT_DIR$", str(root))
+    if not value:
+        return None
+    try:
+        return (Path(value) if Path(value).is_absolute() else root / value).resolve()
+    except OSError:
+        return None
+
+
+def _iter_xml_attrs(
+    path: Path, tag: str, _attrs: tuple[str, ...]
+) -> list[dict[str, str]]:
+    """Return the attribute dicts of every ``<tag>`` in ``path`` (tolerant)."""
+    if not path.is_file():
+        return []
+    try:
+        tree = ET.parse(path)
+    except (ET.ParseError, OSError) as exc:
+        logger.info("linked_projects: malformed/unreadable %s (%s)", path, exc)
+        return []
+    return [dict(el.attrib) for el in tree.iter(tag)]
+
+
+def _read_jsonc(path: Path) -> Any:
+    """Parse JSON that may carry ``//`` comments and trailing commas (VS Code)."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    # tolerant fallback: strip line comments + trailing commas, retry once.
+    stripped = re.sub(r"^\s*//.*$", "", text, flags=re.MULTILINE)
+    stripped = re.sub(r",(\s*[}\]])", r"\1", stripped)
+    try:
+        return json.loads(stripped)
+    except json.JSONDecodeError as exc:
+        logger.info("linked_projects: malformed workspace JSON %s (%s)", path, exc)
+        return None