Organize RAVEL navigation and evidence documentation

README.md

@@ -87,7 +87,7 @@ or offline MNCS/MNCDS validation and cannot create independent or protected evid
 - [Multilingual Stream](case-studies/multilingual-stream/README.md) — shared C11/Rust contract.
 - [Go Gateway](case-studies/go-gateway/README.md) — bounded concurrency and cancellation.
 - [Composed Gateway](case-studies/composed-gateway/README.md) — C11 FFI, generated Go bindings, Go orchestration, Rust authority, recovery, measurement, custody, claim readiness, and portable physical-host reproduction.
-- [Remote Water Control](case-studies/remote-water-control/README.md), [RAVEL 0.1–0.5](case-studies/ravel/README.md), and [dSense](case-studies/dsense-desk-pet/README.md) — additional bounded studies with explicit non-promotion boundaries.
+- [Remote Water Control](case-studies/remote-water-control/README.md), [RAVEL 0.1–0.6](case-studies/ravel/README.md), and [dSense](case-studies/dsense-desk-pet/README.md) — additional bounded studies with explicit non-promotion boundaries.
 
 ## Current claim boundary
 
@@ -119,4 +119,4 @@ external-actor limits.
 - `docs/` — documentation.
 - `rfcs/` — governance proposals, including RFC 0006, RFC 0007, and RFC 0008.
 
-Read `CONTRIBUTING.md`, `GOVERNANCE.md`, and the RFC process before proposing normative changes.
+Read `CONTRIBUTING.md`, `GOVERNANCE.md`, and the RFC process before proposing normative changes.

case-studies/ravel/docs/EVIDENCE_GUIDE.md

@@ -0,0 +1,145 @@
+# RAVEL evidence guide
+
+RAVEL separates protocol, implementation, observations, interpretation, identity,
+and authority. A file that reports a passing check does not automatically prove
+that the mechanism passed its frozen study or that the study has independent or
+protected evidence.
+
+## Evidence layers
+
+### 1. Scope and preregistration
+
+Examples: `RAVEL_0_6_SCOPE.md`, `RAVEL_0_6_PREREGISTRATION.md`, and
+`ravel-0.6-preregistration.json`.
+
+These files define the question, candidate limits, partitions, seeds, gates,
+change rules, and claim boundaries before evaluation. They establish the
+protocol, not the outcome.
+
+### 2. Readable contract
+
+Examples: `RAVEL_0_4_CONTRACT.md` and `RAVEL_0_5_CONTRACT.md`.
+
+The contract explains required behavior and limits in human-readable form. It is
+an authority surface for review, but it does not prove the source implements the
+contract.
+
+### 3. Mechanism source
+
+Examples: `ravel_0_4.c` and `ravel_0_5.c`.
+
+The maintained source defines the executable mechanism. For a generated 0.6
+candidate, the generator, frozen input identity, transformation rules, and output
+identity are all part of the implementation story.
+
+### 4. Raw observations
+
+Examples: `ravel-0.4-raw-observations.json` and
+`ravel-0.5-raw-observations.json`.
+
+These records should contain facts emitted by the executable, such as counts,
+checksums, predictions, topology, resource measurements, and integrity facts.
+They should not silently declare their own authoritative verdict when an
+external evaluator is responsible for deriving it.
+
+### 5. Evaluator-derived evidence
+
+Examples: `ravel-0.5-trial-evidence.json` and
+`ravel-0.5-negative-evidence.json`.
+
+The evaluator checks the frozen matrix, validates record structure, derives
+metrics, applies hard gates, rejects contradictions, and preserves failures. The
+evaluator can establish whether the supplied observations satisfy the declared
+protocol; it cannot establish protected custody or organizational independence
+merely because it is a separate program.
+
+### 6. Source and execution identity
+
+Examples: `ravel-0.4-source-manifest.json` and
+`ravel-0.5-source-and-execution-manifest.json`.
+
+These records bind ordered files, digests, compiler or execution details, and
+other identity facts. They answer which implementation and execution surface the
+evidence refers to. They are why renaming or moving frozen files may be a
+material change rather than harmless cleanup.
+
+### 7. Assurance case
+
+Examples: `ravel-0.4-assurance-case.json` and
+`ravel-0.5-assurance-case.json`.
+
+The assurance case combines the available facts into a bounded disposition. It
+should retain limitations, `UNKNOWN` conditions, failed gates, and explicit
+non-promotion fields.
+
+### 8. Human-readable results and postmortems
+
+Examples: `RAVEL_0_4_RESULTS.md`, `RAVEL_0_5_RESULTS.md`, and
+`RAVEL_0_5_POSTMORTEM.md`.
+
+These files explain the evidence to readers. They are useful summaries, but the
+underlying JSON and source identities remain the auditable basis.
+
+### 9. Runtime observations
+
+Example: `ravel-0.5-runtime-observations.json`.
+
+Wall-clock timing is host-specific and non-normative. Deterministic expert,
+operation, or evaluation counts are the canonical work measures unless a
+separate protocol explicitly defines cross-host performance evidence.
+
+## Distinct result questions
+
+RAVEL reports several different questions that must not be collapsed:
+
+| Question | Typical value |
+|---|---|
+| Did the executable run and produce structurally valid observations? | execution integrity |
+| Did a trial satisfy every frozen mechanism gate? | per-trial result |
+| Did every required trial satisfy the aggregate rule? | development result |
+| Is the source and execution identity complete and verified? | identity assurance |
+| Was evaluation protected from the developer and independently operated? | custody and independence |
+| Does the package satisfy formal MNCS or MNCDS requirements? | formal status |
+| Is release or promotion authorized? | governance disposition |
+
+A `PASS` in one row does not imply `PASS` in another.
+
+## Preserved RAVEL outcomes
+
+- RAVEL 0.4: execution produced evidence, but zero of eight frozen trials passed
+  all gates; development result `FAIL`.
+- RAVEL 0.5: execution integrity `PASS`; 24 of 32 trials passed; the all-trials
+  development result remains `FAIL`.
+- RAVEL 0.6: preregistered development and candidate preparation exist, but
+  selection, future-final evaluation, protected custody, independent operation,
+  formal conformance, and promotion remain `UNKNOWN` or unauthorized.
+
+## What repository-local evidence cannot manufacture
+
+Repository-local source, hashes, signatures, containers, test runners, and
+separate evaluator programs cannot by themselves establish:
+
+- protection from a user with root or repository administration access;
+- future-final seed secrecy from the developer;
+- organizational independence;
+- independent custody or witness authority;
+- uncontaminated real-world data;
+- production safety or operational readiness; or
+- governance approval.
+
+Those claims require external facts and actors, not stronger wording around
+local files.
+
+## Review checklist
+
+Before accepting a RAVEL result or modifying the directory, verify:
+
+1. the exact epoch and candidate identity;
+2. the applicable preregistration and contract;
+3. whether the source is maintained or generated;
+4. whether raw observations are unchanged and complete;
+5. which evaluator derived the result;
+6. whether negative and mutation evidence is retained;
+7. whether manifests bind every required file and execution fact;
+8. whether failures and `UNKNOWN` conditions remain visible; and
+9. whether the proposed change affects a frozen identity or claim boundary.

case-studies/ravel/docs/PROJECT_MAP.md

@@ -0,0 +1,141 @@
+# RAVEL project map
+
+RAVEL is organized by evidence role and research epoch. The parent directory is
+partly flat because historical evidence binds exact paths, filenames, ordering,
+and digests. This guide provides logical grouping without relocating frozen
+artifacts.
+
+## 1. Landing and cross-version orientation
+
+| File | Purpose |
+|---|---|
+| `README.md` | Main entry point, status summary, commands, and claim boundary |
+| `docs/README.md` | Documentation hub |
+| `docs/VERSION_HISTORY.md` | Cross-version development history |
+| `docs/EVIDENCE_GUIDE.md` | Evidence-layer and claim interpretation |
+| `ARCHITECTURE_GAPS.md` | Why 0.3 unified previously separate mechanism roles and what remained external |
+
+## 2. Mechanism implementations
+
+| Epoch | Implementation |
+|---|---|
+| 0.1 | `ravel.c` |
+| 0.2 | `ravel_train.c` |
+| 0.3 | `ravel_unified.c` plus `ravel_unified/*.inc` |
+| 0.4 | `ravel_0_4.c` |
+| 0.5 | `ravel_0_5.c` |
+| 0.6 | Reproducible development source derived by `tools/ravel_0_6_seed_candidate.py`; no selected or final implementation is claimed |
+
+Generated binaries such as `ravel`, `ravel_train`, `ravel_unified_bin`,
+`ravel_0_4_bin`, and `ravel_0_5_bin` are build outputs and are removed by the
+local clean targets.
+
+## 3. Readable behavioral authority
+
+| Epoch | Contract or authority |
+|---|---|
+| 0.1 | `CONTRACT.md` |
+| 0.2 | `TRAINING_CONTRACT.md` |
+| 0.3 | `UNIFIED_CONTRACT.md` |
+| 0.4 | `RAVEL_0_4_CONTRACT.md` |
+| 0.5 | `RAVEL_0_5_CONTRACT.md` |
+| 0.6 | `RAVEL_0_6_SCOPE.md` and `RAVEL_0_6_PREREGISTRATION.md` |
+
+Contracts explain expected behavior, limits, gates, and exclusions. They are not
+substitutes for raw observations or source identity.
+
+## 4. Protocol and preregistration
+
+Common protocol files include:
+
+- `unified-preregistration.json` for the historical unified study;
+- `ravel-0.4-preregistration.json` for the frozen 0.4 matrix;
+- `ravel-0.5-preregistration.json` for the frozen 0.5 matrix; and
+- `ravel-0.6-preregistration.json` for the new preregistered epoch.
+
+The 0.6 support set also includes:
+
+- `ravel-0.6-threat-model.json`;
+- `ravel-0.6-development-record.json`;
+- `ravel-0.6-limitations.md`; and
+- `RAVEL_0_6_NEXT_STEPS.md`.
+
+Preregistration files define what may be changed, which partitions and seeds are
+permitted, how candidates are identified, and how results are derived.
+
+## 5. Raw observations and derived evidence
+
+### Historical studies
+
+- `evidence.json` and `evidence-actual.json` — 0.1 expected and local actual
+  output.
+- `training-*.json` — 0.2 protocol and evidence records.
+- `unified-evidence.json` — deterministic 0.3 observations.
+- `unified-threat-model.json` and `unified-assurance-case.json` — historical
+  threats and bounded disposition.
+
+### RAVEL 0.4
+
+- `ravel-0.4-raw-observations.json` — direct executable output;
+- `ravel-0.4-trial-evidence.json` — derived per-trial evidence;
+- `ravel-0.4-negative-evidence.json` — mutation and adversarial evidence;
+- `RAVEL_0_4_RESULTS.md` — generated human-readable results; and
+- `ravel-0.4-assurance-case.json` — bounded non-promotion disposition.
+
+### RAVEL 0.5
+
+- `ravel-0.5-raw-observations.json` — direct executable output;
+- `ravel-0.5-trial-evidence.json` — evaluator-derived trial evidence;
+- `ravel-0.5-negative-evidence.json` — evaluator and mutation evidence;
+- `ravel-0.5-runtime-observations.json` — host-specific, non-normative timing;
+- `RAVEL_0_5_RESULTS.md` — generated human-readable results;
+- `RAVEL_0_5_POSTMORTEM.md` — retained failure analysis; and
+- `ravel-0.5-assurance-case.json` — bounded non-promotion disposition.
+
+Read [EVIDENCE_GUIDE.md](EVIDENCE_GUIDE.md) before comparing these layers.
+
+## 6. Source and execution identity
+
+| Epoch | Identity records |
+|---|---|
+| 0.4 | `ravel-0.4-source-manifest-spec.json` and `ravel-0.4-source-manifest.json` |
+| 0.5 | `ravel-0.5-source-manifest-spec.json` and `ravel-0.5-source-and-execution-manifest.json` |
+
+Digest tools under `tools/` validate ordered source identity and assurance-case
+bindings. These records are why appearance-only file moves can be semantically
+material.
+
+## 7. Evaluators and support tooling
+
+See [`../tools/README.md`](../tools/README.md) for script-level detail.
+
+The main categories are:
+
+- evidence generation and verification;
+- independent metric and gate derivation;
+- source and execution digest verification;
+- runtime observation capture;
+- mutation and negative testing; and
+- bounded 0.6 candidate source derivation.
+
+## 8. Build and verification entry points
+
+The local `Makefile` exposes version-specific targets. The repository root
+`Makefile` forwards the most important checks under names such as:
+
+- `ravel-test`;
+- `ravel-training-check`;
+- `ravel-unified-check`;
+- `ravel-0.4-check`; and
+- `ravel-0.5-check`.
+
+Use verification targets before any target that rewrites evidence.
+
+## 9. Where new work belongs
+
+- Cross-version explanation or navigation: `docs/`.
+- Evaluator, digest, mutation, or derivation script: `tools/`.
+- New epoch source, contract, preregistration, and evidence: use a clearly
+  versioned identity and document the complete lifecycle before adding files.
+- Historical frozen artifacts: do not rename, regroup, or rewrite merely for
+  visual consistency.

case-studies/ravel/docs/README.md

@@ -0,0 +1,38 @@
+# RAVEL documentation hub
+
+This directory is the human-navigation layer for the RAVEL case study. It does
+not replace versioned contracts, preregistrations, raw observations, manifests,
+or assurance records in the parent directory.
+
+## Guides
+
+- [Version history](VERSION_HISTORY.md) — what changed in each epoch, preserved
+  results, and current development status.
+- [Project map](PROJECT_MAP.md) — where to find implementations, contracts,
+  evidence, manifests, plans, and tooling.
+- [Evidence guide](EVIDENCE_GUIDE.md) — how the evidence layers relate and what
+  conclusions they do and do not support.
+
+## Authoritative material remains versioned
+
+Use the guides above to locate the authoritative files, then read those files
+directly. In particular:
+
+- Markdown contracts define readable behavioral authority;
+- preregistration JSON defines frozen protocol and gates;
+- C source defines the maintained mechanism for its epoch;
+- raw observation JSON records executable output;
+- evaluator-derived evidence records interpretation of those observations;
+- source and execution manifests bind identity;
+- assurance cases state the bounded disposition and unresolved limitations.
+
+Documentation may summarize those records but must not silently upgrade their
+claims.
+
+## Placement rule
+
+Add explanatory, cross-version, or navigational material here. Keep executable
+support scripts under `../tools/`. Keep version-bound contracts, source,
+preregistrations, observations, manifests, and assurance records in their
+existing versioned locations unless a new epoch explicitly defines a different
+layout and identity scheme.