pulseengine · avrabe · May 21, 2026 · May 21, 2026 · May 21, 2026 · May 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,72 @@
 
 ## [Unreleased]
 
+## [0.11.0] — 2026-05-21
+
+Theme: **the cross-git investigation**. A 2026-05-19 investigation
+(six adversarial personas, ten scenarios, three test-bed repos in
+different orgs) found eleven ways `rivet validate` could report a
+green PASS while the project was, in fact, broken — the Cederqvist
+"the tool reports textual success over a semantically-failed
+operation" cliff. The findings were filed as typed Rivet artifacts
+(FEAT-135, REQ-062..REQ-077) and closed across three waves. Minor
+version: new flags and validation behaviour, no breaking schema or
+CLI removal — but `rivet validate` is now stricter (it fails on
+inputs it previously skipped silently), so a project that "passed"
+on 0.10.x may legitimately FAIL on 0.11.0. That is the fix working.
+
+### Added
+
+- `rivet validate --with-externals-validate` — runs validate inside
+  each linked external project and surfaces its diagnostics under a
+  `cross_repo_diagnostics` array (REQ-065).
+- `rivet validate --strict-orphans` — promote `orphan-artifact`
+  warnings to errors for CI (REQ-076).
+- `rivet supplier pull --accept-drift` — the explicit auditor
+  override for sha256 drift (REQ-068).
+- `rivet docs cross-repo-ci` — a new topic: the multi-repo CI
+  sequence, a worked GitHub Actions example, the AoU register
+  (REQ-071).
+- `docs/rivet-is-not.md` — an ISO 26262-10 SEooC Safety-Manual-draft
+  "Rivet is not..." doc with the Cross-org Assumptions-of-Use
+  register AoU-X1..X7 (REQ-072), linked from the README.
+- `external-anchor` schema now declares the `cited-source` field
+  (REQ-066); `docs/historical/` archive + `docs/README.md`.
+
+### Fixed
+
+- **`rivet validate` reported `PASS` over artifact files that failed
+  to parse** — the skip was a stderr log line, uncounted. Skipped
+  files are now Error diagnostics (`artifact-parse-error`) and the
+  run exits non-zero (REQ-062). The headline finding.
+- **Duplicate artifact IDs** silently collapsed via `Store::upsert`
+  last-write-wins — now detected at load time (`duplicate-artifact-id`,
+  REQ-075). The new check immediately surfaced a real `REQ-060`
+  collision in Rivet's own `artifacts/` (resolved → `REQ-077`).
+- **Orphan artifacts** (no inbound/outbound links) were invisible to
+  `rivet validate` — now reported (`orphan-artifact`, Warning;
+  REQ-076).
+- `rivet init --preset {do-178c, en-50128, iec-61508, iec-62304}`
+  produced unvalidatable projects — the four safety-critical schemas
+  are now embedded in the binary (REQ-063).
+- A `derives-from-external` link did not satisfy a required
+  `derives-from` link-field — the cross-org variant now counts
+  (REQ-064).
+- `rivet supplier pull` silently overwrote the cache on sha256
+  drift — it now refuses, naming both hashes (REQ-068).
+- Stale documentation: MSRV (1.85 → 1.89), the schema/oracle/module
+  counts in `schemas.md` / `architecture.md` / `oracles.md` (REQ-074).
+
+### Changed
+
+- `rivet validate --format json` diagnostics now include the `rule`
+  field.
+- 17 stale planning docs archived to `docs/historical/`;
+  `docs/historical/` is doc-check-exempt like `plans/` / `design/`.
+- The `rivet docs cross-repo` topic now documents both cross-repo
+  mechanisms (`externals:` vs `external-anchor` + `cited-source`)
+  and when to use each (REQ-067).
+
 ## [0.10.1] — 2026-05-19
 
 Theme: **adversarial-review action items + user-reported regressions**.

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -7,7 +7,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.10.1"
+version = "0.11.0"
 authors = ["PulseEngine <https://github.com/pulseengine>"]
 edition = "2024"
 license = "Apache-2.0"

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,80 @@
+---
+id: DOC-DOCS-README
+title: docs/ folder map and lifecycle
+type: reference
+status: current
+tags: [docs, structure, lifecycle, governance]
+---
+
+# `docs/` — folder map and lifecycle
+
+This directory holds Rivet's prose documentation. The top level (`docs/*.md`)
+carries the stable, user-facing reference and guide material; four
+subdirectories carry material with a more specific lifecycle. Every `.md` file
+directly under `docs/` carries YAML frontmatter (`id`, `title`, `type`,
+`status`, `tags`) so it is a first-class document artifact — `rivet validate`
+skips files without frontmatter and reports them. Per the doc scanner's
+`read_dir` contract, only the top level of each `docs:` path is scanned for
+frontmatter; subdirectory files are not gated, but carrying frontmatter is
+still recommended.
+
+The `status` field is the lifecycle marker. The intended values:
+
+- `current` — describes shipped behaviour and is believed accurate against the
+  current release. The default state for reference and guide material.
+- `snapshot` — a point-in-time record (an audit, a comparison, a status page).
+  Accurate as of its date; not maintained to track `main`.
+- `draft` — work in progress; not yet a settled description of anything.
+- `historical` — superseded planning or analysis kept for the record. Lives
+  under `docs/historical/`.
+
+## Top level — `docs/*.md`
+
+Stable, user-facing reference and guide material: `getting-started.md`,
+`architecture.md`, `schemas.md`, `oracles.md`, `feature-model-schema.md`,
+`feature-model-bindings.md`, `pre-commit.md`, `mutation-testing.md`,
+`verification.md`, `srs.md`, `stpa-sec.md`, plus the positioning documents
+(`what-is-rivet.md`, `rivet-is-not.md`, `intro-talk-*.md`). These are the docs
+a reader is expected to land on. They are maintained to track `main`; when they
+drift, they get a `status: snapshot` demotion or an `UPDATE` verdict in the
+next docs audit. **Lifecycle:** long-lived; updated in place; never deleted
+while the feature they describe ships.
+
+## `design/`
+
+Forward-looking design notes — RFC-style decision documents for a single
+feature track (status-gate rules, variant-aware properties, the
+tool-confidence-level dossier, cross-org supplier traceability, …). A design
+doc is written before or during implementation and is rarely revisited once the
+feature ships; it stays as a decision record. Design docs may carry the
+`<!-- rivet-docs-check: design-doc-aspirational-ok -->` marker, which exempts
+them from the documentation invariants that gate shipped reference docs.
+**Lifecycle:** authored once per feature track; kept as a decision record;
+archived to `historical/` only when wholly superseded.
+
+## `plans/`
+
+In-flight implementation plans — current work only. A plan describes a body of
+work that has not yet landed. Once the work ships, the plan has served its
+purpose and moves to `historical/`. This directory should be near-empty most of
+the time; a long-lived plan is a signal that the work stalled or that the
+document is really a design note in the wrong folder. **Lifecycle:** short;
+created for in-flight work, moved to `historical/` on completion.
+
+## `research/`
+
+Scoped research reports with explicit verdicts — competitive analysis,
+feasibility spikes, prototype reports, the cross-git investigation, the docs
+audits. A research report is a `snapshot` by nature: it is accurate as of its
+date and is not maintained afterwards. Negative results belong here too and are
+treated as first-class (e.g. the MIRAI prototype report). **Lifecycle:** each
+report is written once, dated, and frozen as a `snapshot`; old reports are kept
+for the record rather than updated.
+
+## `historical/`
+
+The dated archive of completed plans and superseded analysis. Nothing here is
+maintained; documents land here when their `design/` or `plans/` originals are
+overtaken by shipped work or by a newer document. Keeping them (rather than
+deleting) preserves the project's decision history for auditors. **Lifecycle:**
+write-once on arrival; `status: historical`; never updated, never deleted.
diff --git a/docs/adoption-status.md b/docs/adoption-status.md
@@ -1,3 +1,11 @@
+---
+id: DOC-ADOPTION-STATUS
+title: rivet-validate adoption status
+type: status
+status: snapshot
+tags: [adoption, status, audit, dogfood]
+---
+
 # `rivet-validate` adoption status
 
 This file records the most recent run of

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -67,32 +67,98 @@ root: RivetSystem::RivetCli.Impl
 
 ### 2.1 rivet-core Modules
 
+The library crate has grown well beyond the original core set. The table below groups the
+modules by concern; consult `ls rivet-core/src/` for the authoritative file list.
+
+**Artifact model and storage**
+
 | Module       | Purpose                                                          |
 |--------------|------------------------------------------------------------------|
 | `model`      | Core data types: `Artifact`, `Link`, `ProjectConfig`, `SourceConfig` |
 | `store`      | In-memory artifact store with by-ID and by-type indexing         |
 | `schema`     | Schema loading, merging, artifact type and link type definitions |
 | `links`      | `LinkGraph` construction via petgraph, backlinks, orphan detection |
+| `document`   | Markdown documents with YAML frontmatter and wiki-link references |
+| `results`    | Test run results model, YAML loading, and `ResultStore`          |
+
+**Validation, coverage, and analysis**
+
+| Module       | Purpose                                                          |
+|--------------|------------------------------------------------------------------|
 | `validate`   | Validation engine: types, fields, cardinality, traceability rules |
 | `coverage`   | Traceability coverage computation per rule                       |
+| `coverage_evidence` | Coverage-to-evidence cross-checking                        |
 | `matrix`     | Traceability matrix computation (forward and backward)           |
 | `query`      | Query engine: filter artifacts by type, status, tag, link presence |
 | `diff`       | Artifact diff and diagnostic diff between two store snapshots    |
-| `document`   | Markdown documents with YAML frontmatter and wiki-link references |
-| `results`    | Test run results model, YAML loading, and `ResultStore`          |
-| `adapter`    | Adapter trait and configuration for import/export                |
-| `reqif`      | ReqIF 1.2 XML import/export adapter                             |
-| `oslc`       | OSLC client for discovery, query, CRUD, and sync (feature-gated) |
+| `impact`     | Change-impact analysis between store snapshots                   |
+| `convergence`| Convergence / gap-closure tracking                               |
+| `doc_check`  | Documentation invariants (`rivet docs check`) over `.md` bodies  |
+| `lifecycle`  | Artifact status lifecycle transitions and gating                 |
+| `compliance` | Compliance-report computation across domain schemas              |
+
+**Incremental engine (rowan + salsa)**
+
+| Module        | Purpose                                                         |
+|---------------|-----------------------------------------------------------------|
+| `db`          | salsa database: tracked queries and incremental revalidation    |
+| `yaml_cst`    | Lossless YAML concrete syntax tree (rowan)                      |
+| `yaml_hir`    | Higher-level YAML IR: artifact / link extraction from the CST   |
+| `yaml_edit`   | Structure-preserving YAML edits for `rivet add` / `modify`      |
+| `sexpr`       | S-expression parser for `validation-rules:` / status gates      |
+| `sexpr_eval`  | S-expression evaluator against the artifact store               |
+
+**Cross-repo, variants, and provenance**
+
+| Module          | Purpose                                                       |
+|-----------------|---------------------------------------------------------------|
+| `externals`     | Cross-repo `externals:` resolution, `git clone`/`fetch`, lock |
+| `baseline`      | Named baseline tags and baseline-scoped validation            |
+| `snapshot`      | Point-in-time store snapshots for diff / impact               |
+| `feature_model` | Feature-model parsing and SAT-style constraint checking       |
+| `variant_emit`  | Variant-resolved artifact emission                            |
+| `commits`       | Git commit-trailer parsing and commit-to-artifact coverage    |
+| `cited_source`  | `cited-source` hash tracking and drift detection              |
+| `ownership`     | Artifact ownership / `CODEOWNERS`-style attribution           |
+
+**Mutation, formats, and integration**
+
+| Module         | Purpose                                                        |
+|----------------|----------------------------------------------------------------|
+| `mutate`       | Schema-validated artifact mutation (`add`, `modify`, `link`, …) |
+| `adapter`      | Adapter trait and configuration for import/export              |
+| `reqif`        | ReqIF 1.2 XML import/export adapter                            |
+| `oslc`         | OSLC client library (not exposed as a CLI subcommand — see §7) |
 | `wasm_runtime` | WASM component adapter runtime (feature-gated)                 |
-| `error`      | Unified error type for the library                               |
-| `formats/`   | Format-specific adapters: `generic` (YAML), `stpa` (STPA YAML)  |
+| `bazel`        | MODULE.bazel parsing for build-system-aware cross-repo discovery|
+| `mcp`          | Model Context Protocol server primitives                       |
+| `export`       | HTML / Zola static-site export                                 |
+| `embed`        | `{{stats:}}` / `{{coverage:}}` embed expansion in doc bodies   |
+| `verus_specs`  | Verus specification scaffolding for formal verification        |
+| `proofs`       | Proof-artifact tracking (Kani / Verus / Rocq)                  |
+| `formats/`     | Format-specific adapters: `generic` (YAML), `aadl`, `needs_json`|
+| `error`        | Unified error type for the library                             |
+
+This is a representative grouping, not an exhaustive file list; smaller support modules
+(`agent_pipelines`, `test_scanner`, `runs`, `templates`, `migrate`, `bundle`, …) round
+out the crate.
 
 ### 2.2 rivet-cli Modules
 
-| Module  | Purpose                                                              |
-|---------|----------------------------------------------------------------------|
-| `main`  | CLI entry point, clap argument parsing, subcommand dispatch          |
-| `serve` | axum HTTP server with HTMX-rendered dashboard pages                  |
+| Module          | Purpose                                                       |
+|-----------------|---------------------------------------------------------------|
+| `main`          | CLI entry point, clap argument parsing, subcommand dispatch   |
+| `check`         | Oracle subcommands (`rivet check ...`) — see `docs/oracles.md`|
+| `close_gaps`    | `rivet close-gaps` gap-closure driver                         |
+| `docs`          | `rivet docs <topic>` / `rivet docs check` documentation tools |
+| `mcp`           | `rivet mcp` Model Context Protocol server entry point         |
+| `serve`         | axum HTTP server with HTMX-rendered dashboard pages           |
+| `render`        | Server-side HTML rendering helpers for `serve`                |
+| `schema_cmd`    | `rivet schema` inspection subcommands                         |
+| `pipelines_cmd` | `rivet pipelines` agent-pipeline runner                       |
+| `runs_cmd`      | `rivet runs` evidence-run management                          |
+| `migrate_cmd`   | `rivet schema migrate` schema-migration subcommand            |
+| `templates_cmd` | `rivet templates` scaffold subcommand                         |
 
 ## 3. Data Flow
 
@@ -147,17 +213,24 @@ This design is specified by [[REQ-010]] and [[DD-003]].
 ### 3.2 Adapter Pipeline
 
 Adapters implement the `Adapter` trait, which defines `import()` and
-`export()` methods. Three native adapters exist:
+`export()` methods. The native adapters under `rivet-core/src/formats/` are:
 
-1. **GenericYamlAdapter** -- Canonical YAML format with explicit type, links
+1. **GenericYamlAdapter** (`generic`) -- Canonical YAML format with explicit type, links
    array, and fields map. Used for Rivet's own artifacts.
-2. **StpaYamlAdapter** -- Imports STPA analysis artifacts from the meld
-   project's YAML format (losses, hazards, UCAs, etc.).
-3. **ReqIfAdapter** -- Import/export for OMG ReqIF 1.2 XML, enabling
-   interchange with DOORS, Polarion, and codebeamer ([[REQ-005]]).
+2. **AadlAdapter** (`aadl`) -- Imports AADL architecture models (components, flows,
+   analysis results) for the architecture-level traceability bridge.
+3. **NeedsJsonAdapter** (`needs_json`) -- Imports sphinx-needs `needs.json` exports with
+   configurable type mapping ([[REQ-025]]).
 
-The WASM adapter runtime ([[DD-004]]) and OSLC sync adapter ([[DD-001]])
-extend this pipeline for plugin formats and remote tool synchronization.
+Two further adapters live alongside the format adapters: the **ReqIfAdapter**
+(`rivet-core/src/reqif.rs`) for OMG ReqIF 1.2 XML import/export ([[REQ-005]], enabling
+interchange with DOORS, Polarion, and codebeamer), and the WASM adapter runtime
+([[DD-004]]) for plugin formats.
+
+The `oslc` module ([[DD-001]]) is a client *library* for OSLC discovery, query, and CRUD;
+it is **not** wired to a `rivet` CLI subcommand. OSLC has no command-line
+surface today — neither an `oslc` subcommand nor an `--oslc` flag on
+`sync` — see §7.
 
 ```aadl
 root: RivetAdapters::WasmRuntime.Impl
@@ -266,13 +339,21 @@ traceability-rules:
 
 ### 5.2 Available Schemas
 
-| Schema          | Types | Link Types | Rules | Domain                         |
-|-----------------|-------|------------|-------|--------------------------------|
-| `common`        | 0     | 9          | 0     | Base fields and link types     |
-| `dev`           | 3     | 1          | 2     | Development tracking           |
-| `stpa`          | 10    | 5          | 7     | STPA safety analysis           |
-| `aspice`        | 14    | 2          | 10    | ASPICE v4.0 V-model            |
-| `cybersecurity` | 10    | 2          | 10    | SEC.1-4, ISO/SAE 21434         |
+The `schemas/` directory ships a catalogue of domain schemas — STPA, ASPICE 4.0,
+ISO 26262, ISO/PAS 8800, SOTIF, DO-178C, EN 50128, IEC 61508, IEC 62304, the EU AI Act,
+GSN safety cases, AADL, Eclipse SCORE, supply-chain — plus a set of *bridge* schemas that
+declare cross-domain link types. The structurally distinct examples are summarised below;
+the canonical inventory is `docs/schemas.md` and, ultimately, `schemas/*.yaml` itself.
+
+| Schema          | Domain                         |
+|-----------------|--------------------------------|
+| `common`        | Base fields and link types     |
+| `dev`           | Development tracking           |
+| `stpa`          | STPA safety analysis           |
+| `aspice`        | ASPICE v4.0 V-model            |
+| `cybersecurity` | SEC.1-4, ISO/SAE 21434         |
+
+See `docs/schemas.md` for the full domain and bridge-schema catalogue.
 
 ### 5.3 Merge Semantics
 
@@ -298,7 +379,10 @@ dashboard alongside artifacts they verify.
 
 This architecture reflects the following key decisions:
 
-- [[DD-001]] -- OSLC over per-tool REST adapters for external tool sync
+- [[DD-001]] -- OSLC over per-tool REST adapters for external tool sync. The decision
+  stands and the `oslc` client library exists, but OSLC is **not** exposed as a CLI
+  subcommand in the current release; `rivet --help` has no `oslc` entry. See
+  `docs/plans/2026-03-16-oslc-analysis.md` for the deliberate non-shipping rationale.
 - [[DD-002]] -- petgraph for link graph operations
 - [[DD-003]] -- Mergeable YAML schemas for domain composition
 - [[DD-004]] -- WIT-based WASM adapter interface for plugins

diff --git a/docs/feature-model-bindings.md b/docs/feature-model-bindings.md
@@ -1,3 +1,11 @@
+---
+id: DOC-FEATURE-MODEL-BINDINGS
+title: Feature Binding File Format
+type: reference
+status: current
+tags: [reference, variant, feature-model, bindings]
+---
+
 # Feature Binding File Format
 
 A binding file maps features from the feature model to the artifacts and