IronClaw
IronClaw turns documentation drift into a CI failure
IronClaw’s five-part doc-truth series first corrects public extension, Responses API and channel instructions, then scans published paths and binds selected claims to the CLI and owning Rust crates. One pre-fix page taught a manifest shape the current parser hard-rejects; 15 API examples omitted a required model field.
nearai/ironclaw PR #7375 is the inspected primary source: “docs: fix live drift in extension, responses API, and channel docs (doc-truth PR 1/5).” The related records below were inspected as supporting context rather than independent confirmation.
The facts
- nearai/ironclaw PR #7375 was created 2026-08-07T21:17:49Z and was open at inspection; its title is “docs: fix live drift in extension, responses API, and channel docs (doc-truth PR 1/5).” - nearai/ironclaw PR #7376 was created 2026-08-07T21:27:52Z and was open at inspection; its title is “ci(check-guidance): extend the reference gate to the docs/ surface (doc-truth PR 2/5).” - nearai/ironclaw PR #7378 was created 2026-08-07T21:46:50Z and was open at inspection; its title is “test(docs): doc-fact contract tests for CLI, manifest, and Responses claims (doc-truth PR 3/5).” - The repository reported 12598 stars, 1539 open issues, default branch main, and last push 2026-08-08T00:57:06Z. - The latest tagged-release baseline checked was ironclaw-v1.1.0 published 2026-08-06T08:39:11Z.
What changed
nearai/ironclaw PR #7375 reports: Summary Rewrites the manifest sections of docs/extensions/building-a-tool.md to the current reborn.extension_manifest.v3 authoring format ([[tools]], [[tools.credentials]], [auth. ], [mcp]) — the page previously taught the legacy v2 [[host_api]] / [capability_provider.tools] shape, which the v3 parser hard-rejects (crates/extensions/ironclaw_extension_registry/src/v3.rs uses deny_unknown_fields), and never mentioned origin_gate_matrix. This is the exact drift class called out in #7317. Adds an "Origin gate matrix" section documenting origins (loop_run/product/automation), the five policies from OriginGatePolicy, the forbidden-by-default rule, and the reborn_origin_gate_matrix_ratchet.rs shipping requirement. Corrects docs/api/responses.mdx against crates/product/ironclaw_openai_compat: temperature is accepted (0.0–2.0 inclusive, forwarded) not rejected; model is **required** and any well-formed ≤256-byte name (not "must be default"); max_output_tokens and other unknown fields are accepted-and-ignored by DTO policy, not rejected; non-empty tools is rejected only without external-tools wiring. Adds the required model field to all 15 request examples (they would 400 as written — pinned by tests/dto_contract.rs). Fixes docs/channels/building-a-channel.mdx install instructions, which pointed at crates/ironclaw_first_party_extensions/... and available_extensions.rs registration — neither mechanism exists; replaced with the
nearai/ironclaw PR #7376 reports: Summary Extends scripts/ci/check-guidance.py — the existing guidance path-reference gate — to scan the docs/ surface: every published Mintlify page, the docs/zh/ locale mirror, and the living contract corpus docs/reborn/contracts/. The public tree previously had **zero** path validation (the drift #7317 describes). **Scope decision**: the dated archives (docs/internal/, non-contract docs/reborn/) are excluded as classes. Measured before exclusion, 705 of 709 dangling docs references sat in those historical corpora (superpowers plans: 391, internal plans: 115, target-architecture checklists: 97, ADRs: 21, …) — dated plans and ADRs describe the tree as it stood when written; forcing them to track today's tree would rewrite history or drown the shrink-only KNOWN_MISSING table. This narrows the approved plan's "include internal/reborn" intent deliberately; the rationale is encoded in the module docstring and DOCS_EXCLUDED_PREFIXES comment. For docs/ files only backticked inline paths are extracted — Mintlify markdown link targets are site routes (extensionless page paths, site-absolute /using/cli), a different namespace than the tracked
nearai/ironclaw PR #7378 reports: Summary Adds three deterministic **doc-fact contract tests**, each in the crate that owns the truth it checks, pinning published doc claims to real behavior — the PR-time static gate half of the #7317 proposal, with no LLM judging anywhere. **CLI** (crates/app/ironclaw_cli/tests/docs_cli_reference.rs): parses the real binary's --help (same env_clear() spawn as tests/smoke.rs) and cross-checks docs/using/cli.mdx in both directions at subcommand granularity — every visible subcommand documented (any visible alias form counts), every documented command real, ≥15-row fail-closed floor, plus a self-check that the alias table matches clap. Doc gaps it surfaced are fixed in this PR: ironhub had no rows, completion was fence-only, and the Trace Commons table lacked the ironclaw prefix. **Manifest schema** (crates/extensions/ironclaw_extension_registry/tests/docs_manifest_schema_version.rs): walks the published tree (frozen.mintignore fence mirrored as constants, so it cannot silently widen) and asserts zero reborn.extension_manifest.v2 occurrences — fenced code included, since a tutorial code block is exactly where the drift lived — and that building-a-tool.md names MANIFEST_SCHEMA_VERSION_V3
Why it matters
Documentation for an agent runtime is part of its control plane. A dead path or false request contract sends operators into unsafe improvisation, and prose review alone cannot keep a fast-moving tree honest. The operator test is whether the visible result, retained state and authority still describe the same event after retries, background work or restart.
Current
The primary record was open when captured on 2026-08-08. The release baseline was ironclaw-v1.1.0 published 2026-08-06T08:39:11Z. Repository metadata, source bodies, pull requests, issues, releases, Google News, Hacker News, Lobsters, Metamesh and the rendered ClawCharts row were inspected. ClawCharts selected the subject; it did not prove the claim.
Evidence
The primary URL is https://github.com/nearai/ironclaw/pull/7375. Supporting records are https://github.com/nearai/ironclaw/pull/7376 and https://github.com/nearai/ironclaw/pull/7378. Source bodies, timestamps and states are preserved in the daily evidence bundle. Test counts and reproductions remain attributed to their authors unless identified as independently rerun.
Source boundary
Open work is described as open, closed work as closed, and operator reports as reports. A pull request is evidence of proposed or reviewed direction, not proof of a shipped release. Search residue, package mirrors and historically published source spines were excluded.
Operator take
Merge the stacked series in order, keep historical archives fenced rather than rewritten, and require docs-only changes to select the contract tests that consume their claims. Preserve a before-state receipt, make the smallest reversible change, and verify the original failure independently.
Caveat
Public project records are mutable. Status, scope and evidence can change after publication. This brief records the inspected state and does not authorize changes to a reader’s deployment.
Source inspected; source state, environment and release boundary remain explicit.