@event4u/agent-config 5.0.0 → 5.1.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/INDEX.md

@@ -35,6 +35,7 @@ _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 | — |
 
 ## Unnumbered (legacy)
 

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.1.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

package/scripts/check_no_local_settings_committed.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Fail if any ``.agent-settings.local.yml`` is tracked by git.
+
+`.agent-settings.local.yml` is the per-developer, per-machine override layer
+(see ``scripts/_lib/agent_settings.py`` ``LOCAL_PROJECT_FILE``). It is
+gitignored on purpose — committing one would leak one developer's local
+machine paths (e.g. linked-project siblings) into everyone's checkout.
+
+Exit 0 when none are tracked, 1 (with the offending paths) otherwise.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+LOCAL_FILE = ".agent-settings.local.yml"
+
+
+def tracked_local_settings() -> list[str]:
+    try:
+        out = subprocess.run(
+            ["git", "ls-files"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        # Not a git repo / git missing — nothing to enforce here.
+        return []
+    return [
+        line
+        for line in out.splitlines()
+        if line.split("/")[-1] == LOCAL_FILE
+    ]
+
+
+def main() -> int:
+    offenders = tracked_local_settings()
+    if not offenders:
+        print(f"✅  No tracked {LOCAL_FILE} files.")
+        return 0
+    print(f"❌  {LOCAL_FILE} must never be committed (per-machine local layer):")
+    for path in offenders:
+        print(f"  🔴 {path}")
+    print(f"\nRun: git rm --cached <path>  — and confirm {LOCAL_FILE} is gitignored.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())