Address PR #72 round 2: wording precision + pattern intra-links

Three "reachable from" → "AT" wording fixes (build_agents_md.py
module docstring, .github/workflows/ci.yml comment, CHANGELOG.md
entry). The strict check (git tag --points-at HEAD) is the
load-bearing invariant — a wheel built from a commit between two
release tags would silently ship as if it were the prior tag.
Wording now matches implementation; the check is unchanged.

Module docstring's section-4 description previously said patterns
were inlined "verbatim", which became stale when
_transform_pattern_content landed earlier in this PR. Updated to
describe both transforms (heading demotion + relative-link rewrite).

_transform_pattern_content gains a second regex,
_PATTERN_INTRA_LINK_RE, that rewrites pattern-to-pattern bare-name
.md references to in-document anchors (e.g.,
`(bypass-if-output-exists.md)` → `(#bypass-if-output-exists)`).
The demoted H3 heading slug matches the filename slug, so the
anchor resolves cleanly in the bundled single-file context. Closes
the broken pattern cross-link in tool-dispatch-as-node's
"Cross-references" section.

Author: chris-colinsky

.github/workflows/ci.yml

@@ -29,11 +29,13 @@ jobs:
       - name: Fetch submodule tags
         # actions/checkout's submodule clone is shallow and doesn't
         # carry tags. ``scripts/build_agents_md.py`` asserts the
-        # submodule HEAD is reachable from a ``v*`` tag (refuses to
-        # bundle draft spec text); ``tests/test_agents_md_drift.py``
-        # runs that assertion. Fetch tag refs only — the HEAD commit
-        # is already present from the submodule checkout, and we
-        # don't need history beyond what tags point at.
+        # submodule HEAD is AT a ``v*`` tag (``git tag --points-at
+        # HEAD``; refuses to bundle draft spec text or text from
+        # a commit between two release tags);
+        # ``tests/test_agents_md_drift.py`` runs that assertion.
+        # Fetch tag refs only — the HEAD commit is already present
+        # from the submodule checkout, and we don't need history
+        # beyond what tags point at.
         run: git -C openarmature-spec fetch --tags
 
       - name: Install uv

CHANGELOG.md

@@ -8,7 +8,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The
 
 ### Added
 
-- **Bundled agent documentation at `openarmature/AGENTS.md`.** The wheel now ships a generated `AGENTS.md` file at the installed package root, agent-discoverable via `python -c "import openarmature; print(openarmature.__path__[0] + '/AGENTS.md')"`. Sections include a TL;DR, capability summaries pulled from the pinned spec submodule's §1 (Purpose) + §2 (Concepts), the patterns docs, hand-written non-obvious-shapes recipes, and a one-line example index. Generator lives at `scripts/build_agents_md.py`; the committed file is CI-drift-checked by `tests/test_agents_md_drift.py`. The submodule pin discipline (build refuses unless the submodule HEAD is reachable from a `v*` tag) prevents draft spec text from leaking into a release bundle. Adopting projects can point their own `AGENTS.md` / `CLAUDE.md` at this path so agent sessions in their codebase find it automatically.
+- **Bundled agent documentation at `openarmature/AGENTS.md`.** The wheel now ships a generated `AGENTS.md` file at the installed package root, agent-discoverable via `python -c "import openarmature; print(openarmature.__path__[0] + '/AGENTS.md')"`. Sections include a TL;DR, capability summaries pulled from the pinned spec submodule's §1 (Purpose) + §2 (Concepts), the patterns docs, hand-written non-obvious-shapes recipes, and a one-line example index. Generator lives at `scripts/build_agents_md.py`; the committed file is CI-drift-checked by `tests/test_agents_md_drift.py`. The submodule pin discipline (build refuses unless the submodule HEAD is AT a `v*` tag via `git tag --points-at HEAD`) prevents draft (untagged) spec text — or text from a commit between two release tags — from leaking into a release bundle. Adopting projects can point their own `AGENTS.md` / `CLAUDE.md` at this path so agent sessions in their codebase find it automatically.
 - **`FanOutInstanceProgress.result_is_error` field** (proposal 0027, accepted in spec v0.21.0). Explicit boolean discriminator on each per-instance entry in `CheckpointRecord.fan_out_progress` — `True` for `collect`-mode error contributions (roll forward into `errors_field`), `False` for success contributions (roll forward into `target_field`). The engine reads the explicit field on resume rather than inferring routing from `result`'s shape; the previous structural heuristic (`_looks_like_error_record`) is removed. Backward-compat path on load: pre-0027 records that omit the key default to `False`.
 - **Strict `CheckpointRecordInvalid` on fan-out count drift** (proposal 0029, accepted in spec v0.22.0). When the resumed run's resolved instance count differs from the saved `fan_out_progress` entry's `instance_count`, the engine raises `CheckpointRecordInvalid` before any fan-out instance work runs on the resumed path. Replaces the pre-0029 pad/truncate behavior which silently dropped `completed` contributions on shrink (breaking §10.11.1's exactly-once guarantee) and dispatched unsaved work on grow.
 - **`tool_choice` parameter on `Provider.complete()`** (proposal 0025, accepted in spec v0.20.0). Optional discriminated-union value constraining the model's tool-calling behavior — one of `"auto"`, `"required"`, `"none"`, or a `ForceTool(name=...)` record. Validation runs pre-send: `"required"` and `ForceTool` both demand non-empty `tools`, and `ForceTool.name` must appear in the supplied list; violations raise `ProviderInvalidRequest` (§7's existing category — no new error category). When `tool_choice` is `None` (the default) the wire field is omitted and the provider's own default applies, preserving pre-0025 behavior exactly. The `OpenAIProvider` maps the spec shape onto OpenAI's wire shape per §8.1.1 (the `ForceTool.type="tool"` renames to wire `type="function"`).

scripts/build_agents_md.py

@@ -13,8 +13,15 @@
    capability spec, read from the pinned ``openarmature-spec``
    submodule via ``git show <sha>:spec/...`` rather than the
    working tree.
-4. ``docs/patterns/*.md`` — verbatim concatenation of the patterns
-   docs (excluding ``index.md``).
+4. ``docs/patterns/*.md`` — concatenation of the patterns docs
+   (excluding ``index.md``), with bundle-side transforms applied
+   in ``_transform_pattern_content``: ATX headings demoted by two
+   levels (so a pattern's ``# Title`` H1 renders as ``### Title``
+   H3 under the bundle's ``## Patterns`` H2) and relative
+   ``../concepts/...md`` / ``../examples/...md`` links rewritten
+   to absolute ``openarmature.ai`` URLs (the relative paths
+   resolve in the MkDocs source tree but not in the installed
+   wheel).
 5. ``docs/agent/non-obvious-shapes.md`` — hand-written opinionated
    recipes.
 6. Example index — one-line description + path for each
@@ -25,8 +32,9 @@
 Build-time invariants (matches proposal-0028 follow-on review's
 submodule-pin discipline):
 
-- Submodule HEAD MUST be reachable from a ``v*`` tag. The build
-  refuses to read draft (untagged) spec text into a release bundle.
+- Submodule HEAD MUST be AT a ``v*`` tag (``git tag --points-at HEAD``).
+  The build refuses to read draft (untagged) spec text — or text from
+  a commit between two release tags — into a release bundle.
 - Spec text is read from the pinned commit via ``git show``, NOT
   from the submodule working tree. Closes the "submodule HEAD
   moved but bundle still reads stale tree" failure mode.
@@ -203,6 +211,13 @@ def _capability_summaries(spec_tag: str) -> str:
 
 _PATTERN_LINK_RE = re.compile(r"\(\.\./(concepts|examples)/([^)]+?)\.md\)")
 
+# Matches bare-name ``.md`` references in the patterns markdown
+# (pattern-to-pattern links like ``(bypass-if-output-exists.md)``).
+# The negative lookahead skips ``../`` parent-relative paths
+# (handled by ``_PATTERN_LINK_RE``), ``http(s)://`` absolute URLs,
+# and ``#`` in-document anchors.
+_PATTERN_INTRA_LINK_RE = re.compile(r"\((?!\.\.|https?://|#)([a-z0-9-]+)\.md\)")
+
 
 def _transform_pattern_content(text: str) -> str:
     """Bundle-side rewrite of a pattern doc's markdown.
@@ -242,7 +257,13 @@ def _rewrite(m: re.Match[str]) -> str:
             return f"(https://openarmature.ai/{section}/)"
         return f"(https://openarmature.ai/{section}/{name}/)"
 
-    return _PATTERN_LINK_RE.sub(_rewrite, out)
+    out = _PATTERN_LINK_RE.sub(_rewrite, out)
+    # Rewrite intra-pattern links to in-document anchors. Bare-name
+    # ``.md`` references render fine on the MkDocs site (sibling-file
+    # resolution) but break in the bundled single-file AGENTS.md.
+    # The demoted H3 heading slug matches the filename slug — e.g.,
+    # ``(bypass-if-output-exists.md)`` → ``(#bypass-if-output-exists)``.
+    return _PATTERN_INTRA_LINK_RE.sub(lambda m: f"(#{m.group(1)})", out)
 
 
 def _patterns() -> str:

src/openarmature/AGENTS.md

@@ -815,7 +815,7 @@ for malformed `ToolCall.arguments`, and trace output.
 
 - Tools have side effects you can't replay safely on resume. Wrap
   each side-effecting tool with the
-  [bypass-if-output-exists](bypass-if-output-exists.md) pattern so
+  [bypass-if-output-exists](#bypass-if-output-exists) pattern so
   a crashed run resumes without re-side-effecting.
 - The "tools" are long-running async pipelines, not function
   calls. Model them as subgraphs and let the LLM node route via