docs(release): prepare 0.27.0 — curated changelog, rag/map sweep, concat rebuild script (#662)

2026-08-03 07:23:24 +02:00 · 2026-07-23 11:33:02 +02:00
parent d8841279a8
commit dd4c3c3ed0
26 changed files with 501 additions and 81 deletions
@@ -0,0 +1,102 @@
+"""Rebuild docs/map/_complete_map.md from _front.md + the per-slice maps.
+
+The complete map is a literal concatenation: the front matter, then each
+slice's body (everything from its "## Purpose" heading on — any per-file
+title block above it is stripped) in the canonical order below, one blank
+line between sections. It has drifted behind its own sources by hand-sync
+three times; this script makes the rebuild mechanical.
+
+Usage:
+    python scripts/rebuild_map_concat.py           # rewrite the concat
+    python scripts/rebuild_map_concat.py --check   # exit 1 if drifted
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+MAP_DIR = Path(__file__).resolve().parent.parent / "docs" / "map"
+
+# The committed artifact's own section order (recovered from the file; not
+# alphabetical and not the ToC order — keep appending new slices here).
+SLICE_ORDER = [
+    "a2a-audit-journal-permissions",
+    "deployment-tooling",
+    "engines-heal-ciwatch-depupdate",
+    "foundation-batch-sequencing",
+    "foundation-conventions-identity",
+    "foundation-lifecycle",
+    "foundation-policy-misc",
+    "gateway-support",
+    "intake-secretary",
+    "notification",
+    "orchestrator",
+    "org-memory-playbooks",
+    "pr-gate-review",
+    "prompts-roles-taxonomy",
+    "release-manager",
+    "runtime-providers",
+    "vault",
+    "video-engine",
+    "models",
+    "db-migrations",
+    "api-core-websocket",
+    "api-routes-schemas",
+    "mcp-servers",
+    "choreographer",
+    "task-service",
+    "worksession-git",
+    "workspace",
+    "support-services",
+    "review-findings",
+    "metrics-observability",
+    "conventions-service-validator",
+    "product-strategy-research-pitch",
+    "engine-docs-sync",
+    "panel",
+    "tests",
+]
+
+
+def _slice_body(path: Path) -> str:
+    text = path.read_text()
+    idx = text.find("## Purpose")
+    if idx < 0:
+        raise SystemExit(f"{path.name}: no '## Purpose' heading — cannot concat")
+    return text[idx:].rstrip("\n") + "\n"
+
+
+def build() -> str:
+    on_disk = {p.stem for p in MAP_DIR.glob("*.md") if not p.name.startswith("_")}
+    listed = set(SLICE_ORDER)
+    if on_disk != listed:
+        raise SystemExit(
+            "slice set drifted — missing from SLICE_ORDER: "
+            f"{sorted(on_disk - listed)}, listed but absent: {sorted(listed - on_disk)}"
+        )
+    front = (MAP_DIR / "_front.md").read_text()
+    return front + "".join(
+        "\n" + _slice_body(MAP_DIR / f"{name}.md") for name in SLICE_ORDER
+    )
+
+
+def main() -> int:
+    target = MAP_DIR / "_complete_map.md"
+    built = build()
+    if "--check" in sys.argv[1:]:
+        if target.read_text() != built:
+            print(
+                "_complete_map.md is behind its sources — "
+                "run scripts/rebuild_map_concat.py"
+            )
+            return 1
+        print("_complete_map.md is in sync.")
+        return 0
+    target.write_text(built)
+    print(f"wrote {target} ({len(built)} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())