2026.9.28.2: one resolver for the runtime beside a Windows program, header tracking on every host, one statement per fact, conditional tables by specificity

.agents/docs/README.md

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-313 records.
+315 records.
 
 ## By subject
 
@@ -30,6 +30,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### design
 
+- [An ecosystem design for mcpp and xlings: one authority per fact, and the work that follows from it](2026-09-28-ecosystem-design-and-optimisation-plan.md) — active
 - [The compile database, `emit build-database`, and #701/#702: triage against the specifications, and one design](2026-09-26-compile-database-and-issue-699-design.md) — landed
 - [Issues #693 to #696: triage against mcpp's contracts, and one repair plan](2026-09-25-issues-693-696-triage-and-repair-plan.md) — landed
 - [Workspace inheritance, flag scoping and the published form: a unified repair plan (#690)](2026-09-25-issue-690-workspace-build-inheritance-consistency.md) — landed
@@ -68,6 +69,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### review
 
+- [Two days of mcpp and xlings: a review of what merged, what is known, and what is open](2026-09-28-ecosystem-review-of-two-days-of-mcpp-and-xlings.md) — active
 - [#690: self-review before release, engine and ecosystem](2026-09-25-issue-690-self-review.md) — landed
 - [本轮生态级自审](2026-09-20-wave-self-review.md) — active
 - [#674 设计方案评审：`-include unistd.h` 在 Windows + `presents = "posix"` 上的可行性](2026-09-20-issue-674-design-review.md) — active
@@ -104,6 +106,8 @@ Records that declare one. Everything else is listed by date below.
 
 ### 2026-09
 
+- [Two days of mcpp and xlings: a review of what merged, what is known, and what is open](2026-09-28-ecosystem-review-of-two-days-of-mcpp-and-xlings.md) — active
+- [An ecosystem design for mcpp and xlings: one authority per fact, and the work that follows from it](2026-09-28-ecosystem-design-and-optimisation-plan.md) — active
 - [Eight reports after 2026.9.27.1: implementation plan](2026-09-27-eight-reports-implementation-plan.md) — active
 - [Eight reports after 2026.9.27.1: what each one is, where it belongs, and one optimisation plan](2026-09-27-eight-reports-by-home-and-one-optimisation-plan.md) — active
 - [The compile database, `emit build-database`, and #701/#702: triage against the specifications, and one design](2026-09-26-compile-database-and-issue-699-design.md) — landed

.github/actions/bootstrap-mcpp/action.yml

@@ -25,7 +25,7 @@ inputs:
     # `package.name`, so one of the two was simply unreachable — and which one
     # depended on the machine, which is why CI failed on `compat:lua` on
     # Windows and `mcpplibs.capi:lua` on Linux. Never pin below that.
-    default: '2026.9.28.1'
+    default: '2026.9.28.2'
   cache-target:
     description: also restore/save target/ (build artifacts + BMIs)
     required: false

.github/actions/setup-macos-llvm/action.yml

@@ -15,7 +15,7 @@ inputs:
     # Floor imposed by the index, not a routine bump — see
     # .github/actions/bootstrap-mcpp/action.yml for why 0.4.69 is required
     # (two packages named `lua` in one repo need openxlings/xlings#381).
-    default: '2026.9.28.1'
+    default: '2026.9.28.2'
   image:
     description: >
       The runner label the job runs on (macos-15, xcode-27). It is part of the

.github/pull_request_template.md

@@ -0,0 +1,38 @@
+## Summary
+
+<!-- What changes, and why, in declarative sentences. Link the issues it closes. -->
+
+## Criteria
+
+<!-- For each change, the test that fails before it and passes after it, and
+     where that test runs (host, CI job). A criterion that did not run is not
+     a pass: say which ones are left to CI and why. -->
+
+## Intersections
+
+<!-- A release regression of 2026.9.27.1 had one shape three times: a new rule
+     or feature crossed an existing invariant, and no test sat at the crossing
+     (#725, #723, e2e 797). For each new gate, rule or feature in this change:
+
+     - which existing invariant does it cross?
+     - which test sits at that crossing?
+
+     Write "none" only after looking. -->
+
+| New rule or feature | Invariant it crosses | Test at the crossing |
+|---|---|---|
+|  |  |  |
+
+## Compatibility
+
+<!-- What an existing project, home or client observes after the upgrade:
+     changed output, a changed default, a full rebuild, a migration. -->
+
+## Checks before merging
+
+- [ ] `bash .github/tools/check_docs_style.sh`, `check_docs_structure.sh` and `check_version_pins.sh` pass.
+- [ ] `python3 .github/tools/check_workflow_assertions.py` passes (a step asserts what its name says).
+- [ ] No commit on the branch carries an attribution trailer:
+      `git log origin/main..HEAD -i --grep='Co-Authored-By'` prints nothing.
+- [ ] The squash merge is given an explicit subject and body, so GitHub does not
+      compose one from the branch's commits.

.github/release-canaries.toml

@@ -0,0 +1,60 @@
+# Release canaries (the 2026-09-28 ecosystem design, WS10).
+#
+# Real projects built with the candidate mcpp before a release is tagged:
+# release.yml runs .github/workflows/release-canaries.yml first, and a canary
+# that fails blocks the tag. A regression that only a real project shows --
+# 2026.9.27.1's vcpkg compiler detection on GalTranslPP (#726) -- is then read
+# before the release instead of after it.
+#
+# The candidate is built from the commit being released. A project's own pin
+# of mcpp (`workspace.mcpp` in its `.xlings.json`) is removed in the project's
+# checkout, so nothing installs the released mcpp in its place; nothing is
+# committed to the project, and no override mechanism is added to xlings.
+#
+# Each entry: `repo` and `ref` to check out, the runner `os`, a `timeout` in
+# minutes, the `commands` run in the checkout with `$MCPP` naming the
+# candidate (each must exit 0; a command whose output must also say something
+# pairs it with `expect`), and `cache` paths kept between runs.
+
+[[canary]]
+name     = "xlings"
+repo     = "openxlings/xlings"
+ref      = "main"
+os       = "ubuntu-24.04"
+timeout  = 60
+commands = [
+  "$MCPP build",
+  "$MCPP test",
+]
+
+[[canary]]
+name     = "mcppls"
+repo     = "Sunrisepeak/mcpp-language-server"
+ref      = "main"
+os       = "ubuntu-24.04"
+timeout  = 60
+commands = [
+  "$MCPP build",
+  "$MCPP build -p devtools",
+  "$MCPP test",
+]
+
+[[canary]]
+name     = "GalTranslPP"
+repo     = "Sunrisepeak/GalTranslPP"
+ref      = "build/mcpp-zero-setup"
+os       = "windows-2025"
+timeout  = 300
+submodules = true
+commands = [
+  "$MCPP build --workspace --profile fast-release",
+  "$MCPP run -p GPPCLI --profile fast-release < /dev/null",
+  "cd GPPCLI && $MCPP pack --format release --profile fast-release",
+  "cd GPPGUI && $MCPP pack --format release --profile fast-release",
+]
+expect = { "$MCPP run -p GPPCLI --profile fast-release < /dev/null" = "GalTransl++ CLI v" }
+cache = [
+  "~/AppData/Local/vcpkg/archives",
+  "~/AppData/Local/vcpkg/downloads",
+  "~/AppData/Local/vcpkg/registries",
+]

.github/tools/check_default_toolchain_docs.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""The documentation states the default toolchain the resolver picks on this
+host (the 2026-09-28 ecosystem design, WS8).
+
+WHY THIS EXISTS
+
+docs/01 and docs/20 state, in two languages, which toolchain a first run
+installs on each host. The review of 2026-09-28 found them stating llvm@20.1.7
+while the readings it had in hand said llvm@22.1.8, and nothing compared the
+two. The answer now has one authority, `pins::host_default_toolchain`, reported
+by `mcpp self env --format json` as `data.defaultToolchain`; this script reads
+that report on the host it runs on and checks the four statements of that
+host's row against it. Each CI host row runs it, so every row of the tables is
+checked on the machine it describes.
+
+Usage:
+    python3 .github/tools/check_default_toolchain_docs.py --mcpp <binary>
+    python3 .github/tools/check_default_toolchain_docs.py --spec gcc@16.1.0 --os Linux --arch x86_64 [--root DIR]
+The second form is for the fixture tests (tests/scripts/).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def normalise(text: str) -> str:
+    return re.sub(r"\s+", " ", text)
+
+
+def expected_phrases(spec: str, os_name: str, arch: str) -> dict[str, list[str]]:
+    """The statements of this host's row, per file, with `spec` in place."""
+    s = f"`{spec}`"
+    if os_name == "Linux":
+        if arch in ("x86_64", "amd64"):
+            return {
+                "docs/01-getting-started.md": [f"| Linux x86_64 | {s} |"],
+                "docs/zh/01-getting-started.md": [f"| Linux x86_64 | {s} |"],
+                "docs/20-toolchains.md": [f"- Linux x86_64 uses {s}"],
+                "docs/zh/20-toolchains.md": [f"- Linux x86_64 使用面向原生 glibc ABI 的 {s}"],
+            }
+        return {
+            "docs/01-getting-started.md": [f"| other Linux architectures | {s} |"],
+            "docs/zh/01-getting-started.md": [f"| 其它 Linux 架构 | {s} |"],
+            "docs/20-toolchains.md": [f"- Other Linux architectures use {s}"],
+            "docs/zh/20-toolchains.md": [f"- 其他 Linux 架构使用 {s}"],
+        }
+    if os_name == "Darwin":
+        return {
+            "docs/01-getting-started.md": [f"| macOS | {s} |"],
+            "docs/zh/01-getting-started.md": [f"| macOS | {s} |"],
+            "docs/20-toolchains.md": [f"- macOS uses {s}."],
+            "docs/zh/20-toolchains.md": [f"- macOS 使用 {s}。"],
+        }
+    if os_name.startswith(("Windows", "MINGW", "MSYS", "CYGWIN")):
+        if spec.startswith("gcc@"):
+            return {
+                "docs/01-getting-started.md": [f"| Windows without it | {s} for `x86_64-windows-gnu` |"],
+                "docs/zh/01-getting-started.md": [f"| 没有 MSVC 的 Windows | 面向 `x86_64-windows-gnu` 的 {s} |"],
+                "docs/20-toolchains.md": [f"Without usable MSVC, it uses {s} with target `x86_64-windows-gnu`"],
+                "docs/zh/20-toolchains.md": [f"没有可用 MSVC 时使用 {s}，target 为 `x86_64-windows-gnu`"],
+            }
+        return {
+            "docs/01-getting-started.md": [f"| Windows with usable MSVC | {s} |"],
+            "docs/zh/01-getting-started.md": [f"| 有可用 MSVC 的 Windows | {s} |"],
+            "docs/20-toolchains.md": [f"- Windows with a usable MSVC installation uses {s} for the MSVC ABI."],
+            "docs/zh/20-toolchains.md": [f"- Windows 上存在可用 MSVC 时使用面向 MSVC ABI 的 {s}"],
+        }
+    raise SystemExit(f"FAIL: no documented row for host {os_name} {arch}")
+
+
+def reported_default(mcpp: str) -> str:
+    out = subprocess.run([mcpp, "self", "env", "--format", "json"],
+                         capture_output=True, text=True, check=False)
+    if out.returncode != 0:
+        raise SystemExit(f"FAIL: `{mcpp} self env --format json` exited {out.returncode}: {out.stderr.strip()}")
+    data = json.loads(out.stdout).get("data", {})
+    spec = data.get("defaultToolchain", "")
+    if not spec:
+        raise SystemExit("FAIL: `self env --format json` reports no defaultToolchain")
+    return spec
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--mcpp")
+    ap.add_argument("--spec")
+    ap.add_argument("--os", default=platform.system())
+    ap.add_argument("--arch", default=platform.machine())
+    ap.add_argument("--root", default=".")
+    args = ap.parse_args()
+    if not args.spec and not args.mcpp:
+        ap.error("either --mcpp or --spec is required")
+    spec = args.spec or reported_default(args.mcpp)
+    root = Path(args.root)
+    problems = []
+    for rel, phrases in expected_phrases(spec, args.os, args.arch).items():
+        text = normalise((root / rel).read_text(encoding="utf-8"))
+        for phrase in phrases:
+            if normalise(phrase) not in text:
+                problems.append(f"{rel}: does not state `{phrase}`")
+    for p in problems:
+        print(f"FAIL: {p}")
+    print(f"defaultToolchain on {args.os} {args.arch}: {spec}; {len(problems)} problem(s)")
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/tools/check_function_sizes.sh

@@ -33,13 +33,11 @@
 # the caller runs that build first. check_file_lengths.sh needs no such
 # division because it reads the tree.
 #
-# NOT IN CI YET. The only CI job that builds mcpp with clang (ci-linux.yml,
-# "toolchain: musl + llvm", llvm@20.1.7) does not produce a complete build:
-# libc++ 20's `std` module does not make directory_iterator's comparison
-# visible, and that step reads the resolution line rather than the build's
-# exit status. Over the partial database clang-tidy crashes. The gate is wired
-# in once a CI job builds mcpp with clang (mcpp-community/mcpp#729); until
-# then it is run by hand after `mcpp build --toolchain llvm@22.1.8`.
+# IN CI SINCE 2026.9.28.2 (#729). ci-linux.yml's "toolchain: musl + llvm" job
+# builds mcpp with llvm@22.1.8 -- failing on the build's own status, which it
+# did not do while it built with llvm@20.1.7 and read only the resolution line
+# -- and runs this script after it, over the compile database that build
+# writes. By hand: `mcpp build --toolchain llvm@22.1.8`, then this script.
 #
 # clang-tidy itself is not part of the plain xim:llvm payload mcpp resolves
 # for `--toolchain llvm@...` (measured: xim-x-llvm/22.1.8/bin has clang,