docs-format: add Glama README.md carve-out (glama.json-gated)

Glama (glama.ai, the MCP-server directory) requires a README.md to index a
server and will not render README.adoc. Add a single, gated carve-out to the
.adoc-canonical / no-duplicate-format rule, keyed on a repo-root glama.json:

- doc-format.yml: skip the duplicate-format error for README when glama.json present
- contractiles/must/Mustfile: readme-md-glama-carveout — require README.md iff glama.json
- contractiles/dust/Dustfile: preserve:glama-readme — cleanup must not delete it
- contractiles/CANONICAL-TEMPLATES.adoc: document the carve-out (the canonical statement)
- .machine_readable/6a2/PLAYBOOK.a2ml: release-step + docs-format note

README.adoc stays the source of truth everywhere; README.md is maintained solely
for Glama. Non-Glama repos (no glama.json) are unaffected. Glama limitation, not
an owner-policy change.

Author: claude

.github/workflows/doc-format.yml

@@ -34,6 +34,15 @@ jobs:
           # Check for docs that exist in both .md and .adoc (except GitHub-required)
           for doc in README ARCHITECTURE ROADMAP PHILOSOPHY INSTALL CHANGELOG; do
             if [ -f "${doc}.md" ] && [ -f "${doc}.adoc" ]; then
+              # Glama carve-out: the Glama MCP-server directory (glama.ai) requires a
+              # README.md to index a server and will NOT render README.adoc. When a
+              # glama.json is present, README.md is permitted alongside the canonical
+              # README.adoc. README.adoc remains the source of truth. This is a Glama
+              # limitation, not an owner-policy change. See contractiles/CANONICAL-TEMPLATES.adoc.
+              if [ "${doc}" = "README" ] && [ -f "glama.json" ]; then
+                echo "::notice::README.md kept alongside README.adoc (Glama carve-out: glama.json present; .adoc remains canonical)."
+                continue
+              fi
               echo "::error::Duplicate documentation: ${doc}.md and ${doc}.adoc both exist. Keep only .adoc"
               DUPLICATES=$((DUPLICATES + 1))
             fi

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -25,6 +25,16 @@ last-updated = "2026-04-11"
 # 1. Update version in STATE.a2ml, META.a2ml
 # 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
 # 3. Tag and push
+# 4. If glama.json is present (repo listed on the Glama MCP directory),
+#    regenerate README.md from the canonical README.adoc before tagging so the
+#    Glama listing stays current. README.adoc is the source of truth; README.md
+#    exists solely for Glama (which will not render .adoc). Carve-out enforced by
+#    doc-format.yml + Mustfile readme-md-glama-carveout + Dustfile preserve:glama-readme.
+
+[docs-format]
+# Estate docs are .adoc-canonical, no duplicate formats. Sole exception: the
+# Glama README.md carve-out (gated on glama.json). See
+# contractiles/CANONICAL-TEMPLATES.adoc "Documentation carve-out — Glama README.md".
 
 [maintenance-operations]
 # Baseline audit: just maint-audit

contractiles/CANONICAL-TEMPLATES.adoc

@@ -60,6 +60,33 @@ Items with an observable probe belong in `[[intents]]`; horizon-level
 desires that might never be acted on belong in `[[wishes]]`. A wish can
 graduate into an intent when a concrete plan materialises.
 
+=== Documentation carve-out — Glama README.md
+
+The estate is `.adoc`-canonical with no duplicate documentation formats
+(`doc-format.yml` blocks a `README.md` that sits alongside `README.adoc`).
+There is exactly one standing exception:
+
+[NOTE]
+====
+*Glama README.md carve-out.* The Glama MCP-server directory
+(https://glama.ai) requires a `README.md` to index a server and will not
+render `README.adoc`. A repository that opts into Glama therefore keeps a
+`README.md` *alongside* the canonical `README.adoc`, gated on the presence
+of a `glama.json` at the repo root.
+
+* `README.adoc` remains the authored source of truth; `README.md` is
+  maintained (regenerated from the `.adoc`) solely to satisfy Glama.
+* This is a Glama limitation, *not* an owner-policy change — it does not
+  loosen the no-duplicate-format rule for any other file or any repo
+  without a `glama.json`.
+* Enforced by three coupled checks, all keyed on `glama.json`:
+  `doc-format.yml` (skips the duplicate error for `README`),
+  `contractiles/must/Mustfile` (`readme-md-glama-carveout` — requires the
+  `README.md` when `glama.json` is present), and
+  `contractiles/dust/Dustfile` (`preserve: glama-readme` — forbids cleanup
+  from deleting it).
+====
+
 == 2. Semantics The Estate Expects
 
 === Must

contractiles/dust/Dustfile

@@ -24,6 +24,13 @@ recovery:
       rollback: "git checkout HEAD~1 -- REPLACE-WITH-REAL-CONFIG-PATH"
       notes: "Roll back a specific config or policy file without disturbing the rest of the tree."
 
+preserve:
+  # Data-preservation carve-out: artefacts a cleanup/uninstall/de-dup pass MUST NOT remove.
+  - name: glama-readme
+    path: "README.md"
+    condition: "test -f glama.json"
+    notes: "Glama (glama.ai, the MCP-server directory) requires README.md to index this server and will not render README.adoc. When glama.json is present, do NOT delete README.md as a duplicate-format violation. README.adoc remains the canonical source of truth; regenerate README.md from it rather than dropping it."
+
 deprecation:
   - name: example-deprecated-surface
     what: "REPLACE with the real API, module, or command being retired."

contractiles/must/Mustfile

@@ -28,6 +28,10 @@ checks:
     description: "README.adoc (or README.md) must exist."
     run: "test -f README.adoc || test -f README.md"
 
+  - name: readme-md-glama-carveout
+    description: "Glama carve-out: if glama.json is present (repo listed on the Glama MCP-server directory, glama.ai), README.md MUST also exist — Glama requires it and will not render README.adoc. README.adoc stays canonical; README.md is maintained solely for Glama. A Glama limitation, not a policy change. No glama.json => no requirement, so non-Glama repos are unaffected."
+    run: "test ! -f glama.json || test -f README.md"
+
   - name: spdx-headers-present
     description: "Source files must carry SPDX-License-Identifier headers."
     run: "bash -uc '! rg --files . | xargs -r grep -rL SPDX-License-Identifier | rg -v \".gitkeep|.lock|LICENSE|NOTICE\" | head -1 | rg .'"