platformforge 0.2.0__tar.gz → 0.2.2__tar.gz

{platformforge-0.2.0 → platformforge-0.2.2}/CHANGELOG.md

@@ -1,6 +1,28 @@
 # CHANGELOG
 
 All notable changes. Format: wave/feature, the "why", key commits.
+## [0.2.2] - 2026-10-29
+
+### Fixed
+
+- `_forgecontext` v1.3.3 + `_installkit` v1.0.3 (vendored): `repair_context`
+  reports malformed capability files per-file instead of crashing;
+  context/install locks carry a unique ownership token; poisoned journals
+  quarantine instead of wedging later ops; asset/ledger paths are
+  validated before disk writes (`FORGE-INSTALL-UNSAFE-PATH`);
+  `_atomic_write` preserves file modes.
+- A `BLOCKED` check on the mandatory context-registry component now marks
+  the receipt `failed` (nonzero exit) — on install AND on both uninstall
+  paths.
+
+## [0.2.1] - 2026-10-22
+
+### Fixed
+
+- `_forgecontext` v1.3.2: non-UTF-8 consumer docs (AGENTS.md / CLAUDE.md /
+  AGENT_PROTOCOL.md) now refuse with named `FORGE-CONTEXT-CONFLICT` on
+  install and uninstall — never a bare `UnicodeDecodeError` mid-write.
+
 ## [0.2.0] - 2026-10-22
 
 ### Added
@@ -12,7 +34,7 @@ All notable changes. Format: wave/feature, the "why", key commits.
 ### Fixed
 
 - `_txn_restore` journal path validation; interrupt-safe rollback;
-  stale-lock `created_at` fallback (Windows); vendored `_installkit` v1.0.1 +
+  stale-lock `created_at` fallback (Windows); vendored `_installkit` v1.0.2 +
   `forge_bootstrap` v1.1.1 security backports (userinfo redaction, argv trim,
   empty-stdout smoke).
 
@@ -50,6 +72,7 @@ All notable changes. Format: wave/feature, the "why", key commits.
 - Portal vendored 2.1 final (Cycles 0-6)
 
 ## [Unreleased]
+
 ## [0.1.6] - 2026-10-21
 
 ### Changed

{platformforge-0.2.0 → platformforge-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: platformforge
-Version: 0.2.0
+Version: 0.2.2
 Summary: Agentic Platform Engineering intelligence platform — deterministic, offline-first, evidence-first
 Project-URL: Homepage, https://github.com/EdgarSocrates98/platform-forge
 Project-URL: Repository, https://github.com/EdgarSocrates98/platform-forge

{platformforge-0.2.0 → platformforge-0.2.2}/docs/audits/FORGE_CONTEXT_FINAL_HOMOLOGATION.md

@@ -294,3 +294,27 @@ grep register_installation platformforge/install/service.py → (vazio — P0-3
 grep -c 'def test_' tests/test_{install_lifecycle,wheel_isolation,
   evals_surface,discovery_ops}.py               → 31/1/21/4
 ```
+
+## Pós-release — evidência de publicação (2026-10-23 UTC)
+
+| Item | Estado | Evidência |
+|---|---|---|
+| Tag | CRIADA | `v0.2.0` no merge commit da release PR |
+| GitHub Release | CRIADO | `gh release view v0.2.0` |
+| PyPI | PUBLICADO | `pypi.org/pypi/platformforge/json` → `0.2.0` |
+| Wheel smoke (venv limpo) | PASS | `pip install platformforge==0.2.0` + `platformforge --version` → `0.2.0` |
+
+Notas: installkit canônico 1.0.2 (`_SOURCE_SHA256 a15ca78bb34a0109`), bootstrap 1.1.1 — propagados aos 7 carriers; `vendor.py --check` CLEAN ×7. `data-sentinel-forge`: **deferido pelo dono** (outro CLI evoluindo).
+
+## Pós-release hotfix — evidência de publicação patch (2026-10-23 UTC)
+
+Patch motivado pelo review: `UnicodeDecodeError` não-tipado em docs de
+consumidor não-UTF-8 quebrava install **e** uninstall.
+
+| Item | Estado | Evidência |
+|---|---|---|
+| Tag | CRIADA | `v0.2.1` |
+| GitHub Release | CRIADO | `gh release view v0.2.1` |
+| PyPI | PUBLICADO | `pypi.org/pypi/platformforge/json` → `0.2.1` |
+| Wheel smoke | PASS | wheel publicado contém `_forgecontext` v1.3.2 (`_read_doc` presente) — verificado via `pip download platformforge==0.2.1` |
+| Regressão | PASS | teste cp1252 `AGENTS.md` → `FORGE-CONTEXT-CONFLICT` nomeado em install e uninstall |

{platformforge-0.2.0 → platformforge-0.2.2}/docs/economy-parity/VALIDATION-RECEIPT.json

@@ -11,42 +11,42 @@
     "economy-agentic": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_agents_waste.py tests/test_economy_evals.py -k uniqueness or debate or duplication or fanout or waste or stagnant",
-      "seconds": 3.07
+      "seconds": 3.31
     },
     "economy-budget": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_contracts.py -k budget or limit or protected or dimension",
-      "seconds": 2.34
+      "seconds": 2.54
     },
     "economy-cache": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_cache.py",
-      "seconds": 2.55
+      "seconds": 12.07
     },
     "economy-closure": {
       "ok": true,
       "reproduce": "python -c import sys\nfrom pathlib import Path\nreq = {'docs/economy-parity/FINAL-REPORT.md':\n         ['validated_sha', 'remote_ci', 'known gap'],\n       'docs/economy-parity/FINAL-MATRIX.md':\n         ['validated', 'externally-unverified'],\n       'docs/economy-parity/ECONOMY-BENCHMARKS.md':\n         ['Control Plane Overhead', 'End-to-End'],\n       'docs/economy/ROUTING.md':\n         ['decide', 'advisory'],\n       'docs/economy-parity/POLISH-BASELINE.md': ['drift']}\nbad = []\nfor f, needles in req.items():\n    p = Path(f)\n    if not p.is_file(): bad.append(('missing', f)); continue\n    txt = p.read_text()\n    for n in needles:\n        if n not in txt: bad.append((f, n))\nm = Path('docs/economy-parity/FINAL-MATRIX.md').read_text()\nif '\\n' + '|' in m and ' fully-production' in m:\n    bad.append(('matrix', 'overclaimed status'))\nif bad: print(bad); sys.exit(1)\nprint('closure docs coherent')\n && pytest -q tests/test_economy_closure.py",
-      "seconds": 3.55
+      "seconds": 3.49
     },
     "economy-context": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_gateway.py -k TestGateway or TestLazy or TestRole or Suff",
-      "seconds": 2.76
+      "seconds": 2.62
     },
     "economy-contracts": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_contracts.py tests/test_economy_v2.py",
-      "seconds": 4.01
+      "seconds": 3.92
     },
     "economy-evals": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_evals.py",
-      "seconds": 3.28
+      "seconds": 3.17
     },
     "economy-qpt": {
       "ok": true,
       "reproduce": "pytest -q tests/test_qpt_v2.py tests/test_economy_fleet_qpt.py",
-      "seconds": 8.48
+      "seconds": 8.57
     },
     "economy-receipt": {
       "ok": true,
@@ -56,30 +56,30 @@
     "economy-reconcile": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_gateway.py tests/test_economy_evals.py -k reconcil or mismatch or unobserved",
-      "seconds": 2.83
+      "seconds": 2.87
     },
     "economy-resume": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_gateway.py -k resume or checkpoint",
-      "seconds": 2.43
+      "seconds": 2.62
     },
     "economy-routing": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_evals.py -k routing or profile or champion or simple_task",
-      "seconds": 2.77
+      "seconds": 2.95
     },
     "economy-surface": {
       "ok": true,
       "reproduce": "python -c import subprocess, sys\ncmds = [\n ['platformforge','economy','doctor'],\n ['platformforge','economy','checkpoint','--run-id','gate',\n  '--spent','{\"tokens\":1}'],\n ['platformforge','economy','resume','--run-id','gate'],\n ['platformforge','economy','reconcile',\n  '--planned','{\"tokens\":1}','--observed','{\"tokens\":2}'],\n ['platformforge','economy','explain','--run-id','gate'],\n ['platformforge','cache','stats'],\n ['platformforge','cache','gc'],\n ['platformforge','context','capsule','--task','t',\n  '--facts','[{\"fact_id\":\"f\"}]'],\n ['platformforge','context','gc'],\n ['platformforge','routing','explain','--signal','{}'],\n ['platformforge','routing','compare',\n  '--champion','{}','--challenger','{}'],\n]\nfor c in cmds:\n    r = subprocess.run(c, capture_output=True)\n    if r.returncode not in (0, 2):\n        print('FAIL', c, r.returncode, r.stderr[-300:])\n        sys.exit(1)\nprint('all economy verbs respond')\n",
-      "seconds": 15.65
+      "seconds": 16.02
     },
     "economy-verification": {
       "ok": true,
       "reproduce": "pytest -q tests/test_economy_pricing_verify.py",
-      "seconds": 2.8
+      "seconds": 2.87
     }
   },
-  "generated_at": "2026-10-22T22:19:21Z",
+  "generated_at": "2026-10-23T04:16:58Z",
   "kind": "platformforge/economy-validation-receipt/1",
   "known_gaps": [
     "real provider pricing catalog not bundled (declared-rates engine only, by design)",
@@ -93,7 +93,7 @@
   "remote_ci": "not independently verified",
   "schema": "platformforge/economy-validation-receipt/v1",
   "spec": "prompt_evo_economy.md",
-  "validated_sha": "ccbe938e48d9d614cceab670acb5eb6a2577ca10",
+  "validated_sha": "b3b4558bedfcfd434034af1573c3129128cca12a",
   "validator": "scripts/validate.py",
   "validator_version": "economy-validation-receipt/v1",
   "verdict": "validated"

{platformforge-0.2.0 → platformforge-0.2.2}/platformforge/__init__.py

@@ -4,4 +4,4 @@ Deterministic-first, offline-first, evidence-first. The core never imports
 LLM SDKs, cloud SDKs, or MCP — those live behind optional adapters.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{platformforge-0.2.0 → platformforge-0.2.2}/platformforge/_forgecontext.py

@@ -100,6 +100,7 @@ import json
 import os
 import re
 import shutil
+import stat
 import sys
 import tempfile
 import time
@@ -107,10 +108,10 @@ from collections.abc import Iterable, Mapping
 from pathlib import Path, PurePosixPath
 from typing import Any
 
-_FORGECONTEXT_VERSION = "1.3.1"
+_FORGECONTEXT_VERSION = "1.3.3"
 # Filled by the vendor step (scripts/installkit/vendor.py) — the sha256 of
 # the canonical source body, so drift checks can compare vendored copies.
-_SOURCE_SHA256 = "e72e93eab21ade74"
+_SOURCE_SHA256 = "18ebe75c6281a3f5"
 
 SCHEMA_MANIFEST = "forge/context/v1"
 SCHEMA_REGISTRY = "forge/context-registry/v1"
@@ -241,12 +242,17 @@ def _load_json(path: Path, default: Any = None) -> Any:
 
 def _atomic_write(path: Path, data: bytes) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
+    # mkstemp lands 0600 — preserve an existing file's mode so a managed
+    # merge never downgrades the user's permissions.
+    mode = stat.S_IMODE(path.stat().st_mode) if path.is_file() else None
     fd, tmp = tempfile.mkstemp(prefix=path.name, dir=str(path.parent))
     try:
         with os.fdopen(fd, "wb") as fh:
             fh.write(data)
             fh.flush()
             os.fsync(fh.fileno())
+        if mode is not None:
+            os.chmod(tmp, mode)
         os.replace(tmp, path)
     finally:
         if os.path.exists(tmp):
@@ -269,15 +275,18 @@ def _pid_alive(pid: int) -> bool | None:
 
 
 class _Lock:
-    """O_EXCL lockfile carrying ``{pid, created_at}``. Stale locks — dead
-    holder or older than ``stale_after_s`` — are reclaimed once so an
-    interrupted op never bricks the registry."""
+    """O_EXCL lockfile carrying ``{pid, created_at, token}``. Stale locks —
+    dead holder or older than ``stale_after_s`` — are reclaimed once so an
+    interrupted op never bricks the registry. The token guards release:
+    a file reclaimed or rewritten by another claimant is never unlinked
+    by ``__exit__``."""
 
     def __init__(self, lock: Path, stale_after_s: float = 900.0) -> None:
         self._lock = lock
         self._stale = stale_after_s
         self.held = False
         self.recovered = False
+        self._token: str | None = None
 
     def __enter__(self) -> _Lock:
         try:
@@ -294,12 +303,30 @@ class _Lock:
                     E_LOCKED, f"context lock at {self._lock} could not be reclaimed"
                 ) from exc
             self.recovered = True
-            self._create()
+            try:
+                self._create()
+            except FileExistsError:
+                raise LockError(
+                    E_LOCKED,
+                    f"context lock at {self._lock} lost to a concurrent reclaimer",
+                ) from None
             return self
 
     def _create(self) -> None:
+        self._token = hashlib.sha256(
+            f"{os.getpid()}:{time.time_ns()}:{self._lock}".encode()
+        ).hexdigest()[:24]
         fd = os.open(str(self._lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
-        os.write(fd, _json_bytes({"pid": os.getpid(), "created_at": _utc_now()}))
+        os.write(
+            fd,
+            _json_bytes(
+                {
+                    "pid": os.getpid(),
+                    "created_at": _utc_now(),
+                    "token": self._token,
+                }
+            ),
+        )
         os.close(fd)
         self.held = True
 
@@ -331,9 +358,16 @@ class _Lock:
         return age > self._stale
 
     def __exit__(self, *exc: object) -> None:
-        if self.held:
-            with contextlib.suppress(OSError):
-                self._lock.unlink()
+        try:
+            if self.held:
+                # Only release a lock that still carries OUR token — a
+                # reclaimed/stolen file belongs to its current claimant.
+                doc = _load_json(self._lock)
+                if isinstance(doc, dict) and doc.get("token") == self._token:
+                    with contextlib.suppress(OSError):
+                        self._lock.unlink()
+        finally:
+            self.held = False
 
 
 def acquire_lock(ctx_dir: Path) -> _Lock:
@@ -1417,7 +1451,23 @@ def _qualified_ids(manifest: Mapping[str, Any]) -> list[str]:
 def _entry_from_manifest(
     manifest: dict[str, Any], cap_sha: str, prev: dict[str, Any] | None, now: str
 ) -> dict[str, Any]:
-    inst = manifest["installed"]
+    fid = str(manifest.get("forge_id") or "?")
+    inst = manifest.get("installed")
+    if not isinstance(inst, Mapping):
+        raise ContextError(
+            E_SCHEMA,
+            f"{_capability_rel(fid)}: missing required 'installed' — "
+            "repair or remove the capability file",
+        )
+    missing = [
+        k for k in ("forge_id", "name", "version", "state", "recorded_by") if k not in manifest
+    ]
+    if missing:
+        raise ContextError(
+            E_SCHEMA,
+            f"{_capability_rel(fid)}: missing required keys {missing} — "
+            "repair or remove the capability file",
+        )
     return {
         "forge_id": manifest["forge_id"],
         "owner": manifest["forge_id"],
@@ -1535,31 +1585,44 @@ def _recover_journal(ctx: Path, root: Path) -> dict[str, Any] | None:
     recovered: dict[str, Any] | None = None
     now = _utc_now()
     if isinstance(journal, dict):
-        op = journal.get("op")
-        if op == "register" and isinstance(journal.get("manifest"), dict):
-            if not validate_manifest(journal["manifest"]):
-                _apply_register(ctx, root, journal["manifest"], now)
-                recovered = {"op": "register", "forge_id": journal["manifest"]["forge_id"]}
-        elif op == "unregister" and isinstance(journal.get("forge_id"), str):
-            _apply_unregister(ctx, root, journal["forge_id"], now)
-            recovered = {"op": "unregister", "forge_id": journal["forge_id"]}
-        elif op == "install" and isinstance(journal.get("manifest"), dict):
-            if not validate_manifest(journal["manifest"]):
-                _apply_register(ctx, root, journal["manifest"], now)
-                if journal.get("docs", True):
-                    _docs_install_apply(
-                        root, journal["manifest"], tuple(journal.get("legacy_tags") or ())
-                    )
-                recovered = {
-                    "op": "install",
-                    "forge_id": journal["manifest"]["forge_id"],
-                }
-        elif op == "uninstall" and isinstance(journal.get("forge_id"), str):
-            _apply_unregister(ctx, root, journal["forge_id"], now)
-            _docs_uninstall_apply(
-                root, journal["forge_id"], tuple(journal.get("legacy_tags") or ())
-            )
-            recovered = {"op": "uninstall", "forge_id": journal["forge_id"]}
+        try:
+            op = journal.get("op")
+            if op == "register" and isinstance(journal.get("manifest"), dict):
+                if not validate_manifest(journal["manifest"]):
+                    _apply_register(ctx, root, journal["manifest"], now)
+                    recovered = {"op": "register", "forge_id": journal["manifest"]["forge_id"]}
+            elif op == "unregister" and isinstance(journal.get("forge_id"), str):
+                _apply_unregister(ctx, root, journal["forge_id"], now)
+                recovered = {"op": "unregister", "forge_id": journal["forge_id"]}
+            elif op == "install" and isinstance(journal.get("manifest"), dict):
+                if not validate_manifest(journal["manifest"]):
+                    _apply_register(ctx, root, journal["manifest"], now)
+                    if journal.get("docs", True):
+                        _docs_install_apply(
+                            root, journal["manifest"], tuple(journal.get("legacy_tags") or ())
+                        )
+                    recovered = {
+                        "op": "install",
+                        "forge_id": journal["manifest"]["forge_id"],
+                    }
+            elif op == "uninstall" and isinstance(journal.get("forge_id"), str):
+                _apply_unregister(ctx, root, journal["forge_id"], now)
+                _docs_uninstall_apply(
+                    root, journal["forge_id"], tuple(journal.get("legacy_tags") or ())
+                )
+                recovered = {"op": "uninstall", "forge_id": journal["forge_id"]}
+        except ContextError as exc:
+            # A poisoned journal must not wedge every later op: the redo hit a
+            # conflict that post-dates the crash (foreign doc, non-UTF-8 file).
+            # Quarantine the intent — evidence preserved — and report it,
+            # instead of failing forever on the same journal.
+            _quarantine(jpath, now.replace(":", ""))
+            _txn_drop(ctx)
+            return {
+                "op": str(journal.get("op") or "?"),
+                "quarantined": True,
+                "error": f"{exc.kind}: {exc.detail}",
+            }
         if recovered is None:
             _quarantine(jpath, now.replace(":", ""))
             _txn_drop(ctx)
@@ -1685,8 +1748,16 @@ def repair_context(root: Path | str) -> dict[str, Any]:
         now = _utc_now()
         previous = {e["forge_id"]: e for e in reg["forges"]}
         entries = []
+        invalid: list[dict[str, Any]] = []
         for fid in sorted(manifests):
             doc = manifests[fid]
+            # A capability file that fails schema validation is reported and
+            # kept out of the rebuilt registry — never an untyped crash on
+            # the one path meant to converge a broken context.
+            problems = validate_manifest(doc)
+            if problems:
+                invalid.append({"forge_id": fid, "problems": problems[:5]})
+                continue
             cap_sha = _sha_file(ctx / CAPABILITIES_DIR / f"{fid}.json")
             entries.append(_entry_from_manifest(doc, cap_sha, previous.get(fid), now))
         reg["forges"] = entries
@@ -1698,7 +1769,8 @@ def repair_context(root: Path | str) -> dict[str, Any]:
         # foreign-installer content is never ours to remove.
     return {
         "status": "repaired",
-        "forges": sorted(manifests),
+        "forges": sorted(e["forge_id"] for e in entries),
+        "invalid": invalid,
         "recovered": recovered,
         "notes": notes,
         "written": written,
@@ -2126,9 +2198,23 @@ def _is_our_protocol(text: str) -> bool:
     return text.startswith(PROTOCOL_SENTINEL)
 
 
+def _read_doc(path: Path) -> str:
+    """Read a consumer doc as UTF-8 — a file that does not decode is a
+    named refusal, never an untyped internal error (conflicts precede
+    writes per §9.2; errors are typed per §13.1)."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        raise ContextError(
+            E_CONFLICT,
+            f"{path.name}: not valid UTF-8 — convert the file to UTF-8 or "
+            "remove it, then re-run",
+        ) from None
+
+
 def _write_doc(path: Path, text: str, written: list[str], kept: list[str]) -> None:
     rel = path.name
-    old = path.read_text(encoding="utf-8") if path.exists() else None
+    old = _read_doc(path) if path.exists() else None
     if old == text:
         kept.append(rel)
         return
@@ -2143,7 +2229,7 @@ def _sync_protocol(root: Path, written: list[str], notes: list[str]) -> None:
     manifests = _load_manifests(context_dir(root))
     if not manifests:
         if path.exists():
-            text = path.read_text(encoding="utf-8")
+            text = _read_doc(path)
             if _is_our_protocol(text):
                 path.unlink()
                 written.append(f"{PROTOCOL_NAME} (removed — last forge)")
@@ -2157,14 +2243,14 @@ def _sync_protocol(root: Path, written: list[str], notes: list[str]) -> None:
     reg = load_registry(root) or {}
     doc = protocol_document(reg, manifests)
     if path.exists():
-        cur = path.read_text(encoding="utf-8")
+        cur = _read_doc(path)
         if not _is_our_protocol(cur):
             raise ContextError(
                 E_CONFLICT,
                 f"{PROTOCOL_NAME} exists and is not forge-managed — rename "
                 "it or remove it, then re-run",
             )
-    old = path.read_text(encoding="utf-8") if path.exists() else None
+    old = _read_doc(path) if path.exists() else None
     if old != doc:
         _atomic_write(path, doc.encode("utf-8"))
         written.append(PROTOCOL_NAME)
@@ -2184,7 +2270,7 @@ def _sync_marked_file(
     ``preamble`` when absent. ``blocks`` is ordered (ecosystem, then the
     forge's)."""
     path = root / name
-    text = path.read_text(encoding="utf-8") if path.exists() else preamble
+    text = _read_doc(path) if path.exists() else preamble
     text, removed = strip_legacy_blocks(text, legacy_tags, name=name)
     removed_legacy.extend(removed)
     for tag, body in blocks:
@@ -2209,7 +2295,7 @@ def _teardown_marked_file(
     path = root / name
     if not path.exists():
         return
-    text = path.read_text(encoding="utf-8")
+    text = _read_doc(path)
     text, removed = strip_legacy_blocks(text, legacy_tags, name=name)
     removed_legacy.extend(removed)
     text = remove_managed_block(text, f"forge:{forge_id}", name=name)
@@ -2248,7 +2334,7 @@ def _protocol_conflict_check(root: Path) -> None:
     that exists and is not ours."""
     path = root / PROTOCOL_NAME
     if path.exists():
-        text = path.read_text(encoding="utf-8")
+        text = _read_doc(path)
         if not _is_our_protocol(text):
             raise ContextError(
                 E_CONFLICT,
@@ -2265,7 +2351,7 @@ def _docs_install_conflicts(
     (transaction §9.2 step 5: conflict detection precedes backup)."""
     for name, preamble, blocks in _install_block_plan(manifest):
         path = root / name
-        text = path.read_text(encoding="utf-8") if path.exists() else preamble
+        text = _read_doc(path) if path.exists() else preamble
         text, _ = strip_legacy_blocks(text, legacy_tags, name=name)
         for tag, body in blocks:
             text = apply_managed_block(text, tag, body, name=name)
@@ -2282,7 +2368,7 @@ def _docs_uninstall_conflicts(root: Path, forge_id: str, legacy_tags: Iterable[s
         path = root / name
         if not path.exists():
             continue
-        text = path.read_text(encoding="utf-8")
+        text = _read_doc(path)
         text, _ = strip_legacy_blocks(text, legacy_tags, name=name)
         text = remove_managed_block(text, f"forge:{forge_id}", name=name)
         if not keep_shared:
@@ -2566,7 +2652,7 @@ def _verify_install(root: Path, forge_id: str, *, docs: bool) -> list[str]:
     verified.append("manifest")
     if docs:
         agents = root / AGENTS_NAME
-        text = agents.read_text(encoding="utf-8") if agents.exists() else ""
+        text = _read_doc(agents) if agents.exists() else ""
         if f"forge:{forge_id}:begin" not in text:
             raise ContextError(
                 E_SCHEMA, f"verify: {AGENTS_NAME} lacks the forge:{forge_id} block"