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.
134 lines
8.0 KiB
Plaintext
134 lines
8.0 KiB
Plaintext
let d = import "../ontology/defaults/state.ncl" in
|
||
|
||
{
|
||
dimensions = [
|
||
|
||
d.make_dimension {
|
||
id = "protocol-maturity",
|
||
name = "Protocol Maturity",
|
||
description = "Completeness of the ontoref protocol specification — schemas, ADRs, modes, Rust crates, daemon, and adoption tooling.",
|
||
current_state = "adoption-tooling-complete",
|
||
desired_state = "protocol-stable",
|
||
horizon = 'Months,
|
||
states = [],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = "tooling-migrated",
|
||
to = "adoption-tooling-complete",
|
||
condition = "adopt_ontoref mode, templates, daemon crate, landing page all present and validated.",
|
||
catalyst = "Daemon extracted from stratumiops; adoption templates created.",
|
||
blocker = "none",
|
||
horizon = 'Months,
|
||
},
|
||
d.make_transition {
|
||
from = "adoption-tooling-complete",
|
||
to = "protocol-stable",
|
||
condition = "ADR-001 accepted, ontoref.dev published, at least two external projects consuming the protocol.",
|
||
catalyst = "10 projects consuming the protocol: vapora, stratumiops, kogral, typedialog, secretumvault, rustelo, librecloud_renew, website-impl, jpl_ontology, provisioning. ADR-001 Accepted. Auth model, install pipeline, personal/career schemas, content modes, API catalog (#[onto_api], ADR-007), config surface (ADR-008), manifest self-interrogation (ADR-009), protocol migration system (ADR-010), mode guards and convergence (ADR-011) all complete. Session 2026-03-30: manifest expanded to 19 capabilities; manifest coverage validation (audit + pre-commit + SessionStart); 3 new migrations (0010-0012).",
|
||
blocker = "ontoref.dev not yet published.",
|
||
horizon = 'Months,
|
||
},
|
||
],
|
||
},
|
||
|
||
d.make_dimension {
|
||
id = "self-description-coverage",
|
||
name = "Self-Description Coverage",
|
||
description = "How completely ontoref describes itself using its own protocol.",
|
||
current_state = "fully-self-described",
|
||
desired_state = "fully-self-described",
|
||
horizon = 'Weeks,
|
||
states = [],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = ".ontology-bootstrapped",
|
||
to = "modes-and-web-present",
|
||
condition = "adopt_ontoref mode, landing page, and all core.ncl nodes reflect current artifact set.",
|
||
catalyst = "Web presence and adoption tooling added in session 2026-03-12.",
|
||
blocker = "none",
|
||
horizon = 'Weeks,
|
||
},
|
||
d.make_transition {
|
||
from = "modes-and-web-present",
|
||
to = "fully-self-described",
|
||
condition = "At least 3 ADRs accepted, reflection/backlog.ncl present, describe project returns complete picture.",
|
||
catalyst = "ADR-001–ADR-006 authored (6 ADRs present). Auth model, project onboarding, and session management nodes added in 2026-03-13. Personal/career/project-card schemas, 5 content modes, search bookmarks, and ADR-006 (Nu 0.111 compat) added in session 2026-03-15. Session 2026-03-23: api-catalog-surface node added (#[onto_api] proc-macro + inventory catalog), describe-query-layer updated (diff + api subcommands), adopt-ontoref-tooling updated (update_ontoref mode + manifest/connections templates + enrichment prompt), ontoref-daemon updated (11 pages, 29 MCP tools, per-file versioning, API catalog endpoint). Session 2026-03-26: config-surface node added — typed DaemonNclConfig (parse-at-boundary pattern), #[derive(ConfigFields)] coherence registry, override-layer mutation API (PUT /config/{section}), NCL contracts (.ontoref/contracts.ncl: LogConfig + DaemonConfig), manifest config_surface with multi-consumer sections. ADR-007 (inventory/onto_api) extended to ConfigFields; ADR-008 (NCL-first config validation + override-layer mutation). Session 2026-03-26 (2nd): manifest-self-description node added. ADR-009. Session 2026-03-29: browser-style panel navigation. Session 2026-03-30: manifest expanded 3→19 capabilities (complete action surface: modes, compose, plans, backlog graduation, notifications, coder pipeline, forms, templates, drift, quick actions, migration, config, search bookmarks, onboarding, web presence). audit-manifest-coverage validator + pre-commit hook + SessionStart hook. Mode schema extended: Guard type (Block/Warn severity pre-flight checks), Converge type (RetryFailed/RetryAll post-execution loops). ADR-011. Migrations 0010-0012. Bug fix: find-unclaimed-artifacts absolute vs relative path comparison. Justfile split (build/test/dev/ci/assets). Anti-slop novelty-check in coder pipeline (Jaccard overlap against published+QA). Health 43%→100%.",
|
||
blocker = "none",
|
||
horizon = 'Weeks,
|
||
},
|
||
],
|
||
},
|
||
|
||
d.make_dimension {
|
||
id = "ecosystem-integration",
|
||
name = "Ecosystem Integration",
|
||
description = "Degree to which other ecosystem projects (stratumiops, syntaxis, vapora, kogral) consume the ontoref protocol.",
|
||
current_state = "stratumiops-integrated",
|
||
desired_state = "multi-project",
|
||
horizon = 'Months,
|
||
coupled_with = ["protocol-maturity"],
|
||
states = [],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = "source-only",
|
||
to = "stratumiops-integrated",
|
||
condition = "stratumiops has .ontoref/config.ncl and scripts/ontoref wrapper functional; ADR-007 marked Superseded pointing to ontoref:adr-002.",
|
||
catalyst = "Ontoref extraction and stratumiops migration session 2026-03-12.",
|
||
blocker = "none",
|
||
horizon = 'Months,
|
||
},
|
||
d.make_transition {
|
||
from = "stratumiops-integrated",
|
||
to = "multi-project",
|
||
condition = "At least one additional project (vapora, kogral, or syntaxis) has .ontoref/config.ncl and scripts/ontoref. Syntaxis parses ontoref Core type.",
|
||
catalyst = "Syntaxis integration spike or vapora/kogral onboarding.",
|
||
blocker = "Syntaxis syntaxis-ontology crate has ES→EN migration errors pending. vapora/kogral not yet initialized with .ontoref/.",
|
||
horizon = 'Months,
|
||
},
|
||
],
|
||
},
|
||
|
||
d.make_dimension {
|
||
id = "operational-mode",
|
||
name = "Operational Mode",
|
||
description = "Runtime connectivity mode: local (files only) or daemon (push-based DB projection). Auto-detected on each command; transitions trigger hook updates and sync. Daemon launched via ADR-004 NCL pipe bootstrap (ontoref-daemon-boot); NATS topology resolved from NATS_STREAMS_CONFIG env var (global ~/.config/ontoref/streams.json) or project-local nats/streams.json.",
|
||
current_state = "local",
|
||
desired_state = "daemon",
|
||
horizon = 'Continuous,
|
||
states = [
|
||
d.make_state {
|
||
id = "local",
|
||
name = "Local",
|
||
description = "No daemon. All operations read from files. Hooks are no-ops. Safe for offline or repo-only work.",
|
||
tension = 'Low,
|
||
},
|
||
d.make_state {
|
||
id = "daemon",
|
||
name = "Daemon",
|
||
description = "Daemon reachable. Ontology projected into DB on each sync. Hooks push on git merge/checkout. NATS events available.",
|
||
tension = 'Low,
|
||
},
|
||
],
|
||
transitions = [
|
||
d.make_transition {
|
||
from = "local",
|
||
to = "daemon",
|
||
condition = "Daemon reachable at ONTOREF_DAEMON_URL and DB available (if db feature enabled).",
|
||
catalyst = "Daemon started, network restored, or first onboarding after install.",
|
||
blocker = "Daemon not running or DB not configured.",
|
||
horizon = 'Continuous,
|
||
},
|
||
d.make_transition {
|
||
from = "daemon",
|
||
to = "local",
|
||
condition = "Daemon unreachable or DB unavailable.",
|
||
catalyst = "Network loss, daemon stopped, or offline work.",
|
||
blocker = "none",
|
||
horizon = 'Continuous,
|
||
},
|
||
],
|
||
},
|
||
|
||
],
|
||
}
|