doubled-graph 2.0.1__tar.gz → 2.0.2__tar.gz

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: doubled-graph
-Version: 2.0.1
+Version: 2.0.2
 Summary: MCP facade over CodeGraphContext + GRACE 4 (.grace artifacts): impact, context, drift-detect, migration for LLM-driven codebases.
 Project-URL: Homepage, https://github.com/rour/doubled-graph-mcp
 Project-URL: Repository, https://github.com/rour/doubled-graph-mcp
@@ -154,7 +154,7 @@ head -1 "$(which doubled-graph)"  # вывести shebang — это и ест
 ### 4. Проверить, что всё встало
 
 ```bash
-doubled-graph --version          # 2.0.1
+doubled-graph --version          # 2.0.2
 doubled-graph status --repo .    # artifacts.project_kind = grace4, grace_engine.upgrade_required = false
 doubled-graph lint --repo .      # summary.errors = 0
 doubled-graph migrate check --repo .   # map_pending / placeholders — что осталось заполнить

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/README.md

@@ -119,7 +119,7 @@ head -1 "$(which doubled-graph)"  # вывести shebang — это и ест
 ### 4. Проверить, что всё встало
 
 ```bash
-doubled-graph --version          # 2.0.1
+doubled-graph --version          # 2.0.2
 doubled-graph status --repo .    # artifacts.project_kind = grace4, grace_engine.upgrade_required = false
 doubled-graph lint --repo .      # summary.errors = 0
 doubled-graph migrate check --repo .   # map_pending / placeholders — что осталось заполнить

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/docs/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to doubled-graph. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [2.0.2] — 2026-10-23
+
+BOM support on top of 2.0.1 (already published). No artifact-format change:
+`pipx upgrade doubled-graph` is enough; no re-migration required.
+
+**Why:** a real C# repository had 216 `.cs` files starting with a UTF-8 BOM.
+The JS engine treats U+FEFF as whitespace, but Python's `\s` does not, so
+doubled-graph saw those files as ungoverned while `grace lint` was green:
+modules lost `localFiles`, `file show` found nothing, `detect-changes` reported
+`code_without_module`.
+
+### Fixed — UTF-8 BOM in sources and inputs
+- UTF-8 BOM everywhere, not only in source files. Python's `\s` does not match
+  U+FEFF while the JS engine's `\s` does, so `^\s*// MODULE:` never matched and
+  every BOM file (216 in one real repository) looked ungoverned to
+  doubled-graph — modules lost their files, `module show` returned no
+  `localFiles`, `detect-changes` reported `code_without_module` — while
+  `grace lint` was green. All readers now use `utf-8-sig`: source scanning
+  (`graphs/grace4.py`, markup repair, `context`, `detect_changes`), `.grace`
+  documents, `.doubled-graph/config.json`, `.mcp.json`,
+  `.continue/config.json`, `.claude/settings.json`, `AGENTS.md` and legacy
+  `docs/*.xml`. The markup repair writes a source file back **with** its BOM;
+  writers of `.grace`/JSON/hook scripts never add one (a BOM-broken shebang
+  would not execute).
+- `doubled-graph lint` now **works on BOM sources without modifying them**. The
+  engine's Python/TypeScript/Dart analyzers reject U+FEFF (`ast.parse`), and its
+  index check misses `.grace` documents behind a BOM — so lint runs against a
+  temporary snapshot in which BOM is normalised (`.grace/*.xml` and
+  adapter-backed sources only), with the engine `cwd` set to the snapshot and
+  `--path .` (4.2.1 reports `projection.*.unindexed-document` for an absolute
+  `--path` outside cwd). JSON paths are rebased to the real repository before
+  returning. Client files are never written: verified — `errors: 1` before,
+  `errors: 0` after, BOM still present in `src/a.py` and `.grace/graph/index.xml`.
+  Files in languages without an adapter (C#, Go, Rust, Java, Swift, …) are
+  copied verbatim, BOM included: the engine runs no analyzer for them, so their
+  BOM never reaches `ast.parse` and does not affect lint. `migrate check` reports `bom_files` / `bom_adapter_files` and
+  warns `migration.bom-in-code`; `01-content-gaps.md` explains the mirror.
 ## [2.0.1] — 2026-10-23
 
 Migration-fidelity fixes on top of 2.0.0 (already published). No artifact-format

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/docs/TOOLS.md

@@ -55,7 +55,7 @@
   "warnings": [
     {"code": "HASKELL_PARSER_UNSTABLE", "file": "src/foo.hs", "detail": "…"}
   ],
-  "meta": {"phase": "post_migration", "tool_version": "2.0.1", "timestamp_iso": "2026-10-23T10:22:04Z", "trace_id": "…"}
+  "meta": {"phase": "post_migration", "tool_version": "2.0.2", "timestamp_iso": "2026-10-23T10:22:04Z", "trace_id": "…"}
 }
 ```
 
@@ -139,7 +139,7 @@ Declared-сторона (`graphs/grace4.py`) при `analyze` не вызыва
       "phase=post_migration — contract drift check required"
     ]
   },
-  "meta": {"phase": "post_migration", "tool_version": "2.0.1", "timestamp_iso": "...", "trace_id": "..."}
+  "meta": {"phase": "post_migration", "tool_version": "2.0.2", "timestamp_iso": "...", "trace_id": "..."}
 }
 ```
 
@@ -232,7 +232,7 @@ Declared-сторона (`graphs/grace4.py`) при `analyze` не вызыва
     "plan_status": "approved",
     "tasks": ["T-001", "T-002"]
   },
-  "meta": {"phase": "...", "tool_version": "2.0.1", "...": "..."}
+  "meta": {"phase": "...", "tool_version": "2.0.2", "...": "..."}
 }
 ```
 

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/prompts/upgrade-methodology/01-content-gaps.md

@@ -204,6 +204,19 @@ doubled-graph migrate check --repo .   # context_gaps должен быть []
 
 Если после заполнения `context_gaps` пуст, а `grep` всё ещё что-то находит — это строка внутри `<LegacySource>` (архив), её не трогай: проверяй только рабочие секции, не архив.
 
+### BOM в исходниках
+
+`doubled-graph` сам читает BOM-файлы (`utf-8-sig`), но анализатор движка для Python/TypeScript/Dart через `ast.parse`/тулинг отвергает U+FEFF: `grace lint` даёт `analysis.adapter-failed: invalid non-printable character U+FEFF at line 1:1`. Проверь заранее:
+
+```bash
+doubled-graph migrate check --repo .   # bom_files / bom_adapter_files, warning migration.bom-in-code
+```
+
+- **файлы клиента не изменяются**: `doubled-graph lint` при наличии BOM запускает движок на временной копии, где BOM нормализован (только `.grace/*.xml` и adapter-исходники `.py/.pyi/.ts/.tsx/.js/.jsx/.mjs/.cjs/.mts/.cts/.dart`), и переписывает пути отчёта обратно на реальный репозиторий;
+- если `bom_adapter_files` непусто, но `lint` зелёный — это и есть работа зеркала: BOM остался в исходниках, гейт пройден;
+- файлы без адаптера (C#, Go, Rust, Java, Swift, …) попадают в копию **как есть**, BOM у них не снимается: движок не запускает для них анализатор, поэтому lint от BOM не зависит;
+- ничего не удаляй и не перекодируй вручную; если lint всё же даёт `analysis.adapter-failed` с U+FEFF — это сигнал, что зеркало не сработало (сообщи о баге), а не повод править файлы.
+
 ---
 
 ## Шаг 5 — отчёт пользователю (формат фиксированный)

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "doubled-graph"
-version = "2.0.1"
+version = "2.0.2"
 description = "MCP facade over CodeGraphContext + GRACE 4 (.grace artifacts): impact, context, drift-detect, migration for LLM-driven codebases."
 readme = "README.md"
 license = { text = "MIT" }

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/src/doubled_graph/cli.py

@@ -325,7 +325,7 @@ def _cmd_health(args: argparse.Namespace) -> int:
     drift_md = repo / "docs" / "DRIFT.md"
     open_drift_entries = 0
     if drift_md.exists():
-        text = drift_md.read_text(encoding="utf-8")
+        text = drift_md.read_text(encoding="utf-8-sig")
         # Sections separated by `## D-`; resolved if section contains "Resolved"
         sections = [s for s in text.split("\n## D-") if s.strip()]
         open_drift_entries = sum(1 for s in sections if "Resolved" not in s and "resolved" not in s)

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/src/doubled_graph/config.py

@@ -47,9 +47,9 @@ def _load_yaml(p: Path) -> dict:
     except ModuleNotFoundError:
         import json as _json
 
-        with p.open("r", encoding="utf-8") as f:
+        with p.open("r", encoding="utf-8-sig") as f:
             return _json.load(f)
-    with p.open("r", encoding="utf-8") as f:
+    with p.open("r", encoding="utf-8-sig") as f:
         return yaml.safe_load(f) or {}
 
 
@@ -61,7 +61,7 @@ def load_config(repo_path: Path) -> Config:
     if p.suffix in (".yaml", ".yml"):
         data = _load_yaml(p)
     else:
-        with p.open("r", encoding="utf-8") as f:
+        with p.open("r", encoding="utf-8-sig") as f:
             data = json.load(f)
     return Config(**data)
 

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/src/doubled_graph/graphs/grace4.py

@@ -109,7 +109,9 @@ _BARE_AMP = re.compile(r"&(?!amp;|lt;|gt;|apos;|quot;|#\d+;|#x[0-9a-fA-F]+;)")
 _PATH_FIELD = re.compile(r"(?:Path|File)\s+([^\s]+)")
 _LINKS_VALUE = re.compile(r"(?im)^\s*(?://|#|--|;+|\*)\s*LINKS:\s*(?P<value>.+)$")
 _CONTRACT_SECTION = re.compile(
-    r"(?ms)^\s*(?://|#|--|;+|\*)\s*START_MODULE_CONTRACT\s*$(?P<body>.*?)^\s*(?://|#|--|;+|\*)\s*END_MODULE_CONTRACT\s*$"
+    # ``\ufeff?``: a BOM may survive when the text did not come from a
+    # ``utf-8-sig`` read; Python's ``\s`` does not match U+FEFF (JS does).
+    r"(?ms)^\ufeff?\s*(?://|#|--|;+|\*)\s*START_MODULE_CONTRACT\s*$(?P<body>.*?)^\s*(?://|#|--|;+|\*)\s*END_MODULE_CONTRACT\s*$"
 )
 
 
@@ -247,7 +249,7 @@ def legacy_documents(root: Path) -> list[str]:
 def _safe_parse(path: Path) -> tuple[ET.Element | None, str]:
     """Parse XML, escaping bare ``&`` on retry. Returns (root, error message)."""
     try:
-        raw = path.read_text(encoding="utf-8")
+        raw = path.read_text(encoding="utf-8-sig")
     except OSError as exc:
         return None, f"cannot read {path.name}: {exc}"
     try:
@@ -469,7 +471,10 @@ def scan_governed_links(
     issues: list[Issue] = []
     for file_path in iter_code_files(resolved, ignored):
         try:
-            text = file_path.read_text(encoding="utf-8", errors="replace")
+            # `utf-8-sig` strips a BOM: Python's `\s` does not match U+FEFF (the
+            # JS engine's `\s` does), so a BOM would hide every marker from our
+            # `^\s*//` regex while `grace lint` still sees the file.
+            text = file_path.read_text(encoding="utf-8-sig", errors="replace")
         except OSError:
             continue
         section = _CONTRACT_SECTION.search(text)

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/src/doubled_graph/hooks_installer.py

@@ -61,7 +61,7 @@ def _install_post_commit(repo: Path, dry_run: bool) -> dict:
 
     # Soft-safety: if file exists and is non-empty AND doesn't contain our signature — back up.
     if target.exists():
-        existing = target.read_text(encoding="utf-8", errors="replace")
+        existing = target.read_text(encoding="utf-8-sig", errors="replace")
         if "doubled-graph init-hooks" not in existing:
             backup = target.with_suffix(".backup")
             target.rename(backup)
@@ -76,13 +76,25 @@ def _install_post_commit(repo: Path, dry_run: bool) -> dict:
     return {"post_commit": "installed", "path": str(target), "note": replaced}
 
 
+_BOM_PREFIX = b"\xef\xbb\xbf"
+
+
+def _had_bom(path: Path) -> bool:
+    """True when an existing file starts with a UTF-8 BOM."""
+    try:
+        return path.read_bytes().startswith(_BOM_PREFIX)
+    except OSError:
+        return False
+
+
 def _install_claude_code(repo: Path, dry_run: bool) -> dict:
     settings = repo / ".claude" / "settings.json"
     settings.parent.mkdir(parents=True, exist_ok=True)
+    had_bom = _had_bom(settings)
     data: dict = {}
     if settings.exists():
         try:
-            data = json.loads(settings.read_text(encoding="utf-8"))
+            data = json.loads(settings.read_text(encoding="utf-8-sig"))
         except json.JSONDecodeError:
             return {"claude_code": "error", "reason": f"cannot parse {settings}"}
     hooks = data.setdefault("hooks", {})
@@ -100,7 +112,8 @@ def _install_claude_code(repo: Path, dry_run: bool) -> dict:
         return {"claude_code": "dry-run", "path": str(settings), "would_add": CLAUDE_HOOK_ENTRY}
 
     post_tool_use.append(CLAUDE_HOOK_ENTRY)
-    settings.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    # Keep the client's BOM: rewriting a settings file must not re-encode it.
+    settings.write_text(json.dumps(data, indent=2), encoding="utf-8-sig" if had_bom else "utf-8")
     return {"claude_code": "installed", "path": str(settings)}
 
 
@@ -125,13 +138,13 @@ def ensure_gitignore_entries(repo_path: Path, dry_run: bool = False) -> dict:
     so skipping hooks shouldn't leave the user's `git status` polluted.
     """
     gi = repo_path / ".gitignore"
-    existing = gi.read_text(encoding="utf-8") if gi.exists() else ""
+    existing = gi.read_text(encoding="utf-8-sig") if gi.exists() else ""
     missing = [line for line in DOUBLED_GRAPH_GITIGNORE_LINES if line not in existing]
     if not missing:
         return {"status": "already_present", "lines": DOUBLED_GRAPH_GITIGNORE_LINES}
     if dry_run:
         return {"status": "dry_run", "would_append": missing}
-    with gi.open("a", encoding="utf-8") as f:
+    with gi.open("a", encoding="utf-8-sig") as f:
         if existing and not existing.endswith("\n"):
             f.write("\n")
         f.write("\n# doubled-graph\n" + "\n".join(missing) + "\n")

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/src/doubled_graph/integrations/grace_cli.py

@@ -14,9 +14,11 @@ import re
 import shutil
 import subprocess
 import sys
+import tempfile
+from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any
+from typing import Any, Iterator
 
 
 class GraceCLIMissing(RuntimeError):
@@ -773,6 +775,111 @@ class FileRecord:
     raw: dict | None = None
 
 
+_BOM = b"\xef\xbb\xbf"
+_ADAPTER_EXTENSIONS = frozenset({
+    ".py", ".pyi", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".dart",
+})
+
+
+def _adapter_bom_files(repo_path: Path) -> list[Path]:
+    """Adapter-backed sources that start with a UTF-8 BOM (client files untouched)."""
+    from doubled_graph.graphs.grace4 import iter_code_files
+
+    found: list[Path] = []
+    for file_path in iter_code_files(repo_path, ignored=(".doubled-graph",)):
+        if file_path.suffix.lower() not in _ADAPTER_EXTENSIONS:
+            continue
+        try:
+            with file_path.open("rb") as handle:
+                if handle.read(3) == _BOM:
+                    found.append(file_path)
+        except OSError:
+            continue
+    return found
+
+
+def _grace_has_bom(repo_path: Path) -> bool:
+    """True when any `.grace` document starts with a BOM (the engine misses it)."""
+    grace = repo_path / ".grace"
+    if not grace.is_dir():
+        return False
+    for path in grace.rglob("*.xml"):
+        try:
+            with path.open("rb") as handle:
+                if handle.read(3) == _BOM:
+                    return True
+        except OSError:
+            continue
+    return False
+
+
+def _copy_tree_for_lint(repo_path: Path, mirror: Path) -> None:
+    """Snapshot `.grace` + code files; BOM files are normalised in the copy only.
+
+    The engine rejects U+FEFF in adapter analyzers and skips `<Path>` entries in
+    a BOM-prefixed index, so lint needs BOM-free real copies — but the client's
+    working tree is never written to.
+    """
+    from doubled_graph.graphs.grace4 import iter_code_files
+
+    grace = repo_path / ".grace"
+    for directory in [grace, *(path for path in grace.rglob("*") if path.is_dir())]:
+        if directory.is_dir():
+            (mirror / directory.relative_to(repo_path)).mkdir(parents=True, exist_ok=True)
+    for source in grace.rglob("*"):
+        if not source.is_file():
+            continue
+        target = mirror / source.relative_to(repo_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        raw = source.read_bytes()
+        target.write_bytes(raw[len(_BOM):] if raw.startswith(_BOM) else raw)
+    config = repo_path / ".doubled-graph" / "config.json"
+    if config.exists():
+        (mirror / ".doubled-graph").mkdir(parents=True, exist_ok=True)
+        shutil.copy2(config, mirror / ".doubled-graph" / "config.json")
+    for file_path in iter_code_files(repo_path, ignored=(".doubled-graph",)):
+        relative = file_path.relative_to(repo_path)
+        target = mirror / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        raw = file_path.read_bytes()
+        if file_path.suffix.lower() in _ADAPTER_EXTENSIONS and raw.startswith(_BOM):
+            raw = raw[len(_BOM):]
+        target.write_bytes(raw)
+
+
+@contextmanager
+def lint_mirror(repo_path: Path) -> Iterator[Path]:
+    """Yield a lintable root: the repository itself, or a BOM-normalised snapshot.
+
+    Why a snapshot: the methodology must work on BOM sources, and the client's
+    files must not be modified. The engine's Python/TS/Dart analyzer fails on
+    U+FEFF, so lint runs on a temporary copy where those BOMs are absent; JSON
+    paths are rebased back to the real repository before returning.
+    """
+    if not _adapter_bom_files(repo_path) and not _grace_has_bom(repo_path):
+        yield repo_path
+        return
+    temp_root = Path(tempfile.mkdtemp(prefix="doubled-graph-lint-"))
+    try:
+        mirror = temp_root / "repo"
+        mirror.mkdir()
+        _copy_tree_for_lint(repo_path, mirror)
+        yield mirror
+    finally:
+        shutil.rmtree(temp_root, ignore_errors=True)
+
+
+def _rebase(value: Any, old: str, new: str) -> Any:
+    """Replace the temporary mirror root with the real repository path."""
+    if isinstance(value, str):
+        return value.replace(old, new)
+    if isinstance(value, list):
+        return [_rebase(item, old, new) for item in value]
+    if isinstance(value, dict):
+        return {key: _rebase(item, old, new) for key, item in value.items()}
+    return value
+
+
 class GraceCLI:
     """Thin subprocess wrapper around the upstream `grace` CLI (Bun, MIT).
 
@@ -914,7 +1021,7 @@ class GraceCLI:
             "is available. Install Bun (https://bun.sh/) or tsx (`npm install -g tsx`)."
         )
 
-    def _run_soft(self, args: list[str]) -> dict[str, Any]:
+    def _run_soft(self, args: list[str], cwd: Path | None = None) -> dict[str, Any]:
         """Run grace, return rc/stdout/stderr structured. Raise only on real failure.
 
         Soft-failure protocol (1.4.4): rc=0 = success, rc=1 = expected
@@ -935,7 +1042,7 @@ class GraceCLI:
         cmd = self._build_cmd(args)
         proc = subprocess.run(
             cmd,
-            cwd=str(self.repo_path),
+            cwd=str(cwd or self.repo_path),
             capture_output=True,
             text=True,
             check=False,
@@ -991,7 +1098,7 @@ class GraceCLI:
             raise RuntimeError("\n  ".join(parts))
         return proc.stdout
 
-    def _json_command(self, args: list[str]) -> dict:
+    def _json_command(self, args: list[str], cwd: Path | None = None) -> dict:
         """Run a GRACE 4 command that answers with JSON (body or error envelope).
 
         Engine 4.x contract: success prints the payload; failure prints
@@ -1000,7 +1107,7 @@ class GraceCLI:
         both shapes intact and always stamp ``ok`` / ``exit_code`` so callers
         never have to reason about rc alone.
         """
-        soft = self._run_soft(args)
+        soft = self._run_soft(args, cwd=cwd)
         out = soft["stdout"]
         err = soft["stderr"].strip()
         parsed: Any
@@ -1048,10 +1155,19 @@ class GraceCLI:
         streams ``--run-commands`` output, which is not what our CLI flag
         means.
         """
-        args = ["lint", "--path", str(self.repo_path), "--format", "json"]
-        if verbose:
-            args.append("--remediate")
-        return self._json_command(args)
+        with lint_mirror(self.repo_path) as lint_root:
+            # `--path .` + cwd=mirror: engine 4.2.1 reports
+            # `projection.*.unindexed-document` for an absolute --path outside cwd.
+            path_arg = "." if lint_root != self.repo_path else str(self.repo_path)
+            args = ["lint", "--path", path_arg, "--format", "json"]
+            if verbose:
+                args.append("--remediate")
+            # cwd matters: the engine resolves `.grace` relative to cwd, so a
+            # mirror with --path alone would mix the original index with copies.
+            result = self._json_command(args, cwd=lint_root)
+        if lint_root != self.repo_path:
+            result = _rebase(result, str(lint_root), str(self.repo_path))
+        return result
 
     def module_show(self, id_or_path: str, with_verification: bool = False) -> ModuleRecord:
         """Fetch module record: contract + exports + deps + (opt.) V-M-* list.

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/src/doubled_graph/migrations/__init__.py

@@ -7,7 +7,7 @@
   ``doubled-graph setup``.
 """
 
-from doubled_graph.migrations.grace3_to_grace4 import (  # noqa: F401
+from doubled_graph.migrations.grace3_to_grace4 import (
     MigrationReport,
     apply_migration,
     bootstrap_project,

{doubled_graph-2.0.1 → doubled_graph-2.0.2}/src/doubled_graph/migrations/grace3_to_grace4.py

@@ -53,8 +53,30 @@ ROLE_MAP_MODE: dict[str, str] = {
 }
 
 _CONTEXT_MARKER = r"(?://|#|--|;+|\*)"
+_BOM = b"\xef\xbb\xbf"
+
+
+def _read_code_file(path: Path) -> tuple[str, bool]:
+    """Read a source file and report whether it carried a UTF-8 BOM.
+
+    Python's ``\\s`` does not match U+FEFF, so a BOM left in place hides
+    ``^\\s*// MODULE:`` from every regex here (the JS engine's ``\\s`` does
+    match it, so ``grace lint`` still sees the file — a silent divergence).
+    """
+    try:
+        raw = path.read_bytes()
+    except OSError:
+        return "", False
+    has_bom = raw.startswith(_BOM)
+    return raw.decode("utf-8-sig", errors="replace"), has_bom
+
+
+def _write_code_file(path: Path, text: str, has_bom: bool) -> None:
+    """Write source text back, preserving the original BOM."""
+    path.write_text(text, encoding="utf-8-sig" if has_bom else "utf-8")
 _CONTRACT_SECTION = re.compile(
-    rf"(?ms)^\s*{_CONTEXT_MARKER}\s*START_MODULE_CONTRACT\s*$(?P<body>.*?)^\s*{_CONTEXT_MARKER}\s*END_MODULE_CONTRACT\s*$"
+    # ``\ufeff?``: tolerate a BOM when the text was not read with ``utf-8-sig``.
+    rf"(?ms)^\ufeff?\s*{_CONTEXT_MARKER}\s*START_MODULE_CONTRACT\s*$(?P<body>.*?)^\s*{_CONTEXT_MARKER}\s*END_MODULE_CONTRACT\s*$"
 )
 _MODULE_FIELD = re.compile(rf"(?im)^(?P<indent>\s*{_CONTEXT_MARKER}\s*)MODULE:\s*(?P<value>M-[A-Za-z0-9-]+)\s*$")
 _LINKS_LINE = re.compile(rf"(?im)^(?P<prefix>\s*{_CONTEXT_MARKER}\s*)LINKS:\s*(?P<value>.*)$")
@@ -100,6 +122,12 @@ class MigrationReport:
     #: Context documents the legacy artifacts left as a skeleton (0-1 field),
     #: so the content prompt must fill them instead of trusting the migration.
     context_gaps: list[str] = field(default_factory=list)
+    #: Code files that start with a UTF-8 BOM. Our commands handle them, but the
+    #: engine's Python/TypeScript/Dart analyzer rejects U+FEFF (`ast.parse`),
+    #: so lint fails for these files until the BOM is removed.
+    bom_files: list[str] = field(default_factory=list)
+    #: Subset of ``bom_files`` in languages the engine analyzes with an adapter.
+    bom_adapter_files: list[str] = field(default_factory=list)
     modules: int = 0
     verifications: int = 0
     placeholders: list[str] = field(default_factory=list)
@@ -132,6 +160,8 @@ class MigrationReport:
             "markup_pending": list(self.markup_pending),
             "map_pending": list(self.map_pending),
             "context_gaps": list(self.context_gaps),
+            "bom_files": list(self.bom_files),
+            "bom_adapter_files": list(self.bom_adapter_files),
             "modules": self.modules,
             "verifications": self.verifications,
             "placeholders": list(self.placeholders),
@@ -194,7 +224,9 @@ def check_migration(root: Path) -> MigrationReport:
     if report.markup_pending:
         report.issues.append(Issue("warning", "migration.markup-pending", ".",
                                    f"{len(report.markup_pending)} governed file(s) declare no M-* in MODULE_CONTRACT LINKS."))
+    report.bom_files, report.bom_adapter_files = _bom_scan(resolved)
     _add_context_gap_warning(report)
+    _add_bom_warning(report)
     report.ok = not report.errors
     return report
 
@@ -239,7 +271,9 @@ def apply_migration(
 
     report.map_pending = _plan_map_work(resolved)
     report.context_gaps = _context_gaps(resolved)
+    report.bom_files, report.bom_adapter_files = _bom_scan(resolved)
     _add_context_gap_warning(report)
+    _add_bom_warning(report)
 
     if fix_markup:
         changed, pending = _apply_markup_fix(resolved, dry_run=dry_run)
@@ -424,7 +458,7 @@ def _scan_unsupported(root: Path) -> list[str]:
     if docs.is_dir():
         for path in sorted(docs.glob("*.xml")):
             try:
-                texts[str(path.relative_to(root))] = path.read_text(encoding="utf-8", errors="replace")
+                texts[str(path.relative_to(root))] = _read_code_file(path)[0]
             except OSError:
                 continue
     found: list[str] = []
@@ -666,7 +700,7 @@ def _context_values(root: Path) -> tuple[dict[str, str], dict[str, int]]:
     grace_tech = root / ".grace" / "context" / "technology.xml"
     grace_req = root / ".grace" / "context" / "requirements.xml"
     if grace_tech.exists():
-        text = grace_tech.read_text(encoding="utf-8", errors="replace")
+        text = grace_tech.read_text(encoding="utf-8-sig", errors="replace")
         technology = {
             field: value
             for field, _aliases in _TECHNOLOGY_FIELDS
@@ -680,7 +714,7 @@ def _context_values(root: Path) -> tuple[dict[str, str], dict[str, int]]:
         }
 
     if grace_req.exists():
-        text = grace_req.read_text(encoding="utf-8", errors="replace")
+        text = grace_req.read_text(encoding="utf-8-sig", errors="replace")
         requirements = {
             "project": _legacy_value(text, "ProjectName") if not is_placeholder(_legacy_value(text, "ProjectName")) else None,
             "goals": [value for value in _list_values(text, "Goal") if not is_placeholder(value)],
@@ -742,6 +776,47 @@ def _context_gaps(root: Path) -> list[str]:
     return gaps
 
 
+#: Source languages the engine analyzes with its own adapters; their analyzers
+#: (Python `ast.parse`, TypeScript/Dart tooling) reject a leading U+FEFF.
+_ADAPTER_EXTENSIONS = frozenset({".py", ".pyi", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".dart"})
+
+_BOM_BYTES = b"\xef\xbb\xbf"
+
+
+def _bom_scan(root: Path) -> tuple[list[str], list[str]]:
+    """Return (all BOM files, BOM files whose language has an engine adapter)."""
+    all_bom: list[str] = []
+    adapter_bom: list[str] = []
+    for file_path in iter_code_files(root, ignored=(".doubled-graph",)):
+        try:
+            with file_path.open("rb") as handle:
+                prefix = handle.read(3)
+        except OSError:
+            continue
+        if prefix != _BOM_BYTES:
+            continue
+        relative = file_path.relative_to(root).as_posix()
+        all_bom.append(relative)
+        if file_path.suffix.lower() in _ADAPTER_EXTENSIONS:
+            adapter_bom.append(relative)
+    return sorted(all_bom), sorted(adapter_bom)
+
+
+def _add_bom_warning(report: MigrationReport) -> None:
+    if not report.bom_adapter_files:
+        return
+    report.issues.append(Issue(
+        "warning",
+        "migration.bom-in-code",
+        report.bom_adapter_files[0],
+        f"{len(report.bom_adapter_files)} source file(s) start with a UTF-8 BOM; the engine's "
+        "Python/TypeScript/Dart analyzer rejects U+FEFF, so `grace lint` reports "
+        "`analysis.adapter-failed` for them until the BOM is removed. "
+        "doubled-graph commands handle BOM files themselves; languages without an adapter "
+        "(C#, Go, Rust, Java, Swift, …) are unaffected.",
+    ))
+
+
 def _add_context_gap_warning(report: MigrationReport) -> None:
     """Warn only when the legacy context documents were a skeleton (0-1 field).
 
@@ -1002,7 +1077,7 @@ def _parse_xml(path: Path):
     import xml.etree.ElementTree as ET
 
     try:
-        raw = path.read_text(encoding="utf-8", errors="replace")
+        raw = path.read_text(encoding="utf-8-sig", errors="replace")
     except OSError:
         return None
     try:
@@ -1060,9 +1135,8 @@ def _plan_markup_fix(root: Path) -> list[tuple[str, str]]:
     """Return ``(relative_path, module_id)`` for files whose LINKS lack M-*."""
     planned: list[tuple[str, str]] = []
     for file_path in iter_code_files(root, ignored=(".doubled-graph",)):
-        try:
-            text = file_path.read_text(encoding="utf-8", errors="replace")
-        except OSError:
+        text, _has_bom = _read_code_file(file_path)
+        if not text:
             continue
         section = _CONTRACT_SECTION.search(text)
         if section is None:
@@ -1091,9 +1165,8 @@ def _plan_map_work(root: Path) -> list[str]:
     """
     pending: list[str] = []
     for file_path in iter_code_files(root, ignored=(".doubled-graph",)):
-        try:
-            text = file_path.read_text(encoding="utf-8", errors="replace")
-        except OSError:
+        text, _has_bom = _read_code_file(file_path)
+        if not text:
             continue
         section = _CONTRACT_SECTION.search(text)
         if section is None:
@@ -1119,15 +1192,14 @@ def _apply_markup_fix(root: Path, *, dry_run: bool) -> tuple[list[str], list[str
         if dry_run:
             continue
         path = root / relative
-        try:
-            text = path.read_text(encoding="utf-8")
-        except OSError:
+        text, has_bom = _read_code_file(path)
+        if not text:
             continue
         new_text = _fix_file_markup(text, module_id)
         if new_text == text:
             continue
         try:
-            path.write_text(new_text, encoding="utf-8")
+            _write_code_file(path, new_text, has_bom)
         except OSError:
             continue
         changed.append(relative)