13b03d6edf
## Mode guards and convergence loops (ADR-011)
- `Guard` and `Converge` types added to `reflection/schema.ncl` and
`reflection/defaults.ncl`. Guards run pre-flight checks (Block/Warn);
converge loops iterate until a condition is met (RetryFailed/RetryAll).
- `sync-ontology.ncl`: 3 guards + converge (zero-drift condition, max 2 iter).
- `coder-workflow.ncl`: guard (coder-dir-exists) + `novelty-check` step.
- Rust types in `ontoref-reflection/src/mode.rs`; executor in `executor.rs`
evaluates guards before steps and convergence loop after.
- `adrs/adr-011-mode-guards-and-convergence.ncl` added.
## Manifest capability completeness
- `.ontology/manifest.ncl`: 3 → 19 declared capabilities covering the full
action surface (daemon API, modes, Task Composer, QA, bookmarks, etc.).
- `sync.nu`: `audit-manifest-coverage` + `sync manifest-check` command.
- `validate-project.ncl`: 6th category `manifest-cov`.
- Pre-commit hook `manifest-coverage` added.
- Migrations `0010-manifest-capability-completeness`,
`0011-manifest-coverage-hooks`.
## Rust doc authoring pattern — canonical `///` convention
- `#[onto_api]`: `description = "..."` optional when `///` doc comment exists
above handler — first line used as fallback. `#[derive(OntologyNode)]` same.
- `ontoref-daemon/src/api.rs`: 42 handlers migrated to `///` doc comments;
`description = "..."` removed from all `#[onto_api]` blocks.
- `sync diff --docs --fail-on-drift`: exits 1 on crate `//!` drift; used by
new `docs-drift` pre-commit hook. `docs-links` hook checks rustdoc broken links.
- `generator.nu`: mdBook `crates/` chapter — per-crate page from `//!` doc,
coverage badge, feature flags, implementing practice nodes.
- `.claude/CLAUDE.md`: `### Documentation Authoring (Rust)` section added.
- Migration `0012-rust-doc-authoring-pattern`.
## OntologyNode derive fixes
- `#[derive(OntologyNode)]`: `name` and `paths` attributes supported; `///`
doc fallback for `description`; `artifact_paths` correctly populated.
- `Core::from_value` calls `merge_contributors()` behind `#[cfg(feature = "derive")]`.
## Bug fixes
- `sync.nu` drift check: exact crate path match (not `str starts-with`);
first-path-only rule; split on `. ` not `.` to avoid `.ontology/` truncation.
- `find-unclaimed-artifacts`: fixed absolute vs relative path comparison.
- Rustdoc broken intra-doc links fixed across all three crates.
- `ci-docs` recipe now sets `RUSTDOCFLAGS` and actually fails on errors.
mode guards/converge, manifest coverage validation, 19 capabilities (ADR-011)
Extend the mode schema with Guard (pre-flight Block/Warn checks) and Converge
(RetryFailed/RetryAll post-execution loops) — protocol pushes back on invalid
state and iterates until convergence. ADR-011 records the decision to extend
modes rather than create a separate action subsystem.
Manifest expanded from 3 to 19 capabilities covering the full action surface
(compose, plans, backlog graduation, notifications, coder pipeline, forms,
templates, drift, quick actions, migrations, config, onboarding). New
audit-manifest-coverage validator + pre-commit hook + SessionStart hook
ensure agents always see complete project self-description.
Bug fix: find-unclaimed-artifacts absolute vs relative path comparison —
19 phantom MISSING items resolved. Health 43% → 100%.
Anti-slop: coder novelty-check step (Jaccard overlap against published+QA)
inserted between triage and publish in coder-workflow.
Justfile restructured into 5 modules (build/test/dev/ci/assets).
Migrations 0010-0011 propagate requirements to consumer projects.
81 lines
3.5 KiB
Plaintext
81 lines
3.5 KiB
Plaintext
{
|
|
id = "0012",
|
|
slug = "rust-doc-authoring-pattern",
|
|
description = "Add Documentation Authoring (Rust) section to .claude/CLAUDE.md and optional pre-commit hooks for rustdoc broken links and crate //! drift detection.",
|
|
check = {
|
|
tag = "Grep",
|
|
pattern = "Documentation Authoring",
|
|
paths = [".claude/CLAUDE.md"],
|
|
must_be_empty = false,
|
|
},
|
|
instructions = "
|
|
## 1. Add to .claude/CLAUDE.md
|
|
|
|
Insert the following section under '## Key Conventions' (or equivalent conventions block).
|
|
Create .claude/CLAUDE.md if it does not exist.
|
|
|
|
### Documentation Authoring (Rust)
|
|
|
|
Three canonical doc layers — each answers a different question:
|
|
|
|
Layer | Where | Answers
|
|
-------------------|------------------|------------------------------------------
|
|
/// on items | handlers, types | \"what does this item do?\"
|
|
//! in lib.rs | crate root | \"what does this crate provide as a whole?\"
|
|
node description | .ontology/ | \"what is this concept in the architecture?\"
|
|
|
|
Rules that apply to every .rs file:
|
|
|
|
1. /// first line = one standalone sentence. No 'This function/handler/struct...' preamble.
|
|
This line becomes the API catalog entry, describe features summary, and MCP description.
|
|
Further lines after a blank /// are detail and do not appear in catalogs.
|
|
|
|
2. //! first sentence must be conceptually aligned with the practice node whose
|
|
artifact_paths[0] points to this crate. Run `ontoref sync diff --docs` to verify.
|
|
|
|
3. Omit `description = \"...\"` in #[onto_api] when a /// doc comment exists above the handler.
|
|
The proc-macro reads /// automatically. Only use explicit description = \"...\" for
|
|
generated or macro-expanded handlers that cannot carry ///.
|
|
|
|
4. //! is mandatory on every lib.rs. Missing //! on a crate with a practice node
|
|
fails the docs-drift pre-commit check.
|
|
|
|
Agent workflow — discovering doc state:
|
|
ontoref describe workspace # per-crate //! present?, coverage %, drift status
|
|
ontoref describe features <id> # node description + IMPLEMENTATION VIEW (//! excerpt)
|
|
ontoref sync diff --docs # explicit drift report before committing
|
|
|
|
Registering a new crate as a practice implementation:
|
|
1. Add/update a Practice node in .ontology/core.ncl with artifact_paths = [\"crates/my-crate/\"]
|
|
2. Write //! in crates/my-crate/src/lib.rs — first sentence aligned with the node description
|
|
3. Run `ontoref sync diff --docs` to confirm Jaccard OK
|
|
4. Run `ontoref generate-mdbook` — a docs/src/crates/my-crate.md page is generated
|
|
|
|
|
|
## 2. Add pre-commit hooks (Rust projects only)
|
|
|
|
Skip this step if the project has no Rust crates.
|
|
|
|
Add to .pre-commit-config.yaml in the local hooks section (alongside rust-clippy / rust-test):
|
|
|
|
- id: docs-links
|
|
name: Rustdoc broken intra-doc links
|
|
entry: bash -c 'RUSTDOCFLAGS=\"-D rustdoc::broken-intra-doc-links -D rustdoc::private-intra-doc-links\" cargo doc --no-deps --workspace -q'
|
|
language: system
|
|
types: [rust]
|
|
pass_filenames: false
|
|
stages: [pre-commit]
|
|
|
|
- id: docs-drift
|
|
name: Crate //! doc drift check
|
|
entry: bash -c 'nu -c \"use ./reflection/modules/sync.nu; sync diff --docs --fail-on-drift\"'
|
|
language: system
|
|
types: [rust]
|
|
pass_filenames: false
|
|
stages: [pre-commit]
|
|
|
|
docs-drift only fires meaningfully when the project has Practice nodes with artifact_paths
|
|
pointing to Rust crate directories. If no such nodes exist, the hook exits 0 silently.
|
|
",
|
|
}
|