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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: doubled-graph
-Version: 2.0.0
+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.0
+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.0 → doubled_graph-2.0.2}/README.md

@@ -119,7 +119,7 @@ head -1 "$(which doubled-graph)"  # вывести shebang — это и ест
 ### 4. Проверить, что всё встало
 
 ```bash
-doubled-graph --version          # 2.0.0
+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.0 → doubled_graph-2.0.2}/docs/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 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
+change: upgrade is additive, `pipx upgrade doubled-graph` and a re-run of
+`doubled-graph setup` (or `migrate apply` on an unmigrated repo) is enough.
+
+**Why:** 2.0.0 could migrate a real GRACE 3 repository into a project where
+`grace lint` is green but the context documents are empty (`unknown`,
+`Migrated project`, one generic goal) and `TestingStack` cannot produce a
+`<Command>` for `V-<M>`. The checks below make that state visible and prevent
+silent data loss during the copy.
+
+### Fixed — legacy format edge cases (all lose data silently if missed)
+- Namespaced legacy XML: tags arrive as `{urn}M-AUTH`, every `^M-` match failed
+  and a project migrated with **zero modules**. Namespaces are stripped before
+  matching (elements and attributes).
+- UTF-16/UTF-32/BOM legacy documents: `read_text("utf-8")` raised
+  `UnicodeDecodeError`; reads now try `utf-8-sig` → `utf-16` → `utf-32` → `cp1251`.
+- `CDATA` values (`<Language><![CDATA[C#]]></Language>`) were stripped to empty;
+  `CDATA` is unwrapped before tag removal.
+- Module `NAME` / `STATUS` / `TYPE` attributes were dropped (the migrator wrote
+  `Name` from the id and `Status=existing`); they are preserved (`Type` as a
+  free child tag, which GRACE 4 does not validate).
+- Several GRACE 3 verification records for one module (`V-M-AUTH-1`, `-2`, …)
+  collapsed into one canonical `V-M-AUTH` and only the first record's evidence
+  survived; commands, scenarios, markers, trace assertions and test files are
+  now merged.
+- Lowercase/mixed-case contract keys (`role:`, `map_mode:`, `links:`) are
+  silently ignored by the engine's field parser and produced
+  `markup.invalid-role`; the markup repair normalises keys to UPPERCASE and
+  ROLE values to upper case.
+- Windows-style paths (`src\\auth\\a.py`) are normalised to forward slashes, so
+  `LINKS`-based file-to-module linkage matches.
+- Self-closing `<UC-1 ... />` entries were skipped by the use-case extractor;
+  they are now rendered as goals.
+- `migration.context-skeleton` was emitted even when the repository has no
+  artifacts at all (kind `none`); the warning is now gated to migrated projects.
+
+### Fixed — context documents are copied, not skeletonised
+- The migrator now **copies** the legacy context documents instead of shipping a
+  skeleton: `technology.xml` fields (`Language`, `Runtime`, `Framework`,
+  `TestingStack`, `Observability`) and `requirements.xml` sections
+  (`ProjectName`, `Goals` from `UC-*` as text, `Users` from `ACTOR`, `Constraints`)
+  are taken from the old document; undeclared fields are marked
+  `not specified` (never guessed), and `LegacySource` keeps the archive copy.
+- New `context_gaps` in the migration report plus `migration.context-skeleton`
+  warning. The check is gated: it fires when the copied documents are a skeleton
+  (0–1 real field) **or** when `TestingStack` is still a placeholder — a richer
+  document is trusted as-is. It reads the current `.grace/context`, not the
+  legacy documents (which stay on disk forever), so a completed migration
+  reports no gaps. Recognised placeholders include the old migrator/bootstrap
+  prose (`unknown`, `Migrated project`, `Keep the project governed…`,
+  `Describe the primary…`, `Restore the product intent…`), and the bootstrap
+  path now writes `not specified` instead of `unknown`.
+- `01-content-gaps.md` gained **Шаг 0 «context-документы»** (before
+  `MODULE_MAP`) and a mandatory **Шаг 4a «context gate»**: a `grep` over
+  `.grace/context/*.xml` for placeholders plus `context_gaps == []` from
+  `migrate check`, with `deployment`/`ux` `not-applicable` explicitly allowed.
+  `<Command>` for `V-<M>` must not be derived while `TestingStack` is a
+  placeholder.
+
 ## [2.0.0] — 2026-10-23
 
 **Breaking: GRACE 4.** The methodology now runs on the `.grace` artifact model

{doubled_graph-2.0.0 → 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.0", "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.0", "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.0", "...": "..."}
+  "meta": {"phase": "...", "tool_version": "2.0.2", "...": "..."}
 }
 ```
 

{doubled_graph-2.0.0 → doubled_graph-2.0.2}/prompts/upgrade-methodology/00-entry-prompt.md

@@ -56,6 +56,8 @@ doubled-graph lint --repo .       # summary.errors
 prompts/upgrade-methodology/01-content-gaps.md
 ```
 
+Первым его шагом идёт **Шаг 0 — context-документы**: если `migrate check` показывает `context_gaps` (legacy объявил 0–1 поле), ИИ заполняет `technology.xml` (в первую очередь `TestingStack`) и `requirements.xml` из `<LegacySource>` / манифестов проекта, иначе `<Command>` для `V-<M>` вывести не из чего.
+
 Он детерминированно проходит `map_pending` (карты модулей), `placeholders` (пустые `V-<M>`), `markup_pending` (`LINKS`) и заканчивается финальными CLI-проверками. Выдуманные команды запрещены: если тест не найден или не проходит — запись остаётся пустой, ставится `Priority: low` и строка в `docs/DRIFT.md`.
 
 6. Вернуться к обычному циклу: `prompts/maintenance/on-before-edit.md` / `on-after-edit.md`. Legacy `docs/` можно заархивировать отдельным решением (бэкап + approval), это не обязательный шаг.

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

@@ -23,6 +23,35 @@ doubled-graph health --repo .          # модули без verification
 
 ---
 
+## Шаг 0 — context-документы (до всего остального)
+
+Мигратор копирует старые `requirements.xml`/`technology.xml` в `.grace/context/`, но если legacy объявлял 0–1 поле, документ остаётся скелетом: `migrate check` показывает `context_gaps` и warning `migration.context-skeleton`, а поля помечены `not specified`. Пока это не заполнено, из `technology.xml` нельзя вывести `<Command>` для `V-<M>` (шаг 2) — поэтому шаг 0 обязателен и идёт первым.
+
+1. Проверь маркеры командой:
+
+```bash
+grep -n "not specified\|unknown\|Migrated project" .grace/context/*.xml
+```
+
+2. Заполняй поля в этом порядке (первый источник, который даёт факт, — истина):
+
+| Поле | Источник 1 | Источник 2 | Источник 3 |
+|---|---|---|---|
+| `Language`, `Runtime`, `Framework`, `TestingStack`, `Observability` (`technology.xml`) | legacy-значения внутри `<LegacySource>` (там лежит старый `docs/technology.xml` целиком) | манифесты проекта: `*.csproj`/`*.sln`, `package.json`, `pyproject.toml`/`pytest.ini`, `go.mod`, `Cargo.toml`, `pom.xml`/`build.gradle`, `Gemfile`, `composer.json`, `Package.swift`, `mix.exs`, `CMakeLists.txt`/`Makefile` — найденные `find . -maxdepth 3 -name '<manifest>'` | README / CI (`.github/workflows/*`, `.gitlab-ci.yml`) |
+| `ProjectName`, `Goals`, `Users`, `Constraints` (`requirements.xml`) | legacy `<LegacySource>`: `UC-*` → `Goal` текстом, `ACTOR`/`User` → `Users`, `Constraint`/`NFR` → `Constraints` | README (первый абзац/раздел «О проекте») и существующие issue/ADR | — |
+| `deployment.xml` | манифесты инфраструктуры: `Dockerfile`, `docker-compose*.yml`, `k8s/*.yaml`, `helm/`, `Chart.yaml`, `Procfile`, `fly.toml`, `*.tf`, `serverless.yml`, `vercel.json` | README/CI deploy-шаг | `not-applicable` + `<Reason>infrastructure manifests not found</Reason>` |
+| `ux-guidelines.xml` | манифесты фронтенда: `index.html`, `*.xaml`/`*.razor`/`*.vue`/`*.svelte`, `package.json` с react/vue/angular/svelte | README/скриншоты | `not-applicable` + `<Reason>frontend manifests not found</Reason>` |
+
+3. Правила:
+   - значения **копируются** из legacy/манифестов, не придумываются; язык — по манифестам проекта, а не по типу задачи;
+   - `TestingStack` — команда раннера из манифеста (`package.json → scripts.test`, `pyproject/pytest.ini → pytest`, `*proj/*sln → dotnet test`, `go.mod → go test ./...`, `Cargo.toml → cargo test`, `pom.xml → mvn test`, `build.gradle → ./gradlew test`, `Gemfile → bundle exec rspec`, `composer.json → phpunit`, `Package.swift → swift test`, `mix.exs → mix test`, `CMakeLists.txt/Makefile → ctest/make test`);
+   - если факт не найден ни в одном источнике — поле остаётся `not specified`, строка в `docs/DRIFT.md`; шаг 2 в этом случае не выводит `Command` для `V-<M>` (модуль получает `Priority: low`, как в fallback шага 2);
+   - `deployment`/`ux` как `not-applicable` с причиной — законное состояние, а не пробел.
+
+4. Проверь: `doubled-graph lint --repo .` (0 errors) и `doubled-graph migrate check --repo .` (`context_gaps == []`).
+
+---
+
 ## Шаг 1 — `MODULE_MAP` (устраняет `markup.module-map-missing`)
 
 Для каждого пути из `map_pending`, по порядку:
@@ -155,6 +184,41 @@ doubled-graph module health <M-*> --repo .         # критичные моду
 
 ---
 
+## Шаг 4a — context gate: в context нет заглушек
+
+Обязательная проверка перед отчётом: `context/*.xml` не должны содержать ни `unknown`, ни шаблонных фраз мигратора/бутстрапа. Проверяется командой, а не «на глаз»:
+
+```bash
+grep -nE "not specified|unknown|Migrated project|Describe the primary|replace with the real product statement|Keep the project governed|Existing project maintainers|Legacy GRACE 3 documents stay in place|No operational constraints were declared|Users were not described|Restore the product intent|Not configured yet" .grace/context/*.xml
+doubled-graph migrate check --repo .   # context_gaps должен быть []
+```
+
+Что означает каждая находка:
+
+| Находка | Действие |
+|---|---|
+| `technology: … TestingStack is still a placeholder` | заполнить `TestingStack` из `<LegacySource>` или манифеста (шаг 0), иначе `<Command>` для `V-<M>` не выводится |
+| `technology: 0–1/5 real field(s)` | заполнить Language/Runtime/Framework/Observability по шагу 0 |
+| `requirements: … real section(s)` / `Goals are still a placeholder` | перенести `UC-*`/README-цели в `<Goals>` (шаг 0) |
+| `deployment`/`ux` с `not-applicable` + `<Reason>` | не находка: это законное состояние, пропустить |
+
+Если после заполнения `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 — отчёт пользователю (формат фиксированный)
 
 ```
@@ -173,7 +237,8 @@ health:      модулей без verification=<N>
 | Проверка | Готово, когда |
 |---|---|
 | `doubled-graph lint` | `summary.errors == 0` |
-| `doubled-graph migrate check` | `map_pending == []`, `placeholders == []` |
+| `doubled-graph migrate check` | `map_pending == []`, `placeholders == []`, `context_gaps == []` |
+| `grep -nE "not specified\|unknown\|Migrated project\|Describe the primary\|Keep the project governed" .grace/context/*.xml` | пусто вне `<LegacySource>`, кроме `deployment`/`ux` с `not-applicable` и `<Reason>` |
 | `doubled-graph detect-changes --scope all` | `missing_verification` только у записей с `DRIFT.md` |
 | `doubled-graph health` | нет модулей без `V-<M>` |
 | `module health` критичных модулей | не `blocked` |
@@ -203,6 +268,19 @@ health:      модулей без verification=<N>
   doubled-graph health --repo .
 Работай по спискам map_pending / placeholders / markup_pending из вывода.
 
+Шаг 0. Context-документы (обязательно до MODULE_MAP и V-<M>):
+  - проверь маркеры: grep -n "not specified\|unknown\|Migrated project" .grace/context/*.xml
+  - technology.xml: Language/Runtime/Framework/TestingStack/Observability — из <LegacySource> (старый documents/technology.xml),
+    затем из манифестов проекта (find . -maxdepth 3: *.csproj/*.sln, package.json, pyproject.toml/pytest.ini, go.mod,
+    Cargo.toml, pom.xml/build.gradle, Gemfile, composer.json, Package.swift, mix.exs, CMakeLists.txt/Makefile), затем README/CI;
+    TestingStack = команда раннера из манифеста (не догадка);
+  - requirements.xml: ProjectName/Goals/Users/Constraints — из <LegacySource> (UC-* -> Goal текстом, ACTOR/User -> Users,
+    Constraint/NFR -> Constraints), затем README;
+  - deployment.xml/ux-guidelines.xml: по инфраструктурным/фронтенд-манифестам; если их нет — <Applicability>not-applicable</Applicability>
+    + <Reason>;
+  - если факт не найден — поле оставь "not specified" и добавь строку в docs/DRIFT.md; НЕ выдумывай стек.
+  - проверь: doubled-graph migrate check --repo . -> context_gaps = []
+
 Шаг 1. MODULE_MAP для каждого пути из map_pending:
   - прочитай контракт: doubled-graph file show <path> --repo .;
   - извлеки публичные символы командой `grep` по правилам для языка:
@@ -250,6 +328,11 @@ health:      модулей без verification=<N>
   Если lint вернул project.grace3-detected — выполни doubled-graph migrate apply --repo . и повтори шаги 1–3.
   Если grace_engine.upgrade_required = true — npm install -g @osovv/grace-cli@4.2.1 и повтори setup.
 
+Шаг 4a. Context gate (обязательно):
+  grep -nE "not specified|unknown|Migrated project|Describe the primary|replace with the real product statement|Keep the project governed|Existing project maintainers|Legacy GRACE 3 documents stay in place|No operational constraints were declared|Users were not described|Restore the product intent|Not configured yet" .grace/context/*.xml
+  doubled-graph migrate check --repo .   (context_gaps = [])
+  Находки вне <LegacySource> исправляй по шагу 0; TestingStack-заглушка блокирует шаг 2.
+
 Шаг 5. Отчёт в фиксированном формате:
   MODULE_MAP: <N дополнено, K NONE/CONFIG>
   V-<M>:      <N заполнено и прогоняется, K без команды>

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "doubled-graph"
-version = "2.0.0"
+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.0 → 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.0 → 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.0 → doubled_graph-2.0.2}/src/doubled_graph/graphs/declared.py

@@ -61,6 +61,11 @@ class DeclaredModule:
     paths: list[str] = field(default_factory=list)
     exports: list[str] = field(default_factory=list)
     crosslinks: list[str] = field(default_factory=list)
+    #: GRACE 3 declared these as attributes; losing them silently rewrites
+    #: module identity/status during migration, so keep them.
+    name: str = ""
+    status: str = ""
+    type: str = ""
 
 
 @dataclass
@@ -165,20 +170,66 @@ def _load_grace4(root: Path, scan_files: bool) -> DeclaredGraph:
 # ---------------------------------------------------------------------------
 
 
+def _read_xml_text(path: Path) -> str:
+    """Read a legacy XML file whatever its encoding (UTF-8/UTF-16/BOM).
+
+    GRACE 3 projects were written by whatever editor the team used; a UTF-16
+    document is legal XML and must not abort a migration with a traceback.
+    """
+    raw = path.read_bytes()
+    for encoding in ("utf-8-sig", "utf-16", "utf-32", "cp1251"):
+        try:
+            return raw.decode(encoding)
+        except (UnicodeDecodeError, UnicodeError, LookupError):
+            continue
+    return raw.decode("utf-8", errors="replace")
+
+
+def _strip_namespaces(root: ET.Element) -> ET.Element:
+    """Drop ``{namespace}`` prefixes so tag matching works on namespaced XML.
+
+    Legacy documents occasionally declare a default ``xmlns``; ElementTree then
+    reports tags as ``{urn}M-AUTH`` and every ``^M-`` regex misses, which
+    silently produced a zero-module migration.
+    """
+    for element in root.iter():
+        if isinstance(element.tag, str) and "}" in element.tag:
+            element.tag = element.tag.rsplit("}", 1)[-1]
+        for key in list(element.attrib):
+            if "}" in key:
+                element.attrib[key.rsplit("}", 1)[-1]] = element.attrib.pop(key)
+    return root
+
+
+def _attribute(element: ET.Element, *names: str) -> str:
+    """Attribute value by any of ``names``, case-insensitively."""
+    for key, value in element.attrib.items():
+        if key.lower() in {name.lower() for name in names}:
+            text = (value or "").strip()
+            if text:
+                return text
+    return ""
+
+
+def _normalize_path(value: str) -> str:
+    """Store paths in a single portable form (forward slashes)."""
+    return value.replace("\\", "/").strip()
+
+
 def _safe_parse(path: Path) -> tuple[ET.Element | None, str]:
     """Parse XML, escaping bare ``&`` on retry.  Returns (root, error_msg)."""
     if not path.exists():
         return None, ""
-    raw = path.read_text(encoding="utf-8")
+    raw = _read_xml_text(path)
     try:
-        return ET.fromstring(raw), ""
+        return _strip_namespaces(ET.fromstring(raw)), ""
     except ET.ParseError:
         pass
     sanitized = _BARE_AMP.sub("&", raw)
     if sanitized == raw:
         return None, f"XML parse error in {path.name}"
     try:
-        return ET.fromstring(sanitized), ""
+        return _strip_namespaces(ET.fromstring(sanitized)), ""
     except ET.ParseError as exc:
         return None, f"XML parse error in {path.name}: {exc}"
 
@@ -215,12 +266,16 @@ def _merge_dev_plan_module(graph: DeclaredGraph, mod: ET.Element) -> None:
     if purpose and not existing.purpose:
         existing.purpose = purpose
 
+    existing.name = existing.name or _attribute(mod, "NAME", "Name")
+    existing.status = existing.status or _attribute(mod, "STATUS", "Status")
+    existing.type = existing.type or _attribute(mod, "TYPE", "Type")
+
     for src in mod.findall("target/source"):
         if src.text:
-            _append_unique(existing.paths, src.text.strip())
+            _append_unique(existing.paths, _normalize_path(src.text))
     for tst in mod.findall("target/tests"):
         if tst.text:
-            _append_unique(existing.paths, tst.text.strip())
+            _append_unique(existing.paths, _normalize_path(tst.text))
 
     for el in mod.findall("interface/*"):
         name = _export_name(el.tag or "")
@@ -238,9 +293,13 @@ def _merge_kg_module(graph: DeclaredGraph, mod: ET.Element) -> None:
     if purpose and not existing.purpose:
         existing.purpose = purpose
 
+    existing.name = existing.name or _attribute(mod, "NAME", "Name")
+    existing.status = existing.status or _attribute(mod, "STATUS", "Status")
+    existing.type = existing.type or _attribute(mod, "TYPE", "Type")
+
     for el in mod.findall("path"):
         if el.text:
-            _append_unique(existing.paths, el.text.strip())
+            _append_unique(existing.paths, _normalize_path(el.text))
 
     for el in mod.findall("annotations/*"):
         name = _export_name(el.tag or "")
@@ -282,8 +341,8 @@ def _load_legacy(repo_path: Path) -> DeclaredGraph:
         for mod in _iter_module_tags(root):
             _merge_kg_module(graph, mod)
         for cl in root.iter("CrossLink"):
-            src_id = cl.get("from") or ""
-            tgt_id = cl.get("to") or ""
+            src_id = _attribute(cl, "from", "source", "src")
+            tgt_id = _attribute(cl, "to", "target", "dst")
             if not src_id or not tgt_id:
                 continue
             mod = graph.modules.get(src_id)

{doubled_graph-2.0.0 → 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.0 → 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")