Refresh agent documentation standards

[leynos]

Summary

This branch refreshes the repository's agent and documentation standards from the upstream Rust agent template, then formats the documentation set so the repository gates pass under the new rules.

Issue: none.
Roadmap task: none.
Execplan: none.

Review walkthrough

• Start with AGENTS.md to review the imported agent instructions, including the updated documentation, testing, observability, and Rust contribution rules.
• Then review docs/documentation-style-guide.md to inspect the imported documentation style guide and canonical document-type guidance.
• Continue with docs/contents.md and docs/repository-layout.md for the local index and repository layout adjustments required by the new guide.
• Finish by scanning the formatted documentation changes under docs/ to confirm the formatter-only churn and the narrow lint repairs that made the Markdown gate pass.

Validation

• make fmt: passed.
• make check-fmt: passed.
• make lint: passed.
• make test: passed; nextest ran 1430 tests with 1430 passed and 4 skipped, and doctests passed.
• make markdownlint: passed.
• make nixie: passed.

Notes

The upstream AGENTS.md.jinja contained no active Jinja control tokens at import time, so it was imported as Markdown after verification. The repository Markdown formatter touched existing documentation files beyond the two imported templates; those formatting changes are included because make fmt is part of the documented workflow for documentation updates.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 2500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Walkthrough

This PR comprehensively refresh the repository documentation: rewrite AGENTS.md with expanded Rust guidance, add a Documentation maintenance section, standardise ExecPlan "living document" formatting, expand the documentation style guide and repository layout, and reflow many docs across the docs/ tree.

Changes

Assistant Instructions and Repository Contributor Guidance

Layer / File(s)	Summary
Assistant instructions restructure and documentation maintenance policy AGENTS.md	Early section headings are re-capitalised. New "Documentation maintenance" section adds explicit guidance for updating knowledge sources, ADRs, and user/developer guides.
Change quality, refactoring workflow, and Rust testing/error-handling expectations AGENTS.md	Commit-message guidance is refined. Workflow heuristics expand with repository-sweep abstraction policy. Rust-specific testing expectations cover unit, behavioural, property, e2e, and proof tests; module-level and Rustdoc documentation requirements are introduced; error-handling guidance strengthens around expect/unwrap and result-returning constraints.
Dependency management, type-system patterns, and observability standardisation AGENTS.md	NewType wrapper guidance is updated. cap_std and camino are preferred over std::fs/std::path. Dependency specs enforce caret-only versions with explicit prohibition of unstable and wildcard specifiers. Test environment mutation is constrained. tracing and metrics usage patterns are standardised with instrumentation boundaries and label rules.
Project documentation and additional tooling sections reorganisation AGENTS.md	Documentation guidance is reorganised into a dedicated "Project documentation" section covering ADR/design recording and user-guide updates. "Additional tooling" list is remodelled. Section placement before "Key takeaway" is adjusted.

Documentation Conventions, Style Guide, and Repository Mapping

Layer / File(s)	Summary
Documentation style guide expansion: spelling, punctuation, and standard document types docs/documentation-style-guide.md	British English spelling rules are expanded. Punctuation guidance for collective nouns is revised. Markdown linting reference is updated from markdownlint-cli2 to markdownlint. Substantial "Standard document types" section is added, defining canonical filenames, audience, and structure for contents, user's guide, developer's guide, and design/ADR/RFC documents.
ADR template, repository layout document, and GIST-aligned roadmap guidance docs/documentation-style-guide.md	ADR template code fence is adjusted to use plaintext. New "Repository layout document" section introduces explicit canonical location. Rust documentation examples are updated to use no_run. Roadmap example code fence becomes plaintext. GIST workstream alignment guidance is added with stronger constraints against passive step-as-heading structures.
Documentation contents index and landing page docs/contents.md	Heading is changed from "Contents index" to "Documentation contents" with added introductory paragraph describing the file as the central documentation index.
Repository layout and workspace structure documentation docs/repository-layout.md	Top-level tree description clarifies authoritative workspace crate mapping and explicit exclusion of target/ output. crates/ and root-level listings are expanded to include additional Sempai, Weaver, and test-support crates. Implemented components tables are extended with weaver-daemon-types, weaver-test-macros, and broader shared directory coverage including agent-skill/weaver/, .agents/, and .github/workflows/. Planned Sempai entry is revised to clarify DSL and Tree-sitter backend crate locations.

ExecPlan Living Document Standardisation

Layer / File(s)	Summary
Early prototype and daemon-startup ExecPlan updates docs/execplans/13-3-3-archive-3-2-2-daemon-start-help-guidance.md, docs/execplans/2-2-1-act-apply-patch-sub-command.md, docs/execplans/2-2-2-list-all-domains-in-top-level-help.md, docs/execplans/2-2-3-top-level-version-output.md, docs/execplans/2-2-4-provide-contextual-domain-guidance.md, docs/execplans/2-3-1-validate-domains-client-side-before-daemon-startup.md, docs/execplans/2-3-2-valid-operation-alternatives-for-unknown-operations.md, docs/execplans/2-3-3-standardize-actionable-guidance-in-startup-errors.md, docs/execplans/2-3-4-return-argument-requirements-for-act-refactor.md	"Living document" sections across all early-phase ExecPlans are reformatted with consistent line-wrapping and inline code formatting. Content and requirements are unchanged.
Mid-phase (Sempai/configuration/validation) ExecPlan reformatting docs/execplans/3-1-1a-plugin-for-rope.md, docs/execplans/3-1-1b-plugin-for-rust-analyzer.md, docs/execplans/3-2-1-surface-configuration-flags-in-clap-help-output.md, docs/execplans/4-1-1-scaffold-sempai-core-and-sempai.md, docs/execplans/4-1-2-structured-diagnostics-with-stable-error-codes.md, docs/execplans/4-1-3-yaml-rule-parsing-via-saphyr-and-serde-saphyr.md, docs/execplans/4-1-4-mode-aware-sempai-validation.md, docs/execplans/4-1-5-normalization-into-canonical-formula-model.md	"Living document" sections are reformatted. Constraint, tolerance, and surprise notes are reflowed without semantic change. Stage descriptions and checklist items maintain original content.
Entry-help and rename-symbol capability ExecPlan updates docs/execplans/5-1-1-entry-help.md, docs/execplans/5-2-1-define-the-rename-symbol-capability-contract.md, docs/execplans/5-2-2-update-weaver-plugin-rope-manifest.md, docs/execplans/5-2-3-update-rust-plugin-to-declare-rename-symbol.md, docs/execplans/5-2-4-daemon-capability-resolution-for-rename-symbol.md, docs/execplans/5-2-5-unit-behavioural-and-end-to-end-coverage-for-rename-symbol.md	"Living document" sections are reformatted. Entry-help specifically expands FluentLocalizer construction description with numbered steps and fallback behaviour clarification.
Card extraction and graph-slice schema ExecPlan standardisation docs/execplans/7-1-1-stable-jsonl-schemas-for-observe-get-card.md, docs/execplans/7-1-2-tree-sitter-symbol-card-extraction.md, docs/execplans/7-1-3-implement-optional-lsp-enrichment-for-observe-get-card.md, docs/execplans/7-1-4-cache-integration-for-card-extraction-keyed-by-uri.md	"Living document" sections are reformatted. Schema code-block formatting for ParamInfo, LspInfo, DepsInfo, and CardRefusal is adjusted. Stage A checklist items for cache module are reformatted with consistent layout.
Graph-slice, adoption, and foundational-phase ExecPlan updates docs/execplans/7-2-1-define-stable-jsonl-request-and-response-schemas-for-observe-graph-slice.md, docs/execplans/adopt-ortho-config-v0-8-0.md, docs/execplans/phase-1-implement-the-socket-listener-in-weaverd.md	"Living document" sections are standardised. Graph-slice plan's URI argument description and constraint links are reworded to use relative paths. Adoption and phase-1 items use consistent inline-code formatting.
Core design and roadmap ExecPlan formatting docs/execplans/sempai-design.md, docs/execplans/weaver-agent-roadmap.md	"Living document" section line-wrapping is adjusted to present section names consistently across lines.

Design Specifications and Architectural Documentation

Layer / File(s)	Summary
Weaver design specification clarifications: machine output, config behaviour, and safety harness docs/weaver-design.md	0.1.0 target is specified to use --json as the canonical machine switch without supporting root --output or per-operation --format. weaver-config behaviour description is expanded to clarify merged precedence order and strict TOML v1 parsing semantics. WEAVER_FOREGROUND shutdown-signal section is rephrased. SyntacticLock::validate signature formatting is updated. Configurable test doubles for safety harness behavioural testing are documented. weaver-lsp-host historical entry is refined to emphasise capability-aware routing and fail-fast structured error semantics.
Card-first symbol graph and observability schema documentation docs/jacquard-card-first-symbol-graph-design.md, docs/formal-verification-methods-in-weaver.md	observe graph-slice response-shape section is reflowed to clarify resolution_scope values and empty edges array semantics. Testing stack and Kani harness placement guidance is reformatted.
Sempai query language and technical design documents docs/sempai-query-language-design.md, docs/rust-extricate-actuator-plugin-technical-design.md	"Schema-aligned validation" section is reflowed around error-code and WhereClause type description. "System context" and "Authoritative runbook" sections are reformatted with no semantic change.

Developers' and Users' Guides, and Technical Walkthroughs

Layer / File(s)	Summary
Developers guide: card extraction, graph-slice handling, and observability dispatch docs/developers-guide.md	Card-extraction cache guidance is rewrapped to contrast owned versus shared-resource extraction. observe graph-slice handler architecture is re-organised to keep --max-cards 0 rejection note adjacent to budget description. LSP enrichment ordering paragraph is reformatted. run_graph_slice helper and GraphSliceResponse schema fields descriptions are reflowed. refactor_helpers/requirements section spacing is adjusted. Dispatch lifecycle observability internals introductory text is reformatted.
Users guide: configuration, daemon operations, and command parameters docs/users-guide.md	Line-wrapping adjustments are made in: configuration-load-failure behaviour description, daemon response handling for unimplemented operations, weaver daemon start --help help-surface contract, edge resolution_scope wording, act refactor required-flags sentence, and sempai_core crate type-list parenthesisation.
Rust testing, parser testing, and fixture guides docs/rust-doctest-dry-guide.md, docs/rust-parser-testing-comprehensive-guide.md, docs/rust-testing-with-rstest-fixtures.md	Multiple paragraphs in rust-doctest-dry-guide are reflowed around separate-crate explanation, #[cfg(doc)] discussion, IDE workflow, and citation footnote placement. Section 4.4 and 5.1 prose in rust-parser-testing-comprehensive-guide are re-wrapped around rowan example and proptest shrinking description. Table 2 in rust-testing-with-rstest-fixtures is reformatted for column alignment.
BDD testing, configuration, and parser design guides docs/rstest-bdd-users-guide.md, docs/ortho-config-users-guide.md, docs/pratt-parser-for-ddlog-expressions.md	Line-wrapping adjustments are made in rstest-bdd skip scenario explanation, skip-thread constraint, asserting-skipped-outcomes paragraph, placeholder/type-hint parsing rules, and JUnit XML writer description. Ortho-config introduction to rstest-bdd scenarios, "Hello world walkthrough" subcommand description, and error-handling section are reflowed. Tree-sitter parser invocation description is line-wrapped.
Testing methodology, dependency injection, and verification guides docs/reliable-testing-in-rust-via-dependency-injection.md, docs/complexity-antipatterns-and-refactoring-strategies.md	Opening paragraph in reliable-testing is reformatted around external dependencies and global non-deterministic state. Cyclomatic Complexity formula explanation is split across separate lines.
Schema reference and semgrep documentation docs/semgrep-language-reference/semgrep-minimal-examples.md	"Recommended eight-file pack" table header and row formatting is adjusted for column alignment. Referenced example-file mappings are preserved.

Roadmap and Archive Documentation

Layer / File(s)	Summary
Roadmap RFC 0001 references and graph-slice context docs/roadmap.md	RFC 0001 section references are presented as explicit bulleted lists (instead of inline "§§[...]" chains) in the local daemon observability contract area (13.4.4) and deferred observability expansions section (20.3). Bullet labels in the 20.3 update are shortened (e.g., "status expansion", "diagnostics artefact"). A sentence in the 17.1 graph-slices context is reflowed around "migrates prototype archive work …" wording.
Prototype roadmap and RFC footnote standardisation docs/archive/prototype-roadmap.md, docs/rfcs/0001-o11y.md	"Outcome" sections in prototype-roadmap phases 4.1, 5.3, 5.5, 6.1, 7.3, and 11.1 are reformatted with adjusted line-wrapping and citation placement. RFC 0001 has footnote reference marker [^5] repositioned without altering citation target or context.

Sequence Diagram(s)

(Skip — changes are documentation reflows and policy additions; no new runtime component interactions introduced.)

Possibly related PRs

• leynos/ortho-config#336: Overlaps AGENTS.md Rust-specific testing/refactoring/documentation rules and docs-index/style updates.
• leynos/falcon-correlate#47: Matches AGENTS.md contributor guidance rewrite and related docs-index changes.
• leynos/weaver#131: Related ExecPlan/daemon-start-help guidance alignment and WEAVER_FOREGROUND notes.

Suggested labels

Roadmap

"Reflow the docs, polish the guide,
AGENTS now clearer, Rust rules supplied,
ExecPlans aligned and indexes wide,
Repo map updated, style refined,
Ship the docs and keep the path tidy."

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/sync-agent-docs

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/documentation-style-guide.md`:
- Line 285: The RFC template's fenced code block currently uses the "markdown"
language identifier; update the RFC template code fence to use "plaintext"
(matching the ADR template's usage) so non-code text uses the correct language
identifier—locate the RFC template code block (the block starting with
```markdown and the header "# RFC 0001: <title>") and change the fence
identifier to ```plaintext.

In `@docs/execplans/7-1-4-cache-integration-for-card-extraction-keyed-by-uri.md`:
- Around line 310-315: Fix the corrupted markdown list by correcting item 1 to
show the CardCacheKey struct fields with balanced backticks and proper
punctuation: list the fields as path: PathBuf, content_hash: [u8; 32], language:
SupportedLanguage (from weaver-syntax), detail: DetailLevel, line: u32, column:
u32 and end the sentence with "Implement `Hash` and `Eq`." Remove or merge the
nonsensical item 2 ("`. `") so the numbered list is coherent and only contains
the intended entries related to CardCacheKey.

In
`@docs/execplans/7-2-1-define-stable-jsonl-request-and-response-schemas-for-observe-graph-slice.md`:
- Around line 76-80: Rewrite the fragmented introductory sentence into a single
complete line: "The following documents must all be updated before the work is
complete:" and insert a blank line after that sentence and before the bulleted
list; also ensure there's a blank line after the list per docs style. Update the
paragraph containing that sentence in
docs/execplans/7-2-1-define-stable-jsonl-request-and-response-schemas-for-observe-graph-slice.md
so the intro is one continuous sentence and the list is separated by blank
lines.

In `@docs/rust-testing-with-rstest-fixtures.md`:
- Line 1349: The table row for the attribute #[rstest] uses the incorrect
indefinite article "an"; update the text to "Marks a function as a rstest test;
enables fixture injection and parameterization." by replacing "an rstest test"
with "a rstest test" in the docs/rust-testing-with-rstest-fixtures.md entry for
#[rstest], and ensure the change follows the repository's en-GB Oxford
spelling/documentation style.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cfca8538-f426-4ca9-879c-61cf70d576c6

📥 Commits

Reviewing files that changed from the base of the PR and between 96f347e and 5072985.

📒 Files selected for processing (55)

• AGENTS.md
• docs/archive/prototype-roadmap.md
• docs/complexity-antipatterns-and-refactoring-strategies.md
• docs/contents.md
• docs/developers-guide.md
• docs/documentation-style-guide.md
• docs/execplans/13-3-3-archive-3-2-2-daemon-start-help-guidance.md
• docs/execplans/2-2-1-act-apply-patch-sub-command.md
• docs/execplans/2-2-2-list-all-domains-in-top-level-help.md
• docs/execplans/2-2-3-top-level-version-output.md
• docs/execplans/2-2-4-provide-contextual-domain-guidance.md
• docs/execplans/2-3-1-validate-domains-client-side-before-daemon-startup.md
• docs/execplans/2-3-2-valid-operation-alternatives-for-unknown-operations.md
• docs/execplans/2-3-3-standardize-actionable-guidance-in-startup-errors.md
• docs/execplans/2-3-4-return-argument-requirements-for-act-refactor.md
• docs/execplans/3-1-1a-plugin-for-rope.md
• docs/execplans/3-1-1b-plugin-for-rust-analyzer.md
• docs/execplans/3-2-1-surface-configuration-flags-in-clap-help-output.md
• docs/execplans/4-1-1-scaffold-sempai-core-and-sempai.md
• docs/execplans/4-1-2-structured-diagnostics-with-stable-error-codes.md
• docs/execplans/4-1-3-yaml-rule-parsing-via-saphyr-and-serde-saphyr.md
• docs/execplans/4-1-4-mode-aware-sempai-validation.md
• docs/execplans/4-1-5-normalization-into-canonical-formula-model.md
• docs/execplans/5-1-1-entry-help.md
• docs/execplans/5-2-1-define-the-rename-symbol-capability-contract.md
• docs/execplans/5-2-2-update-weaver-plugin-rope-manifest.md
• docs/execplans/5-2-3-update-rust-plugin-to-declare-rename-symbol.md
• docs/execplans/5-2-4-daemon-capability-resolution-for-rename-symbol.md
• docs/execplans/5-2-5-unit-behavioural-and-end-to-end-coverage-for-rename-symbol.md
• docs/execplans/7-1-1-stable-jsonl-schemas-for-observe-get-card.md
• docs/execplans/7-1-2-tree-sitter-symbol-card-extraction.md
• docs/execplans/7-1-3-implement-optional-lsp-enrichment-for-observe-get-card.md
• docs/execplans/7-1-4-cache-integration-for-card-extraction-keyed-by-uri.md
• docs/execplans/7-2-1-define-stable-jsonl-request-and-response-schemas-for-observe-graph-slice.md
• docs/execplans/adopt-ortho-config-v0-8-0.md
• docs/execplans/phase-1-implement-the-socket-listener-in-weaverd.md
• docs/execplans/sempai-design.md
• docs/execplans/weaver-agent-roadmap.md
• docs/formal-verification-methods-in-weaver.md
• docs/jacquard-card-first-symbol-graph-design.md
• docs/ortho-config-users-guide.md
• docs/pratt-parser-for-ddlog-expressions.md
• docs/reliable-testing-in-rust-via-dependency-injection.md
• docs/repository-layout.md
• docs/rfcs/0001-o11y.md
• docs/roadmap.md
• docs/rstest-bdd-users-guide.md
• docs/rust-doctest-dry-guide.md
• docs/rust-extricate-actuator-plugin-technical-design.md
• docs/rust-parser-testing-comprehensive-guide.md
• docs/rust-testing-with-rstest-fixtures.md
• docs/semgrep-language-reference/semgrep-minimal-examples.md
• docs/sempai-query-language-design.md
• docs/users-guide.md
• docs/weaver-design.md