docs: consolidate docs/reborn/ into docs/internal/reborn/ - #7559
Merged
Merged
Conversation
Move-only migration; no content changes beyond path references. Executes the follow-up that PR #7259 left open: docs/.mintignore's reborn/ entry was kept only because the path was load-bearing, and its comment documented that it moves under internal/ once its consumers move with it. - git mv docs/reborn docs/internal/reborn (115 files, history preserved) - rewrite docs/reborn -> docs/internal/reborn across every consumer (crate AGENTS/READMEs and doc-comments, .claude/ skills and rules, AGENTS.md, CI scripts, reborn-e2e.yml path filters, Dockerfile, tests, docs/internal plans) - fix six relative internal/adr/ links inside the moved tree for the added directory level - drop reborn/ from docs/.mintignore and FROZEN_MINTIGNORE_PATTERNS in scripts/ci/docs_publication_boundary.py (the frozen list only ever shrinks); internal/ already fences the new location Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
This PR was not deployed automatically as @thisisjoshford does not have access to the Railway project. In order to get automatic PR deploys, please add @thisisjoshford to your workspace on Railway. |
|
Important Review skippedToo many files! This PR contains 336 files, which is 36 over the limit of 300. To get a review, reduce the PR to 300 files or fewer by splitting it into smaller PRs or changing its base branch. Usage-priced reviews support at most 300 files. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (6)
📒 Files selected for processing (336)
You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
scope: sandbox
Contributor
🧭 IronLoop Run · ReviewThis comment updates in place as the Run moves through its stages. 🟩 Final result · Completed
Automatic trigger · attempt 1 of 3 · completed in 4m 43s IronLoop completed the review and posted it to GitHub. 🔗 Result |
![ironloopai[bot]](https://avatars.githubusercontent.com/in/4116490?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🔍 IronLoop review
🟢 No actionable findings
No actionable issues found in this documentation relocation. The path rewrites, CI scope updates, publication fence change, and moved-document links were consistent with the intended move.
Validation
- ✅ Documentation publication boundary — All documentation pages are published or fenced as required.
- ✅ Guidance path validation — Validated 2,098 guidance path references successfully.
- ✅ Workflow and scope checks — Workflow contracts, target-tree validation, and test-scope classification passed.
- ✅ Architecture path consumers — Relevant architecture test targets passed (62 tests total).
- ✅ Mechanical relocation audit — All modified consumers were literal path rewrites except the intended fence change; moved documents preserved content with the necessary relative-link depth fixes.
Review details
- Run:
a5e2fc6c-2ca6-47be-a24c-fbe4c16e2c05 - Workflow: Review
- Attempts: 1
…f-test fixture Two CI gates failed on the docs/reborn consolidation and forced decisions this commit records: - The Reborn PR test planner failed closed on tests/dockerfile_runtime_home.rs (its path-rewrite edit is functional: the test reads the moved deploy doc). The file was deliberately unmapped because no lane inventoried it. Decide it now: _root_test_partitions() and run-reborn-root-partition.sh both inventory it alongside support_unit_tests.rs, so the hermetic root-partition lanes run it (they previously ran it nowhere) and a change to it selects its partition. With the reader laned, map the two config.hosted-single-tenant*.toml readers it owns in DOCKER_RUNTIME_CONFIG_OWNERS — root-test owners select their root partition, completing the per-file decision set the planner comments left open. docker/process-sandbox-entrypoint.sh stays fail-closed. - test_docs_publication_boundary.py's subset fixture still listed reborn/ in the frozen mintignore list; use the surviving entries. Verified: both self-test suites pass (77 planner + boundary), the planner emits a valid selected plan for this PR's full 342-path diff, shell and Python inventories agree on partition assignment (index 0), and dockerfile_runtime_home passes (19 tests). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
serrrfirat
approved these changes
Aug 13, 2026
gagdiez
approved these changes
Aug 13, 2026
thisisjoshford
added a commit
that referenced
this pull request
Aug 13, 2026
…he docs/internal migration The docs-surface scan carried a double negative — exclude docs/reborn/ as an archive class, then re-include its living pages via DOCS_REINCLUDED_PREFIXES — because the old tree mixed dead archives with living specs. #7559 moved everything under docs/internal/, so the structure is now: one excluded archive class (docs/internal/), and the living spec pages (the contract corpus, the two extension-runtime spec pages, guidance-conventions.md) named in INTERNAL_GUIDANCE_PREFIXES and scanned as first-class guidance files — full link checking, guarded by the same per-prefix zero-match refusal. The published-docs floor now counts only the Mintlify surface (measured 2026-08-13: 82 pages; floor re-halved to 40). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
7 tasks done
thisisjoshford
added a commit
that referenced
this pull request
Aug 13, 2026
… 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>
pull Bot
pushed a commit
to Stars1233/ironclaw
that referenced
this pull request
Aug 13, 2026
…oc-truth PR 2/5) (nearai#7376) * 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 nearai#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 nearai#7317 (doc-truth pipeline, PR 2 of 5); stacked on nearai#7375. 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> * 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 nearai#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(check-guidance): harden the docs gate and fix review-surfaced doc drift Applies the verified findings from the PR nearai#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 nearai#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 nearai#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 b172f69 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> * ci(check-guidance): drop the docs/reborn re-include machinery after the docs/internal migration The docs-surface scan carried a double negative — exclude docs/reborn/ as an archive class, then re-include its living pages via DOCS_REINCLUDED_PREFIXES — because the old tree mixed dead archives with living specs. nearai#7559 moved everything under docs/internal/, so the structure is now: one excluded archive class (docs/internal/), and the living spec pages (the contract corpus, the two extension-runtime spec pages, guidance-conventions.md) named in INTERNAL_GUIDANCE_PREFIXES and scanned as first-class guidance files — full link checking, guarded by the same per-prefix zero-match refusal. The published-docs floor now counts only the Mintlify surface (measured 2026-08-13: 82 pages; floor re-halved to 40). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci(check-guidance): validate docs discovery against docs.json navigation instead of a count floor MIN_DOCS_FILES was an arbitrary magnitude tripwire (half of last measured, hand-re-dated) that only caught the docs branch of discovery losing ~half its pages. The published surface already has an independent definition — docs.json navigation, owned by docs_publication_boundary.py — so the gate now asserts every navigation page's source file is in the reference scan (reusing the boundary script's nav walker and OpenAPI pseudo-page filter). Discovery breaking refuses on the first missing published page, unreadable or page-less navigation refuses rather than passing vacuously, and there is no docs count floor left to tune. --json reports nav_pages_covered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci(check-guidance): count the living internal spec pages in the docs_files metric CodeRabbit: docs_files under-reported the scan — the living internal spec pages are scanned docs files but were excluded from the count, a leftover of the deleted MIN_DOCS_FILES floor's published-only semantics. The metric now reports every scanned file under docs/ (131 at measurement); published surface health has its own signal in nav_pages_covered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci(check-guidance): tighten comments and docstrings Same behavior; the docs-surface comments and test docstrings were carrying paragraph-length rationale better kept in the PR description. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
pull Bot
pushed a commit
to soitun/ironclaw
that referenced
this pull request
Aug 17, 2026
…claims (doc-truth PR 3/5) (nearai#7378) * 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 nearai#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 nearai#7317 (doc-truth pipeline, PR 2 of 5); stacked on nearai#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 nearai#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 nearai#7317 (doc-truth pipeline, PR 3 of 5); stacked on nearai#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 nearai#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 nearai#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 nearai#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 nearai#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 b172f69 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 nearai#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 nearai#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>
l3ocifer
pushed a commit
to l3ocifer/frick-ironclaw
that referenced
this pull request
Sep 3, 2026
* docs: consolidate docs/reborn/ into docs/internal/reborn/ Move-only migration; no content changes beyond path references. Executes the follow-up that PR nearai#7259 left open: docs/.mintignore's reborn/ entry was kept only because the path was load-bearing, and its comment documented that it moves under internal/ once its consumers move with it. - git mv docs/reborn docs/internal/reborn (115 files, history preserved) - rewrite docs/reborn -> docs/internal/reborn across every consumer (crate AGENTS/READMEs and doc-comments, .claude/ skills and rules, AGENTS.md, CI scripts, reborn-e2e.yml path filters, Dockerfile, tests, docs/internal plans) - fix six relative internal/adr/ links inside the moved tree for the added directory level - drop reborn/ from docs/.mintignore and FROZEN_MINTIGNORE_PATTERNS in scripts/ci/docs_publication_boundary.py (the frozen list only ever shrinks); internal/ already fences the new location Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci: classify tests/dockerfile_runtime_home.rs and shrink boundary self-test fixture Two CI gates failed on the docs/reborn consolidation and forced decisions this commit records: - The Reborn PR test planner failed closed on tests/dockerfile_runtime_home.rs (its path-rewrite edit is functional: the test reads the moved deploy doc). The file was deliberately unmapped because no lane inventoried it. Decide it now: _root_test_partitions() and run-reborn-root-partition.sh both inventory it alongside support_unit_tests.rs, so the hermetic root-partition lanes run it (they previously ran it nowhere) and a change to it selects its partition. With the reader laned, map the two config.hosted-single-tenant*.toml readers it owns in DOCKER_RUNTIME_CONFIG_OWNERS — root-test owners select their root partition, completing the per-file decision set the planner comments left open. docker/process-sandbox-entrypoint.sh stays fail-closed. - test_docs_publication_boundary.py's subset fixture still listed reborn/ in the frozen mintignore list; use the surviving entries. Verified: both self-test suites pass (77 planner + boundary), the planner emits a valid selected plan for this PR's full 342-path diff, shell and Python inventories agree on partition assignment (index 0), and dockerfile_runtime_home passes (19 tests). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
l3ocifer
pushed a commit
to l3ocifer/frick-ironclaw
that referenced
this pull request
Sep 3, 2026
…oc-truth PR 2/5) (nearai#7376) * 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 nearai#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 nearai#7317 (doc-truth pipeline, PR 2 of 5); stacked on nearai#7375. 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> * 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 nearai#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(check-guidance): harden the docs gate and fix review-surfaced doc drift Applies the verified findings from the PR nearai#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 nearai#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 nearai#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 b172f69 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> * ci(check-guidance): drop the docs/reborn re-include machinery after the docs/internal migration The docs-surface scan carried a double negative — exclude docs/reborn/ as an archive class, then re-include its living pages via DOCS_REINCLUDED_PREFIXES — because the old tree mixed dead archives with living specs. nearai#7559 moved everything under docs/internal/, so the structure is now: one excluded archive class (docs/internal/), and the living spec pages (the contract corpus, the two extension-runtime spec pages, guidance-conventions.md) named in INTERNAL_GUIDANCE_PREFIXES and scanned as first-class guidance files — full link checking, guarded by the same per-prefix zero-match refusal. The published-docs floor now counts only the Mintlify surface (measured 2026-08-13: 82 pages; floor re-halved to 40). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci(check-guidance): validate docs discovery against docs.json navigation instead of a count floor MIN_DOCS_FILES was an arbitrary magnitude tripwire (half of last measured, hand-re-dated) that only caught the docs branch of discovery losing ~half its pages. The published surface already has an independent definition — docs.json navigation, owned by docs_publication_boundary.py — so the gate now asserts every navigation page's source file is in the reference scan (reusing the boundary script's nav walker and OpenAPI pseudo-page filter). Discovery breaking refuses on the first missing published page, unreadable or page-less navigation refuses rather than passing vacuously, and there is no docs count floor left to tune. --json reports nav_pages_covered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci(check-guidance): count the living internal spec pages in the docs_files metric CodeRabbit: docs_files under-reported the scan — the living internal spec pages are scanned docs files but were excluded from the count, a leftover of the deleted MIN_DOCS_FILES floor's published-only semantics. The metric now reports every scanned file under docs/ (131 at measurement); published surface health has its own signal in nav_pages_covered. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci(check-guidance): tighten comments and docstrings Same behavior; the docs-surface comments and test docstrings were carrying paragraph-length rationale better kept in the PR description. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
l3ocifer
pushed a commit
to l3ocifer/frick-ironclaw
that referenced
this pull request
Sep 3, 2026
…claims (doc-truth PR 3/5) (nearai#7378) * 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 nearai#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 nearai#7317 (doc-truth pipeline, PR 2 of 5); stacked on nearai#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 nearai#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 nearai#7317 (doc-truth pipeline, PR 3 of 5); stacked on nearai#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 nearai#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 nearai#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 nearai#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 nearai#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 b172f69 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 nearai#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 nearai#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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/reborn/moves underdocs/internal/reborn/, ending the last legacy location outside theinternal/publication fence.git mvof all 115 files (history preserved) plus a repo-wide mechanical rewrite ofdocs/reborn→docs/internal/rebornin 225 consumer files — crate AGENTS/READMEs and doc-comments,.claude/skills/rules/commands,AGENTS.md, CI scripts,reborn-e2e.ymlpath filters,Dockerfile, tests, anddocs/internalplans. Six relativeinternal/adr/links inside the moved tree are depth-fixed for the added directory level.reborn/is removed fromdocs/.mintignoreand fromFROZEN_MINTIGNORE_PATTERNSinscripts/ci/docs_publication_boundary.py(the frozen list only ever shrinks;internal/already covers the new location). Comments in both updated.d02a54cc4), forced by the planner's fail-closed arms:tests/dockerfile_runtime_home.rs(whose edit here is functional — it reads the moved deploy doc) was deliberately unmapped in the Reborn PR test planner because no lane ran it. This PR decides it:_root_test_partitions()andrun-reborn-root-partition.shnow inventory it alongsidesupport_unit_tests.rs, so the hermetic root-partition lanes execute it (previously it ran in no CI lane), and the twoconfig.hosted-single-tenant*.tomlfiles it reads are mapped to it inDOCKER_RUNTIME_CONFIG_OWNERS(root-test owners select their root partition).docker/process-sandbox-entrypoint.shstays fail-closed. The docs-boundary self-test fixture also dropsreborn/from its frozen-list sample.Change Type
Linked Issue
Related #7259 (follow-up named in its .mintignore/boundary-script comments)
Validation
cargo fmt --all -- --checkcargo clippy --all --benches --tests --examples --all-features -- -D warningscargo buildcargo test -p ironclaw_architecture_tests --no-fail-fast(41 binaries, 297 passed, 0 failed);dockerfile_runtime_home(19 passed) — no Rust logic changed, only path strings in doc-comments/test fixtures, so clippy/build are unaffecteddocs/rebornreferences remain repo-wide; verified all six depth-fixed ADR links resolve; verified no programmatically-assembleddocs/rebornpaths exist that a text rewrite would missTest Strategy
User behavior: None — internal engineering docs and the CI publication fence; no product behavior.
Risk areas: none checked — no model, browser, side-effect, persistence, security, provider, or cross-component behavior changes.
Tests added or updated:
What the tests prove: every consumer of the old path — the architecture-test suite reading contract files,
check-guidance.py's 2,098 verified path references, thereborn-e2e.ymlscope filters pinned byws12_workflow_contracts.py, the coverage/classify CI scripts, and the Dockerfile deploy-doc test — resolves the new location.Commands run:
python3 scripts/ci/docs_publication_boundary.py— every page published or fencedpython3 scripts/ci/check-guidance.py— 241 guidance files, 2,098 path references verifiedpython3 scripts/ci/check-target-tree.py,python3 scripts/ci/ws12_workflow_contracts.py— passpython3 scripts/ci/test_reborn_pr_test_plan.py(76),test_reborn_changed_coverage.py(28),bash scripts/ci/test-reborn-changed-coverage.sh(113),test-classify-test-scope.sh,test-build-wasm-extensions.sh— passcargo test -p ironclaw_architecture_tests --no-fail-fast— 297 passed, 0 failed (unfiltered output)cargo test -p ironclaw_integration_tests --test dockerfile_runtime_home— 19 passedbash scripts/ci/check-generic-without-concrete.sh --trees-only,python3 scripts/check_no_panics.py --reborn-baseline,bash scripts/ci/check-composition-budget.sh— passbash scripts/ci/test-reborn-coverage.shfails 12/186 cases locally (exit 127 in the sticky-comment cases) — reproduced identically on a pristine HEAD worktree, pre-existing environment issue unrelated to this changeSecurity Impact
None. The publication boundary tightens (one fewer fence entry; the moved tree sits under the already-fenced
internal/). No permissions, network, secrets, file-access, tool-execution, or sandbox changes.Reborn Trust-Boundary Checklist
N/A — documentation move and CI path updates only; no trust-bearing types, prompts, hashes, variants, serde fields, buffers, error classes, or sandbox boundaries touched.
Database Impact
None.
Blast Radius
Anything that reads
docs/reborn/by path: architecture tests,check-guidance.py,docs_publication_boundary.py,reborn-e2e.ymlpath filters + scope regex (pinned by ws12 contracts),classify-test-scope.sh, coverage scripts, the Dockerfile deploy-doc test, and agent guidance (.claude/, AGENTS.md hierarchy). All were rewritten in the same commit and their gates executed. In-flight branches referencing the old path will need a trivial rebase. External deep links github.com/.../docs/reborn/...(e.g. from the movedexplorer.html's absolute URLs before this PR) break; the moved copies now point at the new location.Rollback Plan
Single-commit revert (
git revert) restores the tree and every reference atomically; the fence entries (reborn/in.mintignore+FROZEN_MINTIGNORE_PATTERNS) come back with it, so the boundary gate stays consistent in both directions. Mintlify: the moved pages were already fenced (reborn/entry) and remain fenced (internal/), so no publication change occurs on deploy in either direction.Review Follow-Through
The planner decision above is the one judgment call reviewers may want to weigh: laning
dockerfile_runtime_home.rsmeans the root-partition lanes now run 19 additional hermetic tests (~2s, no Docker daemon; they parse the Dockerfile/configs and drivedocker/reborn/entrypoint.shunder bash). The alternative — classifying it as prose — would have kept a functional test file invisible to CI. Also: the 12 pre-existing local failures intest-reborn-coverage.share environmental (verified against clean HEAD) and left untouched.Review track: B (docs move plus a real CI-planner decision: the previously unlaned
tests/dockerfile_runtime_home.rsnow runs in the root-partition lanes)🤖 Generated with Claude Code