mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
c145f6e522
* docs: fix live drift in extension, responses API, and channel docs
The public tutorial taught the retired manifest v2 authoring format
([[host_api]] / [capability_provider.tools] / runtime_credentials), which
the v3 parser hard-rejects, and never mentioned origin_gate_matrix; the
Responses API page claimed temperature is rejected (accepted 0.0-2.0 and
forwarded), claimed model must be "default" (any well-formed name <= 256
bytes), claimed max_output_tokens is rejected (accepted and ignored by DTO
policy), and omitted the required model field from every request example;
the channel tutorial pointed at two files that no longer exist.
- docs/extensions/building-a-tool.md: rewrite manifest sections to the v3
[[tools]] / [[tools.credentials]] / [auth.<vendor>] shape, document
origin_gate_matrix (origins, policies, ratchet), correct the hosted-MCP
[mcp] section, packaging via ironclaw_extension_support package modules,
and v3 test references; drop the nonexistent script runtime kind.
- docs/api/responses.mdx: correct model/temperature/tools/tool_choice
rejection rules, document unknown-field tolerance, add the required
model field to all 15 request examples.
- docs/channels/building-a-channel.mdx: replace dead
crates/ironclaw_first_party_extensions + available_extensions.rs
registration instructions with the current package-directory mechanism.
- docs/reborn/contracts/extensions.md: state that production manifests
author v3 (lowering into the v2 resolved model described there); label
the v2 examples as legacy.
- docs/reborn/how-to-port-tool-to-reborn.md: superseded banner pointing at
the v3 guides.
Part of #7317 (doc-truth pipeline, PR 1 of 5).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): extend the reference gate to the docs/ surface
The public Mintlify tree had no path-reference validation — a published
tutorial told contributors to edit files that no longer exist and nothing
caught it. check-guidance.py already owned the machinery (tracked-tree
resolution, fence exclusion, suppress markers, shrink-only debt, fail-closed
floors), so the docs surface joins the same gate rather than a fork.
- discover_guidance() now collects every tracked docs/**.md|.mdx: published
pages, the zh/ locale mirror, and the living contract corpus
docs/reborn/contracts/. Dated archives (docs/internal/, the non-contract
parts of docs/reborn/) are excluded as classes — measured 2026-08-07,
705 of 709 dangling docs references sat in those historical corpora, and
forcing dated plans/ADRs to track today's tree would either rewrite
history or drown KNOWN_MISSING.
- docs/ files extract backticked inline paths only; Mintlify markdown link
targets are site routes (extensionless pages, site-absolute /using/cli),
a different namespace than the tracked tree, so the link extractor is off
there by design.
- _reference_lines learns MDX comments ({/* ... */}), including
{/* check-guidance: path-ok */} as the .mdx suppress-marker form, with the
same one-reference-per-marker and multi-line semantics as HTML comments.
- Floors re-measured and re-dated (364 files / 2276 references; floors
180/1100), plus a dedicated MIN_DOCS_FILES=60 floor: the aggregate floors
sit below the guidance-only remainder, so the docs branch of discovery
silently breaking needs its own refusal. --json now reports docs_files.
- Fixes the four real dangles the new scan found in docs/reborn/contracts/
(moved nested_dispatch_stream.rs test home, retired event-store migrations
directory, loop_driver_host tests->src move). KNOWN_MISSING stays empty.
- Self-tests: 8 new cases (dangling docs path fails; Mintlify links are not
references; MDX marker suppresses exactly one reference; multi-line MDX
comment hides content; zh discovered; archives excluded but contracts
scanned; docs fence fails closed; docs floor refuses).
- ws12_workflow_contracts.py: docs/api/responses.mdx and docs/zh/index.mdx
join the has_guidance in-scope probes so a narrowed trigger regex cannot
silently skip the gate for public docs.
Part of #7317 (doc-truth pipeline, PR 2 of 5); stacked on #7375.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): pin CLI, manifest, and Responses doc claims to code
Three deterministic doc-fact contract tests, each living in the crate that
owns the truth it checks, so the drift #7317 describes fails CI instead of
shipping:
- crates/app/ironclaw_cli/tests/docs_cli_reference.rs: parses the real
binary's --help and cross-checks docs/using/cli.mdx table rows both ways
(every visible subcommand documented, any alias form counting; every
documented command real), with a fail-closed row floor. Doc gaps this
surfaced are fixed here: ironhub had no rows at all, completion was
fence-only, and the Trace Commons table lacked the `ironclaw` prefix the
rest of the page uses.
- crates/extensions/ironclaw_extension_registry/tests/
docs_manifest_schema_version.rs: walks the published docs tree (the
frozen .mintignore fence mirrored as constants) and asserts zero
occurrences of the retired reborn.extension_manifest.v2 literal, fenced
code included; asserts building-a-tool.md names
MANIFEST_SCHEMA_VERSION_V3 verbatim and documents origin_gate_matrix.
- crates/product/ironclaw_openai_compat/tests/docs_responses_contract.rs:
docs/api/responses.mdx now carries a machine-readable
{/* doc-fact:responses-request-policy */} marker block (invisible when
rendered); the test parses it and drives every claim through the same
route-level seam as the sibling *_contract.rs suites — the marker's
values parameterize the assertions (temperature accepted at the
documented max and rejected just above it, model accepted at the byte
cap and rejected past it, tool_choice always 400, tools 400 without /
registered with external-tool wiring, empty tools treated as omitted,
unknown fields like max_output_tokens accepted and ignored, and one
request carrying every documented field accepted).
Part of #7317 (doc-truth pipeline, PR 3 of 5); stacked on #7376.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: address Copilot and CodeRabbit review on doc-drift PR
- responses.mdx: tool_choice is rejected only without external-tools wiring;
with external tools enabled it passes validation and is currently ignored
(validate_responses_supported_fields_with_external_tools never checks it).
- building-a-tool.md: clarify that effect-derived host ports are validation
vocabulary against the HostPortCatalog allowlist; adapters are built by
host-runtime services after authorization/obligations, never from manifests.
- how-to-port-tool-to-reborn.md: mark the decision tree's RuntimeKind targets
historical (v3 accepts only wasm|first_party; MCP is top-level [mcp];
process/CLI work is the sandbox lane).
- building-a-channel.mdx: document the user install flow — virtual package
root /system/extensions/<id>/manifest.toml, ironclaw extension search /
install <extension-id> (ID, not path), WebUI Extensions lifecycle.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(responses): align the limits bullet with the corrected tool_choice claim
The rejection list was corrected in the previous commit (tool_choice is
rejected only without external-tools wiring); the "Limits and quirks"
bullet still said "not supported ... rejected with 400". Same claim, one
wording.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): tool_choice is conditionally rejected, not always
Copilot review on the docs PR caught that
validate_responses_supported_fields_with_external_tools never checks
tool_choice — with external tools wired it is accepted and ignored, not
400'd. The doc-fact marker moves tool_choice into
rejected_without_external_tools, and the dedicated test now proves both
sides: 400 naming the param on the plain router, accepted-and-ignored
(submit succeeds, nothing registers) with external-tool wiring.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs: apply verified code-review findings on the drift PR
A full code review of this PR against live code surfaced claims the
original drift pass got wrong or missed; every fix below was re-verified
against the cited source before editing:
- responses.mdx: standard `ironclaw serve` deployments always wire
external tools (OpenAiCompatRouteMountPorts requires the store/resume
pair; mount.rs wires them unconditionally), so `tools` is accepted and
`tool_choice` is accepted-and-ignored on shipped binaries — the
conditional 400s apply only to custom compositions without the wiring
(now a Note). temperature is validated and carried in the submitted turn
payload but not applied as a provider sampling parameter. Non-streaming
wait timeout is 30 s (DEFAULT_RESPONSES_WAIT_TIMEOUT), not 120. usage on
retrieval is read best-effort from persisted run state incl. USD cost
(read_run_usage), not always zero.
- building-a-tool.md: the [auth.example] oauth2_code recipe gains the
required token_response map (deny_unknown_fields rejects the example as
previously written); Gmail/Google Calendar corrected to first_party
runtimes (their manifests declare kind = "first_party"); the worked
api_key recipe is github's, not slack's; the tail "Quick implementation
checklist" and reference list were still v2-era (script lane,
assets/<extension>/ path, "manifest v2", v2.rs pointer) and now teach
the v3 shape; composition/CLI package-naming claim narrowed (the binary
does link slack/telegram adapter crates).
- contracts/extensions.md: legacy-format paragraph no longer claims
host-bundled packages ship v2 (none do), and origin_gate_matrix is
attributed to capability.rs + building-a-tool.md instead of
extension-runtime/overview.md §3, which does not mention it.
- how-to-port banner: `script` manifest authoring is retired; the
RuntimeKind::Script symbol survives as the process-sandbox lane's kind.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* docs(contracts): repoint delivery_resolution.rs to its family directory
PR #7157 (merged to main 2026-08-07) cited
crates/ironclaw_outbound/src/delivery_resolution.rs in the
communication-delivery-resolution contract; the crate lives at
crates/domains/ironclaw_outbound/. Caught by this branch's docs surface of
check-guidance.py on the first merge of main after the gate landed —
exactly the drift class it exists for.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(test-plan): route docs pages to the doc-fact tests that read them
docs/ sat in IGNORED_PREFIXES as a pure-prose class, which this PR's
doc-fact tests falsify: three cargo tests now read published pages, so
a docs-only PR would have selected zero crate tests and merged green,
leaving the failure to land on whichever unrelated change ran the full
plan next.
Published Markdown now selects the registry's schema-version sweep;
docs/using/cli.mdx and docs/api/responses.mdx additionally select
their owning crates. All selections are direct exact test targets —
no reverse-dependency widening, since prose only changes the doc-fact
assertions that read it. Fenced trees (docs/internal/, docs/reborn/,
drafts) and non-page files keep the prose classification.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): harden the docs gate and fix review-surfaced doc drift
Applies the verified findings from the PR #7376 code review:
- The loop-exit and turn-runner contract docs claimed the deleted
loop_driver_host checkpoint-rejection test had 'moved into the
module'; it was deleted in #6696 and the fenced verification command
could not run. Both now cite the real surviving pins
(planned_driver.rs executor test + the ironclaw_turns projection
test mapped in scripts/reborn-e2e-rust.sh), with runnable commands.
- An unterminated comment now refuses at EOF like an unterminated
fence; before, one typo'd closer silently un-scanned the rest of the
file.
- Markdown links in the re-included corpora are now checked as repo
paths (they are never published, so the Mintlify-route rationale did
not apply); this alone added ~165 verified references.
- Each DOCS_REINCLUDED_PREFIXES entry must match at least one tracked
page or discovery refuses, so the planned docs/reborn consolidation
cannot silently drop the corpus from the scan.
- The living extension-runtime spec pages (overview.md,
standard-operations.md) and guidance-conventions.md join the scan;
guidance-conventions.md now describes the docs surface and the MDX
marker form, and its one dangling test path is repointed.
- Floors comment corrected (57 rule globs, not 38).
Also fixes four drifted claims from #7375's pages, verified against
live code: the interleaved function_call_output example was rejected
with 400 (resume input must be exclusively function_call_output items
with previous_response_id); model is echoed only on create (GET/cancel
report the 'reborn' placeholder); output_schema_ref is optional; and
the unknown-fields claim now names the two deliberate exemptions.
Self-tests: 43 pass (three new arms — unterminated comment refusal in
both syntaxes, re-included links as repo claims, stale re-included
prefix refusal).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* ci(check-guidance): sync module docstring with re-included link checking
CodeRabbit caught the docstring still claiming the link extractor is
off for all of docs/** — stale since b172f69c7 enabled it for the
re-included corpora. The docstring now states the exception and the
current re-include set.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): drop the retired reborn/ entry from the publication-fence mirrors
reborn/ left docs/.mintignore when #7559 consolidated it into internal/;
the fence mirrors in docs_manifest_schema_version.rs and
reborn_pr_test_plan.py still listed it. Fixture paths follow the move.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): tighten doc-fact comments and docstrings
Same behavior; module docs and test docstrings trimmed to the point.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): harden the doc-fact suites per CodeRabbit review
- CLI: validate full documented command paths via `ironclaw <path> --help`
(immediately caught and removed the nonexistent `extension activate` row)
and match visible aliases as exact tokens, not substrings.
- Responses: seed a real prior response so `previous_response_id` is
actually submitted and accepted; document `metadata` in the visible table
to match the marker.
- Manifest sweep: parse the publication fence from docs/.mintignore instead
of mirroring it, so a removed fence entry widens the scan with it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(docs): correct the completion syntax and parse the fence in the planner
Review findings (sub-agent /code-review):
- docs/using/cli.mdx taught `ironclaw completion <shell>`; the binary only
accepts `--shell <shell>`. The contract test stops extracting at flags,
so it could not catch this.
- The planner's doc-fact arm mirrored the .mintignore fence as constants —
the same hand-maintained-mirror class the PR removes elsewhere. It now
parses docs/.mintignore via docs_publication_boundary, and a .mintignore
edit itself routes to the published sweep.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(test-plan): treat a missing docs/.mintignore as no fence, not a crash
Matches docs_publication_boundary.find_violations(): fence gone means
everything is published, so every page routes to the sweep.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): replace the doc-fact count floors with derived anchors
Same move as #7376's MIN_DOCS_FILES removal: MIN_DOC_COMMAND_ROWS was
redundant with the completeness check (the binary defines the expected
set), and MIN_SCANNED_PAGES is now a docs.json nav-coverage assertion —
every source-backed navigation route must be among the walked pages.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* test(docs): assert the current schema version instead of scanning for a retired literal
Hardcoding `reborn.extension_manifest.v2` was backward-looking: retiring
v3 would need a hand-edit or the test goes stale. The scan now extracts
every `reborn.extension_manifest.<version>` mention in published pages
and asserts it equals `MANIFEST_SCHEMA_VERSION_V3`, with the family
prefix derived from the same constant — the next schema bump retargets
the test by itself, and typo'd or older versions (v1, v33) are caught
too.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>