From 2369f3d5415d0e7eb79edc147b82a0072f0b94c9 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:07:55 -0400
Subject: [PATCH 01/10] refactor(adapters): stage the registry for layered
 descriptor sources
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Carve descriptor provenance into a new descriptor::layers module
(Layer, DescriptorSource, embedded_sources) and rebuild the registry on
top of it: entries now record their contributing sources, build_registry
takes owned DescriptorSource values and returns a Result (duplicate
labels error instead of panicking), and the static becomes a OnceLock
whose lazy fallback loads the embedded built-ins only — the seam #136's
user-supplied layers feed into next.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/adapters/descriptor.rs         |   1 +
 src/adapters/descriptor/layers.rs  |  50 ++++++++++++
 src/adapters/descriptor_adapter.rs |   1 +
 src/adapters/registry.rs           | 123 +++++++++++++++++++++--------
 4 files changed, 144 insertions(+), 31 deletions(-)
 create mode 100644 src/adapters/descriptor/layers.rs

diff --git a/src/adapters/descriptor.rs b/src/adapters/descriptor.rs
index e249122..1f073e6 100644
--- a/src/adapters/descriptor.rs
+++ b/src/adapters/descriptor.rs
@@ -19,6 +19,7 @@ use crate::validation::{SchemaName, ValidationError, validate_against_schema};
 
 use super::capabilities::{GuardEngine, ShadowPreflight, SlugCapability, TranscriptParser};
 
+pub mod layers;
 mod validation;
 
 /// The three built-in harness descriptors, embedded like the schemas: a
diff --git a/src/adapters/descriptor/layers.rs b/src/adapters/descriptor/layers.rs
new file mode 100644
index 0000000..8209252
--- /dev/null
+++ b/src/adapters/descriptor/layers.rs
@@ -0,0 +1,50 @@
+//! Descriptor source layers: where a descriptor's TOML text came from.
+//!
+//! Every descriptor source carries its layer and display path so registry
+//! entries can report provenance (`harness list`/`show`) and error messages
+//! can name the contributing file.
+
+use super::EMBEDDED_DESCRIPTORS;
+
+/// The layer a descriptor source belongs to, in precedence order (later
+/// layers override earlier ones field-by-field).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Layer {
+    /// A built-in descriptor bundled into the binary (`harnesses/*.toml`).
+    Embedded,
+}
+
+/// One descriptor source: its layer, a display path for error messages and
+/// provenance, and the raw TOML text.
+#[derive(Debug, Clone)]
+pub struct DescriptorSource {
+    pub layer: Layer,
+    pub path: String,
+    pub toml_src: String,
+}
+
+/// The bundled built-in descriptors as the registry's base layer.
+pub fn embedded_sources() -> Vec<DescriptorSource> {
+    EMBEDDED_DESCRIPTORS
+        .iter()
+        .map(|(path, toml_src)| DescriptorSource {
+            layer: Layer::Embedded,
+            path: (*path).to_string(),
+            toml_src: (*toml_src).to_string(),
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn embedded_sources_cover_every_bundled_descriptor() {
+        let sources = embedded_sources();
+        assert_eq!(sources.len(), EMBEDDED_DESCRIPTORS.len());
+        assert!(sources.iter().all(|s| s.layer == Layer::Embedded));
+        assert_eq!(sources[0].path, "harnesses/claude-code.toml");
+        assert!(!sources[0].toml_src.is_empty());
+    }
+}
diff --git a/src/adapters/descriptor_adapter.rs b/src/adapters/descriptor_adapter.rs
index ae4c8ee..4321296 100644
--- a/src/adapters/descriptor_adapter.rs
+++ b/src/adapters/descriptor_adapter.rs
@@ -23,6 +23,7 @@ use super::skill_shadow::PluginShadowReport;
 use super::skills_block::{DEFAULT_HEADER, DEFAULT_ITEM, render_skills_block};
 
 /// A [`HarnessAdapter`] backed by a validated [`HarnessDescriptor`].
+#[derive(Debug)]
 pub struct DescriptorAdapter {
     descriptor: HarnessDescriptor,
     /// Compiled `staging.stage_name_pattern`; validated to compile at load
diff --git a/src/adapters/registry.rs b/src/adapters/registry.rs
index 66a3412..08c7ee4 100644
--- a/src/adapters/registry.rs
+++ b/src/adapters/registry.rs
@@ -7,53 +7,87 @@
 //! and the artifact `Deserialize`), [`Harness::known`] enumerates the entries,
 //! and [`adapter_for`] serves each handle's [`HarnessAdapter`].
 
-use std::sync::LazyLock;
+use std::sync::{LazyLock, OnceLock};
 
 use crate::core::Harness;
 
-use super::descriptor::{EMBEDDED_DESCRIPTORS, load_descriptor};
+use super::descriptor::layers::{DescriptorSource, Layer, embedded_sources};
+use super::descriptor::{DescriptorError, load_descriptor};
 use super::descriptor_adapter::DescriptorAdapter;
 use super::harness::{HarnessAdapter, ToolVocabulary};
 
-/// One registry entry: a harness identity (the descriptor's `label`) and its
-/// descriptor-backed adapter.
+/// One registry entry: a harness identity (the descriptor's `label`), the
+/// descriptor sources that contributed to it (for `harness list`/`show`
+/// provenance), and its descriptor-backed adapter.
+#[derive(Debug)]
 struct RegistryEntry {
     label: &'static str,
+    sources: Vec<(Layer, String)>,
     adapter: DescriptorAdapter,
 }
 
-/// Built on first use. The embedded descriptors are bundled and known-valid,
-/// so a load failure here is a programmer error (a bad descriptor edit) and
-/// panics — mirroring the bundled-schema panics in `validation::schema` —
-/// with the descriptor's own actionable message.
-static REGISTRY: LazyLock<Vec<RegistryEntry>> =
-    LazyLock::new(|| build_registry(EMBEDDED_DESCRIPTORS));
+/// Set once by `init_registry` (layered sources), or lazily to the embedded
+/// built-ins on first pre-init access. The lazy fallback keeps unit tests
+/// hermetic: they never call `init_registry`, so user-supplied descriptor
+/// layers can't leak into them.
+static REGISTRY: OnceLock<Vec<RegistryEntry>> = OnceLock::new();
+
+fn registry() -> &'static Vec<RegistryEntry> {
+    REGISTRY.get_or_init(|| {
+        // The embedded descriptors are bundled and known-valid, so a failure
+        // here is a programmer error (a bad descriptor edit) and panics —
+        // mirroring the bundled-schema panics in `validation::schema` — with
+        // the descriptor's own actionable message.
+        build_registry(embedded_sources())
+            .unwrap_or_else(|e| panic!("bundled harness descriptor is invalid: {e}"))
+    })
+}
+
+/// A descriptor source set that cannot form a registry.
+#[derive(Debug, thiserror::Error)]
+enum RegistryBuildError {
+    #[error(transparent)]
+    Descriptor(#[from] DescriptorError),
+    #[error("duplicate harness label {label:?}: {first} and {second}")]
+    DuplicateLabel {
+        label: String,
+        first: String,
+        second: String,
+    },
+}
 
 /// Load descriptor sources into registry entries, keyed by each descriptor's
 /// `label`. The label is the harness identity — `--harness <label>`, artifact
-/// values, and adapter lookup all resolve through it — so a duplicate is a
-/// programmer error and panics. Layering user-supplied descriptor files
-/// (#136) means feeding more sources through here.
+/// values, and adapter lookup all resolve through it — so two sources
+/// producing the same label collide.
 fn build_registry(
-    sources: impl IntoIterator<Item = (&'static str, &'static str)>,
-) -> Vec<RegistryEntry> {
+    sources: Vec<DescriptorSource>,
+) -> Result<Vec<RegistryEntry>, RegistryBuildError> {
     let mut entries: Vec<RegistryEntry> = Vec::new();
-    for (source, toml_src) in sources {
-        let descriptor = load_descriptor(toml_src, source)
-            .unwrap_or_else(|e| panic!("bundled harness descriptor is invalid: {e}"));
+    for source in sources {
+        let descriptor = load_descriptor(&source.toml_src, &source.path)?;
+        if let Some(existing) = entries.iter().find(|e| e.label == descriptor.label) {
+            return Err(RegistryBuildError::DuplicateLabel {
+                label: descriptor.label,
+                first: existing
+                    .sources
+                    .last()
+                    .expect("every entry records its source")
+                    .1
+                    .clone(),
+                second: source.path,
+            });
+        }
         // Leaked once per registry entry per process: the label becomes the
         // `'static` identity the rest of the crate passes around by handle.
         let label: &'static str = Box::leak(descriptor.label.clone().into_boxed_str());
-        assert!(
-            !entries.iter().any(|e| e.label == label),
-            "duplicate harness label {label:?} (from {source})"
-        );
         entries.push(RegistryEntry {
             label,
+            sources: vec![(source.layer, source.path)],
             adapter: DescriptorAdapter::from_descriptor(descriptor),
         });
     }
-    entries
+    Ok(entries)
 }
 
 /// The registry-level default harness — what `--harness` falls back to when
@@ -76,7 +110,7 @@ impl Harness {
     /// Resolve a kebab-case identifier against the descriptor registry — the
     /// only way to obtain a [`Harness`], so every held handle is valid.
     pub fn resolve(name: &str) -> Result<Harness, UnknownHarnessError> {
-        REGISTRY
+        registry()
             .iter()
             .find(|e| e.label == name)
             .map(|e| Harness::from_static_name(e.label))
@@ -90,7 +124,9 @@ impl Harness {
     /// for code that must sweep all of them (e.g. guard teardown scans each
     /// harness's skills dir for a marker).
     pub fn known() -> impl Iterator<Item = Harness> {
-        REGISTRY.iter().map(|e| Harness::from_static_name(e.label))
+        registry()
+            .iter()
+            .map(|e| Harness::from_static_name(e.label))
     }
 }
 
@@ -123,7 +159,7 @@ pub fn harness_value_parser() -> clap::builder::ValueParser {
 /// the harness identifier for all harness-specific behavior; every other
 /// module goes through the returned trait object.
 pub fn adapter_for(harness: Harness) -> &'static dyn HarnessAdapter {
-    &REGISTRY
+    &registry()
         .iter()
         .find(|e| e.label == harness.name())
         .expect("Harness handles originate from the registry")
@@ -135,7 +171,7 @@ pub fn adapter_for(harness: Harness) -> &'static dyn HarnessAdapter {
 /// staging's sibling-asset filter, the guard's Bash tamper rule, and
 /// detect-stray-writes' staging-dir lookbehind.
 pub fn all_config_dir_names() -> Vec<String> {
-    let mut names: Vec<String> = REGISTRY
+    let mut names: Vec<String> = registry()
         .iter()
         .flat_map(|e| e.adapter.config_dir_names())
         .collect();
@@ -150,7 +186,7 @@ pub fn all_config_dir_names() -> Vec<String> {
 pub fn all_tool_vocabulary() -> &'static ToolVocabulary {
     static ALL: LazyLock<ToolVocabulary> = LazyLock::new(|| {
         let mut union = ToolVocabulary::default();
-        for entry in REGISTRY.iter() {
+        for entry in registry().iter() {
             let vocab = entry.adapter.tool_vocabulary();
             union.write_tools.extend(vocab.write_tools);
             union.patch_tools.extend(vocab.patch_tools);
@@ -175,6 +211,9 @@ pub fn all_tool_vocabulary() -> &'static ToolVocabulary {
 mod tests {
     use super::*;
 
+    use crate::adapters::descriptor::EMBEDDED_DESCRIPTORS;
+    use crate::adapters::descriptor::layers::{Layer, embedded_sources};
+
     #[test]
     fn all_config_dir_names_unions_every_adapter() {
         assert_eq!(
@@ -196,9 +235,31 @@ mod tests {
     }
 
     #[test]
-    #[should_panic(expected = "duplicate harness label")]
-    fn duplicate_label_panics() {
-        build_registry([EMBEDDED_DESCRIPTORS[0], EMBEDDED_DESCRIPTORS[0]]);
+    fn duplicate_label_in_same_layer_errors() {
+        let mut sources = embedded_sources();
+        sources.push(sources[0].clone());
+        let err = build_registry(sources).unwrap_err().to_string();
+        assert!(err.contains("duplicate harness label"), "{err}");
+        assert!(err.contains("claude-code"), "names the label: {err}");
+        assert!(
+            err.contains("harnesses/claude-code.toml"),
+            "names the colliding source files: {err}"
+        );
+    }
+
+    #[test]
+    fn registry_entries_record_embedded_provenance() {
+        let entries = build_registry(embedded_sources()).unwrap();
+        assert_eq!(entries.len(), EMBEDDED_DESCRIPTORS.len());
+        for entry in &entries {
+            assert_eq!(entry.sources.len(), 1, "one contributing file per built-in");
+            assert_eq!(entry.sources[0].0, Layer::Embedded);
+            assert!(
+                entry.sources[0].1.contains(entry.label),
+                "source path names the harness: {}",
+                entry.sources[0].1
+            );
+        }
     }
 
     #[test]

From 211d0608247f506223d7737867d8bd04f8b015d8 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:10:45 -0400
Subject: [PATCH 02/10] refactor(cli)!: resolve --harness after parsing, not in
 clap

--harness now parses as a plain string and resolves against the
descriptor registry in run_context_with_bootstrap, so runtime-loaded
descriptor layers (#136) can name harnesses clap never saw. The
PossibleValuesParser goes away with the compile-time-complete registry
assumption: unknown names now surface the registry's own actionable
error (unknown harness 'x'; known harnesses: ...) with exit 1 instead of
clap's invalid-value rejection with exit 2, and run --help names the
built-ins in the flag's doc text instead of [possible values:].

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/adapters/mod.rs          |  2 +-
 src/adapters/registry.rs     | 11 -----------
 src/cli/args.rs              | 10 +++++-----
 src/cli/commands/pipeline.rs |  2 +-
 src/cli/mod.rs               |  8 ++++++--
 tests/cli/basics.rs          | 11 ++++++-----
 6 files changed, 19 insertions(+), 25 deletions(-)

diff --git a/src/adapters/mod.rs b/src/adapters/mod.rs
index f19ffb2..e94fbdc 100644
--- a/src/adapters/mod.rs
+++ b/src/adapters/mod.rs
@@ -31,7 +31,7 @@ pub use harness::{
 };
 pub use registry::{
     DEFAULT_HARNESS_NAME, UnknownHarnessError, adapter_for, all_config_dir_names,
-    all_tool_vocabulary, harness_value_parser,
+    all_tool_vocabulary,
 };
 pub use skill_shadow::{
     PluginShadowReport, ShadowSource, format_shadow_banner, shadow_validity_warnings,
diff --git a/src/adapters/registry.rs b/src/adapters/registry.rs
index 08c7ee4..a7c1e61 100644
--- a/src/adapters/registry.rs
+++ b/src/adapters/registry.rs
@@ -144,17 +144,6 @@ impl<'de> serde::Deserialize<'de> for Harness {
     }
 }
 
-/// The `--harness` value parser: registry-driven possible values, so clap
-/// renders `[possible values: …]` in help, suggests near-misses, and rejects
-/// unknown names listing the known ones — with no compile-time harness set.
-pub fn harness_value_parser() -> clap::builder::ValueParser {
-    use clap::builder::TypedValueParser as _;
-    let names: Vec<&'static str> = Harness::known().map(Harness::name).collect();
-    clap::builder::PossibleValuesParser::new(names)
-        .map(|name| Harness::resolve(&name).expect("clap only passes registry-known names"))
-        .into()
-}
-
 /// Resolve the adapter for a [`Harness`]. This is the single dispatch point on
 /// the harness identifier for all harness-specific behavior; every other
 /// module goes through the returned trait object.
diff --git a/src/cli/args.rs b/src/cli/args.rs
index 486273f..43456f7 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -6,8 +6,6 @@
 
 use clap::{Args, Parser, Subcommand};
 
-use crate::core::Harness;
-
 /// Run skill evals — measure whether an agent skill actually shifts behavior.
 ///
 /// An eval dispatches a fresh subagent twice per test case — once with the skill
@@ -78,9 +76,11 @@ pub struct CommonArgs {
     /// `--guard`. Each reads its own per-task events file (`claude-events.jsonl`,
     /// `codex-events.jsonl`); Codex stages skills under `.agents/skills`.
     /// OpenCode stages skills under `.opencode/skills`; transcript ingest and
-    /// `--guard` are not yet wired for OpenCode.
-    #[arg(long, value_parser = crate::adapters::harness_value_parser())]
-    pub harness: Option<Harness>,
+    /// `--guard` are not yet wired for OpenCode. The name is resolved against
+    /// the harness descriptor registry after parsing; an unknown name errors
+    /// listing every registered harness.
+    #[arg(long)]
+    pub harness: Option<String>,
     /// Workspace directory (defaults to `<cwd>/.eval-magic`).
     ///
     /// The artifact root. Pass the same value to every command of a run, including
diff --git a/src/cli/commands/pipeline.rs b/src/cli/commands/pipeline.rs
index 2c424b6..a8bbc8c 100644
--- a/src/cli/commands/pipeline.rs
+++ b/src/cli/commands/pipeline.rs
@@ -44,7 +44,7 @@ fn run_step(step: &run::steps::StepCommand) -> anyhow::Result<()> {
         skill: step.skill.clone(),
         iteration: Some(step.iteration),
         mode: None,
-        harness: Some(step.harness),
+        harness: Some(step.harness.name().to_string()),
         workspace_dir: step.workspace_dir.clone(),
         only: None,
         skip: None,
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 483ffaa..6186b7a 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -11,7 +11,7 @@ use std::path::{Path, PathBuf};
 use anyhow::{anyhow, bail};
 use clap::Parser;
 
-use crate::core::{DetectInput, RunContext, detect_run_context};
+use crate::core::{DetectInput, Harness, RunContext, detect_run_context};
 
 mod args;
 mod commands;
@@ -86,12 +86,16 @@ pub(crate) fn run_context_with_bootstrap(
     args: &CommonArgs,
     bootstrap: Option<String>,
 ) -> anyhow::Result<RunContext> {
+    // `--harness` parses as a plain string so runtime-loaded descriptors can
+    // name harnesses clap never saw; resolution against the registry happens
+    // here, after parsing.
+    let harness = args.harness.as_deref().map(Harness::resolve).transpose()?;
     Ok(detect_run_context(DetectInput {
         skill_dir: args.skill_dir.clone(),
         skill: args.skill.clone(),
         bootstrap,
         workspace_dir: args.workspace_dir.clone(),
-        harness: args.harness,
+        harness,
         cwd: None,
     })?)
 }
diff --git a/tests/cli/basics.rs b/tests/cli/basics.rs
index 7027df0..8ace54c 100644
--- a/tests/cli/basics.rs
+++ b/tests/cli/basics.rs
@@ -137,8 +137,9 @@ fn unknown_subcommand_is_rejected() {
     skill_eval().arg("does-not-exist").assert().failure();
 }
 
-/// An unknown `--harness` value is rejected with an error naming the offending
-/// value and every known harness.
+/// An unknown `--harness` value is rejected by the registry resolver with an
+/// error naming the offending value and every known harness. (Resolution
+/// happens after parsing, not in clap, so runtime-loaded descriptors count.)
 #[test]
 fn unknown_harness_value_is_rejected_naming_known_harnesses() {
     skill_eval()
@@ -146,16 +147,16 @@ fn unknown_harness_value_is_rejected_naming_known_harnesses() {
         .assert()
         .failure()
         .stderr(
-            contains("invalid value 'nonexistent'")
+            contains("unknown harness 'nonexistent'")
                 .and(contains("claude-code"))
                 .and(contains("codex"))
                 .and(contains("opencode")),
         );
 }
 
-/// `run --help` lists the known harnesses as possible values for `--harness`.
+/// `run --help` names the built-in harnesses in the `--harness` doc text.
 #[test]
-fn run_help_lists_harness_possible_values() {
+fn run_help_names_builtin_harnesses() {
     skill_eval()
         .args(["run", "--help"])
         .assert()

From 63bd8a893bd6d49b3c4d96e88e1745515a49ac2d Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:14:57 -0400
Subject: [PATCH 03/10] feat(descriptors): make skills_dir optional for
 baseline harnesses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A descriptor with just a label now loads: skills_dir leaves the schema's
required set and becomes Option<String>, and HarnessAdapter::skills_dir
returns Option<PathBuf>. Two new load-time invariants keep the
combination coherent — [staging] configured without skills_dir and
[guard] without skills_dir are both rejected, since staging copies into
the skills dir and the guard keeps its marker/manifest there. Guard
teardown and the armed-marker sweep skip skills_dir-less harnesses;
staging call sites keep a PathBuf via expect, justified because the run
preflight (upcoming) forces --no-stage for such harnesses.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 schema/harness-descriptor.schema.json |  4 +-
 src/adapters/descriptor.rs            | 42 ++++++++++++++++++++-
 src/adapters/descriptor/validation.rs | 53 +++++++++++++++++++++++----
 src/adapters/descriptor_adapter.rs    | 10 ++---
 src/adapters/harness.rs               | 12 +++---
 src/cli/commands/guard.rs             |  1 +
 src/cli/run/staging/mod.rs            |  4 +-
 src/sandbox/install.rs                | 14 +++++--
 8 files changed, 114 insertions(+), 26 deletions(-)

diff --git a/schema/harness-descriptor.schema.json b/schema/harness-descriptor.schema.json
index b318f64..b0e1854 100644
--- a/schema/harness-descriptor.schema.json
+++ b/schema/harness-descriptor.schema.json
@@ -4,7 +4,7 @@
   "title": "Harness Descriptor",
   "description": "The data half of a harness adapter: every declarative value a harness exposes, plus references to named code capabilities (transcript parsers, guard engines, slug generation, shadow preflight). Authored as TOML (harnesses/*.toml), validated after transcoding to JSON. Cross-field invariants (guard/banner lockstep, slug/naming-rule agreement, vocabulary coverage) are enforced by the Rust loader on top of this schema.",
   "type": "object",
-  "required": ["label", "skills_dir"],
+  "required": ["label"],
   "additionalProperties": false,
   "properties": {
     "label": {
@@ -15,7 +15,7 @@
     "skills_dir": {
       "type": "string",
       "minLength": 1,
-      "description": "Project-local staged-skills directory, `/`-separated relative to the repo root (e.g. \".claude/skills\")."
+      "description": "Project-local staged-skills directory, `/`-separated relative to the repo root (e.g. \".claude/skills\"). Optional: a harness without one cannot stage skills natively, so runs fall back to --no-stage (each SKILL.md inlined into its dispatch prompt) with a preflight warning."
     },
     "config_dirs": {
       "type": "array",
diff --git a/src/adapters/descriptor.rs b/src/adapters/descriptor.rs
index 1f073e6..a738c4e 100644
--- a/src/adapters/descriptor.rs
+++ b/src/adapters/descriptor.rs
@@ -47,7 +47,7 @@ pub const EMBEDDED_DESCRIPTORS: [(&str, &str); 3] = [
 #[derive(Debug, Clone, Deserialize)]
 pub struct HarnessDescriptor {
     pub label: String,
-    pub skills_dir: String,
+    pub skills_dir: Option<String>,
     #[serde(default)]
     pub config_dirs: Vec<String>,
     #[serde(default)]
@@ -310,7 +310,7 @@ armed_message = "guard armed"
     fn minimal_descriptor_loads() {
         let d = load(MINIMAL).unwrap();
         assert_eq!(d.label, "demo");
-        assert_eq!(d.skills_dir, ".demo/skills");
+        assert_eq!(d.skills_dir.as_deref(), Some(".demo/skills"));
         assert_eq!(d.config_dirs, vec![".demo".to_string()]);
         // Section defaults match the trait defaults.
         assert!(!d.run.supports_guard);
@@ -328,6 +328,44 @@ armed_message = "guard armed"
         assert!(d.guard.is_some());
     }
 
+    #[test]
+    fn label_only_descriptor_loads_as_baseline() {
+        let d = load("label = \"demo\"\n").unwrap();
+        assert_eq!(d.label, "demo");
+        assert!(d.skills_dir.is_none(), "no skills dir declared");
+        assert!(d.config_dirs.is_empty());
+        assert!(!d.run.supports_guard);
+    }
+
+    #[test]
+    fn rejects_staging_without_skills_dir() {
+        let err = err_of("label = \"demo\"\n\n[staging]\nsurface_phrase = \"skill\"\n");
+        assert!(err.contains("staging"), "{err}");
+        assert!(err.contains("skills_dir"), "{err}");
+    }
+
+    #[test]
+    fn rejects_guard_without_skills_dir() {
+        let toml = r#"
+label = "demo"
+config_dirs = [".demo"]
+
+[run]
+supports_guard = true
+
+[tools]
+write = ["Edit", "MultiEdit", "NotebookEdit", "Write"]
+shell = ["Bash"]
+
+[guard]
+engine = "claude-hooks"
+armed_message = "guard armed"
+"#;
+        let err = err_of(toml);
+        assert!(err.contains("guard"), "{err}");
+        assert!(err.contains("skills_dir"), "{err}");
+    }
+
     #[test]
     fn embedded_descriptors_load_and_validate() {
         for (source, toml_src) in EMBEDDED_DESCRIPTORS {
diff --git a/src/adapters/descriptor/validation.rs b/src/adapters/descriptor/validation.rs
index e72d70d..4d8cc2f 100644
--- a/src/adapters/descriptor/validation.rs
+++ b/src/adapters/descriptor/validation.rs
@@ -39,6 +39,28 @@ pub(super) fn validate_descriptor(
         ));
     }
 
+    // Native staging and the write guard both live under the skills dir:
+    // staging copies skills into it, and the guard keeps its marker/manifest
+    // there. Without a skills_dir neither has anywhere to operate.
+    if d.skills_dir.is_none() {
+        if staging_is_configured(&d.staging) {
+            return fail(
+                "[staging] is configured but skills_dir is not declared; native staging \
+                 copies skills into skills_dir — declare it, or drop [staging] and let \
+                 runs fall back to --no-stage"
+                    .into(),
+            );
+        }
+        if d.guard.is_some() {
+            return fail(
+                "[guard] is declared but skills_dir is not; the guard's marker and \
+                 teardown manifest live under skills_dir — declare it, or drop the \
+                 guard and rely on the detect-stray-writes audit"
+                    .into(),
+            );
+        }
+    }
+
     // Slug shape: one source of truth, all four placeholders, and the
     // generated slug must satisfy the descriptor's own naming rules.
     if d.staging.slug_template.is_some() && d.staging.slug_capability.is_some() {
@@ -81,13 +103,15 @@ pub(super) fn validate_descriptor(
 
     // The skills dir must live under a declared config dir, or staging's
     // sibling-asset filter would copy a checked-in copy into staged envs.
-    let top = d.skills_dir.split('/').next().unwrap_or_default();
-    if !d.config_dirs.iter().any(|dir| dir == top) {
-        return fail(format!(
-            "config_dirs {:?} misses \"{top}\", the parent of skills_dir — staging's \
-             sibling-asset filter and the guard tamper rules key off config_dirs",
-            d.config_dirs
-        ));
+    if let Some(skills_dir) = &d.skills_dir {
+        let top = skills_dir.split('/').next().unwrap_or_default();
+        if !d.config_dirs.iter().any(|dir| dir == top) {
+            return fail(format!(
+                "config_dirs {:?} misses \"{top}\", the parent of skills_dir — staging's \
+                 sibling-asset filter and the guard tamper rules key off config_dirs",
+                d.config_dirs
+            ));
+        }
     }
 
     // Every tool the guard engine hooks must be declared in the vocabulary,
@@ -261,6 +285,21 @@ pub(super) fn validate_descriptor(
     Ok(())
 }
 
+/// True when any `[staging]` field departs from the defaults — the signal
+/// that the descriptor actually configures native staging rather than just
+/// inheriting the baseline.
+fn staging_is_configured(staging: &super::StagingSection) -> bool {
+    staging.slug_template.is_some()
+        || staging.slug_capability.is_some()
+        || staging.stage_name_pattern.is_some()
+        || staging.stage_name_max_len.is_some()
+        || staging.stage_name_invalid_message.is_some()
+        || staging.rewrites_frontmatter_name
+        || staging.advertises_staged_slug_name
+        || staging.surface_phrase.is_some()
+        || staging.unresolved_phrase.is_some()
+}
+
 #[cfg(test)]
 mod tests {
     use super::super::load_descriptor;
diff --git a/src/adapters/descriptor_adapter.rs b/src/adapters/descriptor_adapter.rs
index 4321296..5eed8be 100644
--- a/src/adapters/descriptor_adapter.rs
+++ b/src/adapters/descriptor_adapter.rs
@@ -85,11 +85,11 @@ impl HarnessAdapter for DescriptorAdapter {
         self.descriptor.label.clone()
     }
 
-    fn skills_dir(&self, repo_root: &Path) -> PathBuf {
-        self.descriptor
-            .skills_dir
-            .split('/')
-            .fold(repo_root.to_path_buf(), |path, segment| path.join(segment))
+    fn skills_dir(&self, repo_root: &Path) -> Option<PathBuf> {
+        self.descriptor.skills_dir.as_ref().map(|dir| {
+            dir.split('/')
+                .fold(repo_root.to_path_buf(), |path, segment| path.join(segment))
+        })
     }
 
     fn run_capabilities(&self) -> HarnessRunCapabilities {
diff --git a/src/adapters/harness.rs b/src/adapters/harness.rs
index 1d5d6fe..6d755c7 100644
--- a/src/adapters/harness.rs
+++ b/src/adapters/harness.rs
@@ -59,8 +59,10 @@ pub trait HarnessAdapter {
     /// **Baseline.** The project-local directory staged skills live under for
     /// this harness. Under `--no-stage` nothing is staged into it, so a
     /// baseline harness may point this at any repo-local path its discovery
-    /// would read.
-    fn skills_dir(&self, repo_root: &Path) -> PathBuf;
+    /// would read. `None` when the harness declares no skills directory —
+    /// native staging is then unavailable and the run preflight forces
+    /// `--no-stage` (each SKILL.md is inlined into its dispatch prompt).
+    fn skills_dir(&self, repo_root: &Path) -> Option<PathBuf>;
 
     // ── Run-option capabilities (defaulted) ──────────────────────────────────
 
@@ -383,15 +385,15 @@ mod tests {
         let root = Path::new("/repo");
         assert_eq!(
             adapter_for(Harness::resolve("claude-code").unwrap()).skills_dir(root),
-            root.join(".claude").join("skills")
+            Some(root.join(".claude").join("skills"))
         );
         assert_eq!(
             adapter_for(Harness::resolve("codex").unwrap()).skills_dir(root),
-            root.join(".agents").join("skills")
+            Some(root.join(".agents").join("skills"))
         );
         assert_eq!(
             adapter_for(Harness::resolve("opencode").unwrap()).skills_dir(root),
-            root.join(".opencode").join("skills")
+            Some(root.join(".opencode").join("skills"))
         );
     }
 
diff --git a/src/cli/commands/guard.rs b/src/cli/commands/guard.rs
index f79820c..693a541 100644
--- a/src/cli/commands/guard.rs
+++ b/src/cli/commands/guard.rs
@@ -69,5 +69,6 @@ fn default_marker_path(harness_name: &str) -> PathBuf {
     let harness = Harness::resolve(harness_name).expect("bundled harness");
     adapter_for(harness)
         .skills_dir(&std::env::current_dir().unwrap_or_default())
+        .expect("bundled guard-capable harnesses declare skills_dir")
         .join(sandbox::GUARD_MARKER)
 }
diff --git a/src/cli/run/staging/mod.rs b/src/cli/run/staging/mod.rs
index 3352c9b..59408dd 100644
--- a/src/cli/run/staging/mod.rs
+++ b/src/cli/run/staging/mod.rs
@@ -108,7 +108,9 @@ impl Default for StageSiblingOpts<'_> {
 
 /// `<repo_root>/.agents/skills` (Codex) or `<repo_root>/.claude/skills`.
 pub(crate) fn skills_dir_for_harness(repo_root: &Path, harness: Harness) -> PathBuf {
-    adapter_for(harness).skills_dir(repo_root)
+    adapter_for(harness)
+        .skills_dir(repo_root)
+        .expect("staging requires skills_dir; the run preflight forces --no-stage otherwise")
 }
 
 /// True when `name` is any harness's project-local config dir (`.claude`,
diff --git a/src/sandbox/install.rs b/src/sandbox/install.rs
index 5119013..e322758 100644
--- a/src/sandbox/install.rs
+++ b/src/sandbox/install.rs
@@ -132,7 +132,11 @@ pub fn teardown_guard(stage_root: &Path) -> bool {
     let mut torn = false;
     for harness in Harness::known() {
         let adapter = crate::adapters::adapter_for(harness);
-        torn |= teardown_guard_from_skills_dir(&adapter.skills_dir(stage_root));
+        // A harness without a skills dir cannot host a guard (descriptor
+        // validation rejects the combination), so there is nothing to sweep.
+        if let Some(skills_dir) = adapter.skills_dir(stage_root) {
+            torn |= teardown_guard_from_skills_dir(&skills_dir);
+        }
         if let Some(hook_dir) = adapter.guard_hook_cleanup_dir(stage_root) {
             let _ = prune_if_empty(&hook_dir);
         }
@@ -144,10 +148,12 @@ pub fn teardown_guard(stage_root: &Path) -> bool {
 pub(crate) fn guard_is_armed(stage_root: &Path) -> bool {
     let now = now_ms();
     Harness::known().any(|harness| {
-        let marker_path = crate::adapters::adapter_for(harness)
+        crate::adapters::adapter_for(harness)
             .skills_dir(stage_root)
-            .join(GUARD_MARKER);
-        marker_is_armed(read_marker(&marker_path).as_ref(), now)
+            .is_some_and(|skills_dir| {
+                let marker_path = skills_dir.join(GUARD_MARKER);
+                marker_is_armed(read_marker(&marker_path).as_ref(), now)
+            })
     })
 }
 

From c23f739781b3829efa213f59dbdeef7a60596289 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:23:50 -0400
Subject: [PATCH 04/10] feat(byoh): layered user-supplied harness descriptors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Descriptor sources now stack in precedence order — embedded built-ins,
user-global ($EVAL_MAGIC_CONFIG_DIR, $XDG_CONFIG_HOME/eval-magic, or
~/.config/eval-magic, under harnesses/*.toml), project-local
(.eval-magic/harnesses/*.toml), and a one-off --harness-file — with
field-level merge: a later file overrides individual fields of an
earlier descriptor with the same label, or defines a new harness
outright. Every file passes the schema gate individually (only label is
required, so partial overrides validate too) and merged results re-run
the full invariant suite with a provenance chain naming every
contributing file.

Policy: broken discovered files are skipped with a warning pointing at
harness lint — they never brick the CLI; a broken --harness-file is a
hard error. User-layer files may not declare [guard] or flip
run.supports_guard (fail-open safety until the guard engine opens up);
unguarded runs fall back to the detect-stray-writes audit. When
--harness is omitted, a --harness-file descriptor's label becomes the
invocation's default harness. Test helpers set EVAL_MAGIC_CONFIG_DIR=""
so a developer's user-global descriptors never leak into the suite.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/adapters/descriptor.rs        |  98 ++++++-
 src/adapters/descriptor/layers.rs | 299 ++++++++++++++++++++-
 src/adapters/registry.rs          | 429 +++++++++++++++++++++++++++---
 src/cli/args.rs                   |  10 +
 src/cli/mod.rs                    |   9 +-
 tests/cli/harness.rs              | 135 ++++++++++
 tests/cli/helpers.rs              |   6 +-
 tests/cli/main.rs                 |   1 +
 tests/run/helpers.rs              |   6 +-
 9 files changed, 945 insertions(+), 48 deletions(-)
 create mode 100644 tests/cli/harness.rs

diff --git a/src/adapters/descriptor.rs b/src/adapters/descriptor.rs
index a738c4e..f92ba9a 100644
--- a/src/adapters/descriptor.rs
+++ b/src/adapters/descriptor.rs
@@ -177,13 +177,59 @@ pub enum DescriptorError {
 /// Parse, schema-check, and invariant-check one descriptor. `source` names the
 /// descriptor in error messages (its file path).
 pub fn load_descriptor(toml_src: &str, source: &str) -> Result<HarnessDescriptor, DescriptorError> {
+    finalize_descriptor(&parse_descriptor_value(toml_src, source)?, source)
+}
+
+/// Parse one descriptor file's TOML into a JSON value and schema-check it.
+/// This is the per-file gate every layered source passes individually — the
+/// schema requires only `label`, so partial override files validate here too,
+/// while unknown fields and bad capability names are still rejected with the
+/// file's own path in the message.
+pub fn parse_descriptor_value(
+    toml_src: &str,
+    source: &str,
+) -> Result<serde_json::Value, DescriptorError> {
     let value: serde_json::Value = toml::from_str(toml_src).map_err(|e| DescriptorError::Toml {
         path: source.to_string(),
         message: e.to_string(),
     })?;
-    let descriptor: HarnessDescriptor =
+    let _: serde_json::Value =
         validate_against_schema(SchemaName::HarnessDescriptor, &value, source)?;
-    validation::validate_descriptor(&descriptor, source)?;
+    Ok(value)
+}
+
+/// Merge `overlay` onto `base`, field by field: objects merge recursively per
+/// key; scalars, arrays, and nulls replace wholesale. This is the layering
+/// rule — a later descriptor file overrides individual fields of an earlier
+/// one, never whole-file shadowing.
+pub fn merge_descriptor_value(base: &mut serde_json::Value, overlay: serde_json::Value) {
+    match (base, overlay) {
+        (serde_json::Value::Object(base), serde_json::Value::Object(overlay)) => {
+            for (key, value) in overlay {
+                match base.get_mut(&key) {
+                    Some(slot) if slot.is_object() && value.is_object() => {
+                        merge_descriptor_value(slot, value);
+                    }
+                    _ => {
+                        base.insert(key, value);
+                    }
+                }
+            }
+        }
+        (base, overlay) => *base = overlay,
+    }
+}
+
+/// Deserialize and invariant-check a (possibly merged) descriptor value.
+/// `provenance` names every contributing file (e.g. `base.toml (built-in) +
+/// overlay.toml (project)`) so a post-merge violation is traceable.
+pub fn finalize_descriptor(
+    value: &serde_json::Value,
+    provenance: &str,
+) -> Result<HarnessDescriptor, DescriptorError> {
+    let descriptor: HarnessDescriptor =
+        validate_against_schema(SchemaName::HarnessDescriptor, value, provenance)?;
+    validation::validate_descriptor(&descriptor, provenance)?;
     Ok(descriptor)
 }
 
@@ -400,6 +446,54 @@ armed_message = "guard armed"
         assert!(err.contains("harness-descriptor schema"), "{err}");
     }
 
+    #[test]
+    fn merge_deep_merges_tables_and_replaces_scalars_and_arrays() {
+        let mut base: serde_json::Value = toml::from_str(
+            r#"
+label = "demo"
+config_dirs = [".demo"]
+
+[model]
+flag = "--model"
+
+[dispatch]
+capture_prefix = "demo"
+"#,
+        )
+        .unwrap();
+        let overlay: serde_json::Value = toml::from_str(
+            r#"
+label = "demo"
+config_dirs = [".other"]
+
+[model]
+flag = "--model-x"
+"#,
+        )
+        .unwrap();
+        merge_descriptor_value(&mut base, overlay);
+        // Nested-table scalar replaced; sibling table untouched; array replaced
+        // wholesale (no element-wise merge).
+        assert_eq!(base["model"]["flag"], "--model-x");
+        assert_eq!(base["dispatch"]["capture_prefix"], "demo");
+        assert_eq!(base["config_dirs"], serde_json::json!([".other"]));
+    }
+
+    #[test]
+    fn finalize_names_every_contributing_file_on_invariant_breaks() {
+        // A merged value violating an invariant reports the provenance chain,
+        // not a single path.
+        let value: serde_json::Value =
+            toml::from_str("label = \"demo\"\nskills_dir = \".demo/skills\"\n").unwrap();
+        let err = finalize_descriptor(&value, "base.toml (built-in) + overlay.toml (project)")
+            .expect_err("missing config_dirs parent should be rejected")
+            .to_string();
+        assert!(
+            err.contains("base.toml (built-in) + overlay.toml (project)"),
+            "{err}"
+        );
+    }
+
     #[test]
     fn subst_replaces_tokens_and_passes_unknown_through() {
         let out = subst(
diff --git a/src/adapters/descriptor/layers.rs b/src/adapters/descriptor/layers.rs
index 8209252..47e3db6 100644
--- a/src/adapters/descriptor/layers.rs
+++ b/src/adapters/descriptor/layers.rs
@@ -1,10 +1,18 @@
 //! Descriptor source layers: where a descriptor's TOML text came from.
 //!
-//! Every descriptor source carries its layer and display path so registry
-//! entries can report provenance (`harness list`/`show`) and error messages
-//! can name the contributing file.
+//! Discovery order is precedence order — embedded built-ins, then user-global
+//! (`~/.config/eval-magic/harnesses/*.toml`), then project-local
+//! (`.eval-magic/harnesses/*.toml`), then a one-off `--harness-file`. Later
+//! layers override earlier ones field-by-field (see
+//! [`merge_descriptor_value`](super::merge_descriptor_value)). Every source
+//! carries its layer and display path so registry entries can report
+//! provenance (`harness list`/`show`) and error messages can name the
+//! contributing file.
 
-use super::EMBEDDED_DESCRIPTORS;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use super::{DescriptorError, EMBEDDED_DESCRIPTORS};
 
 /// The layer a descriptor source belongs to, in precedence order (later
 /// layers override earlier ones field-by-field).
@@ -12,6 +20,26 @@ use super::EMBEDDED_DESCRIPTORS;
 pub enum Layer {
     /// A built-in descriptor bundled into the binary (`harnesses/*.toml`).
     Embedded,
+    /// A user-global descriptor (`<config-root>/harnesses/*.toml`, where the
+    /// config root is `$EVAL_MAGIC_CONFIG_DIR`, `$XDG_CONFIG_HOME/eval-magic`,
+    /// or `~/.config/eval-magic`).
+    UserGlobal,
+    /// A project-local descriptor (`<cwd>/.eval-magic/harnesses/*.toml`).
+    ProjectLocal,
+    /// A one-off descriptor passed via `--harness-file <path>`.
+    HarnessFile,
+}
+
+impl Layer {
+    /// The short name `harness list`/`show` and warnings display.
+    pub fn display_name(self) -> &'static str {
+        match self {
+            Layer::Embedded => "built-in",
+            Layer::UserGlobal => "user",
+            Layer::ProjectLocal => "project",
+            Layer::HarnessFile => "file",
+        }
+    }
 }
 
 /// One descriptor source: its layer, a display path for error messages and
@@ -35,9 +63,148 @@ pub fn embedded_sources() -> Vec<DescriptorSource> {
         .collect()
 }
 
+/// A `--harness-file` path that could not be read. Unlike discovered layer
+/// files (skipped with a warning), the explicitly named file is a hard error.
+#[derive(Debug, thiserror::Error)]
+#[error("cannot read --harness-file {path}: {message}")]
+pub struct HarnessFileError {
+    pub path: String,
+    pub message: String,
+}
+
+/// Discover every descriptor source in precedence order: embedded →
+/// user-global → project-local → `--harness-file`. Missing layer directories
+/// are fine (empty layer); unreadable files inside a layer directory are
+/// skipped and reported in the returned warnings. Only the explicit
+/// `--harness-file` fails hard.
+pub fn discover_sources(
+    config_root: Option<&Path>,
+    project_root: &Path,
+    harness_file: Option<&Path>,
+) -> Result<(Vec<DescriptorSource>, Vec<String>), HarnessFileError> {
+    let mut warnings = Vec::new();
+    let mut sources = embedded_sources();
+    if let Some(config_root) = config_root {
+        sources.extend(dir_sources(
+            &config_root.join("harnesses"),
+            Layer::UserGlobal,
+            &mut warnings,
+        ));
+    }
+    sources.extend(dir_sources(
+        &project_root.join(".eval-magic").join("harnesses"),
+        Layer::ProjectLocal,
+        &mut warnings,
+    ));
+    if let Some(file) = harness_file {
+        let toml_src = fs::read_to_string(file).map_err(|e| HarnessFileError {
+            path: file.display().to_string(),
+            message: e.to_string(),
+        })?;
+        sources.push(DescriptorSource {
+            layer: Layer::HarnessFile,
+            path: file.display().to_string(),
+            toml_src,
+        });
+    }
+    Ok((sources, warnings))
+}
+
+/// Every `*.toml` in `dir`, sorted by filename for deterministic layering.
+fn dir_sources(dir: &Path, layer: Layer, warnings: &mut Vec<String>) -> Vec<DescriptorSource> {
+    let Ok(entries) = fs::read_dir(dir) else {
+        // No directory means an empty layer, not an error.
+        return Vec::new();
+    };
+    let mut paths: Vec<PathBuf> = entries
+        .flatten()
+        .map(|e| e.path())
+        .filter(|p| p.extension().is_some_and(|ext| ext == "toml") && p.is_file())
+        .collect();
+    paths.sort();
+    paths
+        .into_iter()
+        .filter_map(|path| match fs::read_to_string(&path) {
+            Ok(toml_src) => Some(DescriptorSource {
+                layer,
+                path: path.display().to_string(),
+                toml_src,
+            }),
+            Err(e) => {
+                warnings.push(format!(
+                    "skipping unreadable harness descriptor {}: {e}",
+                    path.display()
+                ));
+                None
+            }
+        })
+        .collect()
+}
+
+/// Resolve the user-global config root from explicit/env inputs:
+/// `$EVAL_MAGIC_CONFIG_DIR` verbatim (empty disables the layer), else
+/// `$XDG_CONFIG_HOME/eval-magic`, else `<home>/.config/eval-magic`.
+pub fn config_root_from(
+    explicit: Option<&str>,
+    xdg_config_home: Option<&str>,
+    home: Option<&Path>,
+) -> Option<PathBuf> {
+    if let Some(explicit) = explicit {
+        if explicit.is_empty() {
+            return None;
+        }
+        return Some(PathBuf::from(explicit));
+    }
+    if let Some(xdg) = xdg_config_home
+        && !xdg.is_empty()
+    {
+        return Some(Path::new(xdg).join("eval-magic"));
+    }
+    home.map(|home| home.join(".config").join("eval-magic"))
+}
+
+/// [`config_root_from`] over the live environment.
+pub fn default_config_root() -> Option<PathBuf> {
+    config_root_from(
+        std::env::var("EVAL_MAGIC_CONFIG_DIR").ok().as_deref(),
+        std::env::var("XDG_CONFIG_HOME").ok().as_deref(),
+        std::env::home_dir().as_deref(),
+    )
+}
+
+/// Reject descriptor content user-supplied files may not declare: the write
+/// guard installs native hook config into dispatch environments, so it stays
+/// restricted to built-in descriptors until the guard engine is opened up.
+/// The check runs on each file's own content, so a user overlay of a guarded
+/// built-in still inherits the embedded guard cleanly.
+pub fn check_user_layer_restrictions(
+    value: &serde_json::Value,
+    path: &str,
+) -> Result<(), DescriptorError> {
+    let declares_guard = value.get("guard").is_some();
+    let flips_support = value
+        .pointer("/run/supports_guard")
+        .and_then(serde_json::Value::as_bool)
+        == Some(true);
+    if declares_guard || flips_support {
+        return Err(DescriptorError::Invariant {
+            path: path.to_string(),
+            message: "user-supplied descriptors may not declare [guard] or set \
+                      run.supports_guard = true — the write guard installs native hook \
+                      config and stays restricted to built-in descriptors until the guard \
+                      engine is opened up (see the guard-engine follow-up issue). Remove \
+                      it; unguarded runs fall back to the detect-stray-writes audit."
+                .to_string(),
+        });
+    }
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::fs;
+    use std::path::Path;
 
     #[test]
     fn embedded_sources_cover_every_bundled_descriptor() {
@@ -47,4 +214,128 @@ mod tests {
         assert_eq!(sources[0].path, "harnesses/claude-code.toml");
         assert!(!sources[0].toml_src.is_empty());
     }
+
+    #[test]
+    fn user_layer_may_not_declare_a_guard_table() {
+        let value: serde_json::Value = toml::from_str(
+            "label = \"demo\"\n\n[guard]\nengine = \"claude-hooks\"\narmed_message = \"x\"\n",
+        )
+        .unwrap();
+        let err = check_user_layer_restrictions(&value, "user.toml")
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("user.toml"), "{err}");
+        assert!(err.contains("may not declare [guard]"), "{err}");
+        assert!(
+            err.contains("detect-stray-writes"),
+            "names the fallback: {err}"
+        );
+    }
+
+    #[test]
+    fn user_layer_may_not_flip_supports_guard_on() {
+        let value: serde_json::Value =
+            toml::from_str("label = \"demo\"\n\n[run]\nsupports_guard = true\n").unwrap();
+        let err = check_user_layer_restrictions(&value, "user.toml")
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("run.supports_guard"), "{err}");
+    }
+
+    #[test]
+    fn user_layer_restrictions_pass_everything_else() {
+        let value: serde_json::Value = toml::from_str(
+            "label = \"demo\"\n\n[run]\nsupports_guard = false\n\n[model]\nflag = \"-m\"\n",
+        )
+        .unwrap();
+        assert!(check_user_layer_restrictions(&value, "user.toml").is_ok());
+    }
+
+    #[test]
+    fn config_root_prefers_explicit_env_then_xdg_then_home() {
+        assert_eq!(
+            config_root_from(Some("/explicit"), Some("/xdg"), Some(Path::new("/home/u"))),
+            Some("/explicit".into())
+        );
+        assert_eq!(
+            config_root_from(None, Some("/xdg"), Some(Path::new("/home/u"))),
+            Some("/xdg/eval-magic".into())
+        );
+        assert_eq!(
+            config_root_from(None, None, Some(Path::new("/home/u"))),
+            Some("/home/u/.config/eval-magic".into())
+        );
+        assert_eq!(config_root_from(None, None, None), None);
+    }
+
+    #[test]
+    fn empty_config_dir_env_disables_the_user_layer() {
+        assert_eq!(
+            config_root_from(Some(""), Some("/xdg"), Some(Path::new("/home/u"))),
+            None
+        );
+    }
+
+    #[test]
+    fn discovery_layers_in_precedence_order() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let config_root = tmp.path().join("config");
+        let project_root = tmp.path().join("project");
+        let user_dir = config_root.join("harnesses");
+        let project_dir = project_root.join(".eval-magic").join("harnesses");
+        fs::create_dir_all(&user_dir).unwrap();
+        fs::create_dir_all(&project_dir).unwrap();
+        // Written out of name order to prove the filename sort.
+        fs::write(user_dir.join("b.toml"), "label = \"bee\"\n").unwrap();
+        fs::write(user_dir.join("a.toml"), "label = \"ay\"\n").unwrap();
+        fs::write(user_dir.join("notes.md"), "not a descriptor").unwrap();
+        fs::write(project_dir.join("p.toml"), "label = \"pea\"\n").unwrap();
+        let file = tmp.path().join("one-off.toml");
+        fs::write(&file, "label = \"one-off\"\n").unwrap();
+
+        let (sources, warnings) =
+            discover_sources(Some(&config_root), &project_root, Some(&file)).unwrap();
+        assert!(warnings.is_empty(), "{warnings:?}");
+        let tail: Vec<(Layer, &str)> = sources[EMBEDDED_DESCRIPTORS.len()..]
+            .iter()
+            .map(|s| (s.layer, s.path.as_str()))
+            .collect();
+        assert_eq!(sources[0].layer, Layer::Embedded);
+        assert_eq!(
+            tail,
+            vec![
+                (Layer::UserGlobal, user_dir.join("a.toml").to_str().unwrap()),
+                (Layer::UserGlobal, user_dir.join("b.toml").to_str().unwrap()),
+                (
+                    Layer::ProjectLocal,
+                    project_dir.join("p.toml").to_str().unwrap()
+                ),
+                (Layer::HarnessFile, file.to_str().unwrap()),
+            ]
+        );
+    }
+
+    #[test]
+    fn discovery_tolerates_missing_layer_dirs() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let (sources, warnings) = discover_sources(
+            Some(&tmp.path().join("nope")),
+            &tmp.path().join("also-nope"),
+            None,
+        )
+        .unwrap();
+        assert_eq!(sources.len(), EMBEDDED_DESCRIPTORS.len());
+        assert!(warnings.is_empty(), "{warnings:?}");
+    }
+
+    #[test]
+    fn discovery_fails_hard_on_an_unreadable_harness_file() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let missing = tmp.path().join("missing.toml");
+        let err = discover_sources(None, tmp.path(), Some(&missing))
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("--harness-file"), "{err}");
+        assert!(err.contains("missing.toml"), "{err}");
+    }
 }
diff --git a/src/adapters/registry.rs b/src/adapters/registry.rs
index a7c1e61..1158f77 100644
--- a/src/adapters/registry.rs
+++ b/src/adapters/registry.rs
@@ -7,12 +7,19 @@
 //! and the artifact `Deserialize`), [`Harness::known`] enumerates the entries,
 //! and [`adapter_for`] serves each handle's [`HarnessAdapter`].
 
+use std::path::Path;
 use std::sync::{LazyLock, OnceLock};
 
 use crate::core::Harness;
 
-use super::descriptor::layers::{DescriptorSource, Layer, embedded_sources};
-use super::descriptor::{DescriptorError, load_descriptor};
+use super::descriptor::layers::{
+    DescriptorSource, HarnessFileError, Layer, check_user_layer_restrictions, default_config_root,
+    discover_sources, embedded_sources,
+};
+use super::descriptor::{
+    DescriptorError, HarnessDescriptor, finalize_descriptor, merge_descriptor_value,
+    parse_descriptor_value,
+};
 use super::descriptor_adapter::DescriptorAdapter;
 use super::harness::{HarnessAdapter, ToolVocabulary};
 
@@ -40,12 +47,66 @@ fn registry() -> &'static Vec<RegistryEntry> {
         // the descriptor's own actionable message.
         build_registry(embedded_sources())
             .unwrap_or_else(|e| panic!("bundled harness descriptor is invalid: {e}"))
+            .entries
     })
 }
 
-/// A descriptor source set that cannot form a registry.
+/// The registry could not be initialized from the layered sources.
 #[derive(Debug, thiserror::Error)]
-enum RegistryBuildError {
+pub enum RegistryInitError {
+    #[error(transparent)]
+    HarnessFile(#[from] HarnessFileError),
+    #[error(transparent)]
+    Build(#[from] RegistryBuildError),
+    #[error("the harness registry is already initialized")]
+    AlreadyInitialized,
+}
+
+/// When `--harness-file` is in play, its descriptor's label — consulted by
+/// `Default for Harness` so the one-off harness doesn't have to be repeated
+/// via `--harness`.
+static SESSION_DEFAULT_HARNESS: OnceLock<&'static str> = OnceLock::new();
+
+/// Initialize the registry from every descriptor layer: embedded built-ins →
+/// user-global (`<config-root>/harnesses/*.toml`) → project-local
+/// (`<cwd>/.eval-magic/harnesses/*.toml`) → the optional one-off
+/// `--harness-file`. Called once by the CLI entry point, before anything
+/// resolves a harness.
+///
+/// Discovered files that fail to load are skipped with a warning on stderr
+/// (pointing at `harness lint`); a broken `--harness-file` is a hard error.
+/// When `--harness-file` names a descriptor, its label becomes the session's
+/// default harness.
+pub fn init_registry(harness_file: Option<&Path>) -> Result<(), RegistryInitError> {
+    let project_root = std::env::current_dir().unwrap_or_default();
+    let (sources, io_warnings) = discover_sources(
+        default_config_root().as_deref(),
+        &project_root,
+        harness_file,
+    )?;
+    let built = build_registry(sources)?;
+    for warning in io_warnings.iter().chain(&built.warnings) {
+        eprintln!("⚠ {warning}");
+    }
+    if harness_file.is_some()
+        && let Some(entry) = built
+            .entries
+            .iter()
+            .find(|e| e.sources.iter().any(|(l, _)| *l == Layer::HarnessFile))
+    {
+        let _ = SESSION_DEFAULT_HARNESS.set(entry.label);
+    }
+    REGISTRY
+        .set(built.entries)
+        .map_err(|_| RegistryInitError::AlreadyInitialized)
+}
+
+/// A descriptor source set that cannot form a registry. Only embedded and
+/// `--harness-file` sources can produce this — discovered layer files fail
+/// soft (skipped with a warning in [`BuiltRegistry::warnings`]) so a broken
+/// user descriptor never bricks the CLI.
+#[derive(Debug, thiserror::Error)]
+pub enum RegistryBuildError {
     #[error(transparent)]
     Descriptor(#[from] DescriptorError),
     #[error("duplicate harness label {label:?}: {first} and {second}")]
@@ -56,38 +117,134 @@ enum RegistryBuildError {
     },
 }
 
-/// Load descriptor sources into registry entries, keyed by each descriptor's
-/// `label`. The label is the harness identity — `--harness <label>`, artifact
-/// values, and adapter lookup all resolve through it — so two sources
-/// producing the same label collide.
-fn build_registry(
-    sources: Vec<DescriptorSource>,
-) -> Result<Vec<RegistryEntry>, RegistryBuildError> {
-    let mut entries: Vec<RegistryEntry> = Vec::new();
+/// The outcome of loading a layered source set: the label-keyed entries plus
+/// the warnings for every discovered file that was skipped.
+#[derive(Debug)]
+struct BuiltRegistry {
+    entries: Vec<RegistryEntry>,
+    warnings: Vec<String>,
+}
+
+/// One label's in-progress state while folding layered sources.
+struct PendingEntry {
+    label: String,
+    value: serde_json::Value,
+    descriptor: HarnessDescriptor,
+    sources: Vec<(Layer, String)>,
+}
+
+/// Load descriptor sources into label-keyed entries with layered overrides.
+///
+/// Sources arrive in precedence order. The first source for a label defines
+/// it; a later source with the same label from a *different* layer merges
+/// field-by-field on top ([`merge_descriptor_value`]) and the merged result is
+/// re-validated with the full provenance chain in its error messages. Two
+/// same-label files within one layer have no precedence between them, so the
+/// second is rejected (fatal for embedded, a skip-warning otherwise).
+///
+/// Failure policy per layer: embedded sources are known-valid (a failure is a
+/// programmer error, propagated), `--harness-file` was explicitly named (a
+/// failure is the user's answer, propagated), and discovered user/project
+/// files fail soft — the file is skipped, the message lands in
+/// [`BuiltRegistry::warnings`], and any earlier state for that label survives.
+fn build_registry(sources: Vec<DescriptorSource>) -> Result<BuiltRegistry, RegistryBuildError> {
+    let mut pending: Vec<PendingEntry> = Vec::new();
+    let mut warnings: Vec<String> = Vec::new();
     for source in sources {
-        let descriptor = load_descriptor(&source.toml_src, &source.path)?;
-        if let Some(existing) = entries.iter().find(|e| e.label == descriptor.label) {
-            return Err(RegistryBuildError::DuplicateLabel {
-                label: descriptor.label,
-                first: existing
+        let strict = matches!(source.layer, Layer::Embedded | Layer::HarnessFile);
+        let mut fail_soft = |e: RegistryBuildError| -> Result<(), RegistryBuildError> {
+            if strict {
+                Err(e)
+            } else {
+                warnings.push(format!(
+                    "skipping harness descriptor: {e}\n  (run `eval-magic harness lint <file>` \
+                     for the full report)"
+                ));
+                Ok(())
+            }
+        };
+
+        let value = match parse_descriptor_value(&source.toml_src, &source.path) {
+            Ok(value) => value,
+            Err(e) => {
+                fail_soft(e.into())?;
+                continue;
+            }
+        };
+        if source.layer != Layer::Embedded
+            && let Err(e) = check_user_layer_restrictions(&value, &source.path)
+        {
+            fail_soft(e.into())?;
+            continue;
+        }
+        let label = value
+            .get("label")
+            .and_then(serde_json::Value::as_str)
+            .expect("the schema gate requires a string label")
+            .to_string();
+
+        match pending.iter().position(|p| p.label == label) {
+            None => match finalize_descriptor(&value, &source.path) {
+                Ok(descriptor) => pending.push(PendingEntry {
+                    label,
+                    value,
+                    descriptor,
+                    sources: vec![(source.layer, source.path)],
+                }),
+                Err(e) => fail_soft(e.into())?,
+            },
+            Some(index) => {
+                let entry = &mut pending[index];
+                let (last_layer, last_path) = entry
                     .sources
                     .last()
-                    .expect("every entry records its source")
-                    .1
-                    .clone(),
-                second: source.path,
-            });
+                    .expect("every entry records its source");
+                if *last_layer == source.layer {
+                    fail_soft(RegistryBuildError::DuplicateLabel {
+                        label,
+                        first: last_path.clone(),
+                        second: source.path,
+                    })?;
+                    continue;
+                }
+                let mut merged = entry.value.clone();
+                merge_descriptor_value(&mut merged, value);
+                let provenance = provenance_chain(&entry.sources, &source);
+                match finalize_descriptor(&merged, &provenance) {
+                    Ok(descriptor) => {
+                        entry.value = merged;
+                        entry.descriptor = descriptor;
+                        entry.sources.push((source.layer, source.path));
+                    }
+                    Err(e) => fail_soft(e.into())?,
+                }
+            }
         }
-        // Leaked once per registry entry per process: the label becomes the
-        // `'static` identity the rest of the crate passes around by handle.
-        let label: &'static str = Box::leak(descriptor.label.clone().into_boxed_str());
-        entries.push(RegistryEntry {
-            label,
-            sources: vec![(source.layer, source.path)],
-            adapter: DescriptorAdapter::from_descriptor(descriptor),
-        });
     }
-    Ok(entries)
+
+    let entries = pending
+        .into_iter()
+        .map(|p| RegistryEntry {
+            // Leaked once per registry entry per process: the label becomes
+            // the `'static` identity the rest of the crate passes around by
+            // handle.
+            label: Box::leak(p.label.into_boxed_str()),
+            sources: p.sources,
+            adapter: DescriptorAdapter::from_descriptor(p.descriptor),
+        })
+        .collect();
+    Ok(BuiltRegistry { entries, warnings })
+}
+
+/// `base.toml (built-in) + overlay.toml (project)` — the provenance string a
+/// merged descriptor's validation errors carry.
+fn provenance_chain(sources: &[(Layer, String)], next: &DescriptorSource) -> String {
+    sources
+        .iter()
+        .map(|(layer, path)| format!("{path} ({})", layer.display_name()))
+        .chain([format!("{} ({})", next.path, next.layer.display_name())])
+        .collect::<Vec<_>>()
+        .join(" + ")
 }
 
 /// The registry-level default harness — what `--harness` falls back to when
@@ -132,8 +289,13 @@ impl Harness {
 
 impl Default for Harness {
     fn default() -> Self {
-        Harness::resolve(DEFAULT_HARNESS_NAME)
-            .expect("the embedded registry contains the default harness")
+        // A `--harness-file` descriptor becomes the session default, so the
+        // one-off harness doesn't have to be repeated via `--harness`.
+        let name = SESSION_DEFAULT_HARNESS
+            .get()
+            .copied()
+            .unwrap_or(DEFAULT_HARNESS_NAME);
+        Harness::resolve(name).expect("the session default resolves against the registry")
     }
 }
 
@@ -223,8 +385,16 @@ mod tests {
         assert_eq!(vocab.read_tools, ["Glob", "Grep", "Read"]);
     }
 
+    fn src(layer: Layer, path: &str, toml_src: &str) -> DescriptorSource {
+        DescriptorSource {
+            layer,
+            path: path.to_string(),
+            toml_src: toml_src.to_string(),
+        }
+    }
+
     #[test]
-    fn duplicate_label_in_same_layer_errors() {
+    fn duplicate_embedded_label_errors() {
         let mut sources = embedded_sources();
         sources.push(sources[0].clone());
         let err = build_registry(sources).unwrap_err().to_string();
@@ -238,9 +408,10 @@ mod tests {
 
     #[test]
     fn registry_entries_record_embedded_provenance() {
-        let entries = build_registry(embedded_sources()).unwrap();
-        assert_eq!(entries.len(), EMBEDDED_DESCRIPTORS.len());
-        for entry in &entries {
+        let built = build_registry(embedded_sources()).unwrap();
+        assert!(built.warnings.is_empty(), "{:?}", built.warnings);
+        assert_eq!(built.entries.len(), EMBEDDED_DESCRIPTORS.len());
+        for entry in &built.entries {
             assert_eq!(entry.sources.len(), 1, "one contributing file per built-in");
             assert_eq!(entry.sources[0].0, Layer::Embedded);
             assert!(
@@ -251,6 +422,190 @@ mod tests {
         }
     }
 
+    #[test]
+    fn project_layer_overrides_a_single_field_of_a_builtin() {
+        let mut sources = embedded_sources();
+        sources.push(src(
+            Layer::ProjectLocal,
+            ".eval-magic/harnesses/claude-code.toml",
+            "label = \"claude-code\"\n\n[model]\nflag = \"--model-x\"\n",
+        ));
+        let built = build_registry(sources).unwrap();
+        assert!(built.warnings.is_empty(), "{:?}", built.warnings);
+        assert_eq!(built.entries.len(), EMBEDDED_DESCRIPTORS.len());
+        let entry = built
+            .entries
+            .iter()
+            .find(|e| e.label == "claude-code")
+            .unwrap();
+        // The overridden field changed; everything else survives from the
+        // embedded base (field-level merge, not file shadowing).
+        assert_eq!(entry.adapter.cli_model_flag(), Some("--model-x".into()));
+        assert!(entry.adapter.run_capabilities().supports_guard);
+        assert_eq!(
+            entry.sources,
+            vec![
+                (Layer::Embedded, "harnesses/claude-code.toml".to_string()),
+                (
+                    Layer::ProjectLocal,
+                    ".eval-magic/harnesses/claude-code.toml".to_string()
+                ),
+            ]
+        );
+    }
+
+    #[test]
+    fn new_label_in_a_user_layer_registers_a_new_harness() {
+        let mut sources = embedded_sources();
+        sources.push(src(
+            Layer::ProjectLocal,
+            ".eval-magic/harnesses/cool.toml",
+            "label = \"cool-custom-harness\"\n",
+        ));
+        let built = build_registry(sources).unwrap();
+        assert!(built.warnings.is_empty(), "{:?}", built.warnings);
+        let entry = built
+            .entries
+            .iter()
+            .find(|e| e.label == "cool-custom-harness")
+            .expect("new harness registered");
+        assert_eq!(entry.sources[0].0, Layer::ProjectLocal);
+        assert!(entry.adapter.skills_dir(Path::new("/r")).is_none());
+    }
+
+    #[test]
+    fn discovered_file_declaring_a_guard_warns_and_is_skipped() {
+        let mut sources = embedded_sources();
+        sources.push(src(
+            Layer::ProjectLocal,
+            ".eval-magic/harnesses/armed.toml",
+            "label = \"armed\"\n\n[guard]\nengine = \"claude-hooks\"\narmed_message = \"x\"\n",
+        ));
+        let built = build_registry(sources).unwrap();
+        assert_eq!(
+            built.entries.len(),
+            EMBEDDED_DESCRIPTORS.len(),
+            "file skipped"
+        );
+        assert_eq!(built.warnings.len(), 1);
+        assert!(
+            built.warnings[0].contains("may not declare [guard]"),
+            "{}",
+            built.warnings[0]
+        );
+    }
+
+    #[test]
+    fn discovered_overlay_breaking_invariants_warns_and_keeps_the_base() {
+        let mut sources = embedded_sources();
+        // Replacing config_dirs orphans skills_dir's parent — an invariant
+        // break that only shows post-merge.
+        sources.push(src(
+            Layer::ProjectLocal,
+            ".eval-magic/harnesses/claude-code.toml",
+            "label = \"claude-code\"\nconfig_dirs = [\".other\"]\n",
+        ));
+        let built = build_registry(sources).unwrap();
+        assert_eq!(built.warnings.len(), 1);
+        assert!(
+            built.warnings[0].contains(".eval-magic/harnesses/claude-code.toml"),
+            "names the offending file: {}",
+            built.warnings[0]
+        );
+        let entry = built
+            .entries
+            .iter()
+            .find(|e| e.label == "claude-code")
+            .unwrap();
+        assert_eq!(
+            entry.adapter.config_dir_names(),
+            vec![".claude".to_string()],
+            "embedded base survives the dropped overlay"
+        );
+        assert_eq!(
+            entry.sources.len(),
+            1,
+            "the bad overlay records no provenance"
+        );
+    }
+
+    #[test]
+    fn same_label_twice_in_one_discovered_layer_warns_and_skips_the_second() {
+        let mut sources = embedded_sources();
+        sources.push(src(
+            Layer::ProjectLocal,
+            "a.toml",
+            "label = \"claude-code\"\n\n[model]\nflag = \"--from-a\"\n",
+        ));
+        sources.push(src(
+            Layer::ProjectLocal,
+            "b.toml",
+            "label = \"claude-code\"\n\n[model]\nflag = \"--from-b\"\n",
+        ));
+        let built = build_registry(sources).unwrap();
+        assert_eq!(built.warnings.len(), 1);
+        assert!(
+            built.warnings[0].contains("a.toml"),
+            "{}",
+            built.warnings[0]
+        );
+        assert!(
+            built.warnings[0].contains("b.toml"),
+            "{}",
+            built.warnings[0]
+        );
+        let entry = built
+            .entries
+            .iter()
+            .find(|e| e.label == "claude-code")
+            .unwrap();
+        assert_eq!(entry.adapter.cli_model_flag(), Some("--from-a".into()));
+    }
+
+    #[test]
+    fn harness_file_failures_are_fatal() {
+        let mut sources = embedded_sources();
+        sources.push(src(Layer::HarnessFile, "one-off.toml", "label = "));
+        let err = build_registry(sources).unwrap_err().to_string();
+        assert!(err.contains("one-off.toml"), "{err}");
+    }
+
+    #[test]
+    fn harness_file_guard_rejection_is_fatal() {
+        let mut sources = embedded_sources();
+        sources.push(src(
+            Layer::HarnessFile,
+            "one-off.toml",
+            "label = \"armed\"\n\n[guard]\nengine = \"claude-hooks\"\narmed_message = \"x\"\n",
+        ));
+        let err = build_registry(sources).unwrap_err().to_string();
+        assert!(err.contains("may not declare [guard]"), "{err}");
+    }
+
+    #[test]
+    fn harness_file_overlay_merges_on_top_of_discovered_layers() {
+        let mut sources = embedded_sources();
+        sources.push(src(
+            Layer::ProjectLocal,
+            "p.toml",
+            "label = \"claude-code\"\n\n[model]\nflag = \"--from-project\"\n",
+        ));
+        sources.push(src(
+            Layer::HarnessFile,
+            "one-off.toml",
+            "label = \"claude-code\"\n\n[model]\nflag = \"--from-file\"\n",
+        ));
+        let built = build_registry(sources).unwrap();
+        assert!(built.warnings.is_empty(), "{:?}", built.warnings);
+        let entry = built
+            .entries
+            .iter()
+            .find(|e| e.label == "claude-code")
+            .unwrap();
+        assert_eq!(entry.adapter.cli_model_flag(), Some("--from-file".into()));
+        assert_eq!(entry.sources.len(), 3);
+    }
+
     #[test]
     fn resolve_unknown_name_lists_known_harnesses() {
         let err = Harness::resolve("nonexistent").unwrap_err().to_string();
diff --git a/src/cli/args.rs b/src/cli/args.rs
index 43456f7..43417cf 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -33,6 +33,16 @@ use clap::{Args, Parser, Subcommand};
     after_help = super::help::AFTER_HELP
 )]
 pub(crate) struct Cli {
+    /// Load a one-off harness descriptor file as the top registry layer.
+    ///
+    /// The file merges field-by-field onto any registered harness with the same
+    /// `label` (or defines a new one), exactly like a project-local descriptor
+    /// in `.eval-magic/harnesses/`, and — when `--harness` is omitted — its
+    /// label becomes the invocation's default harness. Unlike discovered
+    /// descriptor files (skipped with a warning when broken), errors in this
+    /// explicitly named file are fatal.
+    #[arg(long, global = true, value_name = "PATH")]
+    pub harness_file: Option<String>,
     #[command(subcommand)]
     pub command: Option<Commands>,
 }
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 6186b7a..6bc07f3 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -21,10 +21,13 @@ mod run;
 use args::{Cli, Commands, CommonArgs, RunArgs};
 use commands::*;
 
-/// Parse process arguments, dispatch to the selected subcommand, and return its
-/// result. Called by the binary entry point.
+/// Parse process arguments, initialize the harness descriptor registry (every
+/// layer, including an optional `--harness-file`), dispatch to the selected
+/// subcommand, and return its result. Called by the binary entry point.
 pub fn run() -> anyhow::Result<()> {
-    dispatch(Cli::parse().command)
+    let cli = Cli::parse();
+    crate::adapters::registry::init_registry(cli.harness_file.as_deref().map(Path::new))?;
+    dispatch(cli.command)
 }
 
 fn dispatch(command: Option<Commands>) -> anyhow::Result<()> {
diff --git a/tests/cli/harness.rs b/tests/cli/harness.rs
new file mode 100644
index 0000000..f29c861
--- /dev/null
+++ b/tests/cli/harness.rs
@@ -0,0 +1,135 @@
+//! Layered harness-descriptor discovery: user-global and project-local
+//! descriptor files, the one-off `--harness-file`, and the fail-soft policy
+//! for broken discovered files.
+
+use crate::helpers::skill_eval;
+use predicates::prelude::PredicateBooleanExt;
+use predicates::str::contains;
+use std::fs;
+use std::path::Path;
+use tempfile::TempDir;
+
+/// Write `<root>/.eval-magic/harnesses/<file>` with the given TOML.
+fn write_project_descriptor(root: &Path, file: &str, contents: &str) {
+    let dir = root.join(".eval-magic").join("harnesses");
+    fs::create_dir_all(&dir).unwrap();
+    fs::write(dir.join(file), contents).unwrap();
+}
+
+#[test]
+fn project_local_descriptor_registers_a_new_harness() {
+    let tmp = TempDir::new().unwrap();
+    write_project_descriptor(tmp.path(), "cool.toml", "label = \"cool-custom-harness\"\n");
+
+    // The command still fails later (no skill context), but the harness name
+    // resolves — the registry saw the project-local layer.
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["aggregate", "--harness", "cool-custom-harness"])
+        .assert()
+        .failure()
+        .stderr(contains("unknown harness").not());
+}
+
+#[test]
+fn unknown_harness_error_lists_discovered_harnesses() {
+    let tmp = TempDir::new().unwrap();
+    write_project_descriptor(tmp.path(), "cool.toml", "label = \"cool-custom-harness\"\n");
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["aggregate", "--harness", "nonexistent"])
+        .assert()
+        .failure()
+        .stderr(
+            contains("unknown harness 'nonexistent'")
+                .and(contains("claude-code"))
+                .and(contains("cool-custom-harness")),
+        );
+}
+
+#[test]
+fn user_global_layer_is_discovered_via_config_dir_env() {
+    let tmp = TempDir::new().unwrap();
+    let config_root = tmp.path().join("config");
+    let dir = config_root.join("harnesses");
+    fs::create_dir_all(&dir).unwrap();
+    fs::write(dir.join("cool.toml"), "label = \"cool-custom-harness\"\n").unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .env("EVAL_MAGIC_CONFIG_DIR", &config_root)
+        .args(["aggregate", "--harness", "cool-custom-harness"])
+        .assert()
+        .failure()
+        .stderr(contains("unknown harness").not());
+}
+
+#[test]
+fn harness_file_registers_a_one_off_harness() {
+    let tmp = TempDir::new().unwrap();
+    let file = tmp.path().join("cool.toml");
+    fs::write(&file, "label = \"cool-custom-harness\"\n").unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .arg("aggregate")
+        .arg("--harness-file")
+        .arg(&file)
+        .args(["--harness", "cool-custom-harness"])
+        .assert()
+        .failure()
+        .stderr(contains("unknown harness").not());
+}
+
+#[test]
+fn broken_project_local_descriptor_warns_but_never_bricks() {
+    let tmp = TempDir::new().unwrap();
+    write_project_descriptor(
+        tmp.path(),
+        "broken.toml",
+        "label = \"broken\"\nmystery = 1\n",
+    );
+
+    // The built-in harness still resolves; the broken file is skipped with a
+    // warning that points at the lint command.
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["aggregate", "--harness", "claude-code"])
+        .assert()
+        .failure()
+        .stderr(
+            contains("skipping harness descriptor")
+                .and(contains("harness lint"))
+                .and(contains("unknown harness").not()),
+        );
+}
+
+#[test]
+fn broken_harness_file_is_fatal() {
+    let tmp = TempDir::new().unwrap();
+    let file = tmp.path().join("broken.toml");
+    fs::write(&file, "label = ").unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .arg("aggregate")
+        .arg("--harness-file")
+        .arg(&file)
+        .assert()
+        .failure()
+        .stderr(contains("broken.toml").and(contains("invalid TOML")));
+}
+
+#[test]
+fn missing_harness_file_is_fatal() {
+    let tmp = TempDir::new().unwrap();
+    skill_eval()
+        .current_dir(tmp.path())
+        .arg("aggregate")
+        .arg("--harness-file")
+        .arg(tmp.path().join("missing.toml"))
+        .assert()
+        .failure()
+        .stderr(contains("--harness-file").and(contains("missing.toml")));
+}
diff --git a/tests/cli/helpers.rs b/tests/cli/helpers.rs
index eae12dc..bc34b2f 100644
--- a/tests/cli/helpers.rs
+++ b/tests/cli/helpers.rs
@@ -7,7 +7,11 @@ use tempfile::TempDir;
 
 /// Build a `Command` for the built `eval-magic` binary.
 pub fn skill_eval() -> Command {
-    Command::cargo_bin("eval-magic").expect("binary `eval-magic` should build")
+    let mut cmd = Command::cargo_bin("eval-magic").expect("binary `eval-magic` should build");
+    // Disable user-global descriptor discovery so a developer's
+    // ~/.config/eval-magic/harnesses never leaks into the tests.
+    cmd.env("EVAL_MAGIC_CONFIG_DIR", "");
+    cmd
 }
 
 /// A canonicalized temp root (resolves macOS /var → /private/var so the binary's
diff --git a/tests/cli/main.rs b/tests/cli/main.rs
index ef77a55..75424ea 100644
--- a/tests/cli/main.rs
+++ b/tests/cli/main.rs
@@ -13,6 +13,7 @@ mod basics;
 mod grade;
 mod grade_models;
 mod guard;
+mod harness;
 mod init;
 mod package;
 mod stray_writes;
diff --git a/tests/run/helpers.rs b/tests/run/helpers.rs
index 5e3a96d..e752ab7 100644
--- a/tests/run/helpers.rs
+++ b/tests/run/helpers.rs
@@ -10,7 +10,11 @@ pub const STAGED_MANIFEST: &str = ".slow-powers-eval-manifest.json";
 pub const DEFAULT_EVALS: &str = r#"{ "skill_name": "mr-review", "evals": [ { "id": "e1", "prompt": "review this MR", "expected_output": "a review" } ] }"#;
 
 pub fn skill_eval() -> Command {
-    Command::cargo_bin("eval-magic").expect("binary `eval-magic` should build")
+    let mut cmd = Command::cargo_bin("eval-magic").expect("binary `eval-magic` should build");
+    // Disable user-global descriptor discovery so a developer's
+    // ~/.config/eval-magic/harnesses never leaks into the tests.
+    cmd.env("EVAL_MAGIC_CONFIG_DIR", "");
+    cmd
 }
 
 /// Build `<root>/skill-dir/mr-review/{SKILL.md,evals/evals.json}` and a `work`

From 3453d8b22dd395fd56e1a4447ca807392d31a8c1 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:31:10 -0400
Subject: [PATCH 05/10] feat(cli): harness list, show, and lint subcommands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

harness list surveys the registry — label (with the session default
marked), contributing layers (built-in + project when merged), and the
enhancements each resolved descriptor declares. harness show prints one
harness's resolved post-merge descriptor as authorable TOML behind a
provenance comment header, ready to copy into a layer file; descriptor
structs gain Serialize (defaults omitted) and the toml dependency turns
on display for it. harness lint validates a descriptor file — TOML +
schema, the user-layer guard restriction, and cross-field invariants
merged onto the registered harness with the same label, so partial
overrides are checked against their real merge target — or, given a
name, strictly re-lints every discovered layer file, surfacing exactly
what registry init skipped with a warning. ✓/✗ report lines follow the
validate idiom; a reserved --probe live-dispatch check is documented as
deferred.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 Cargo.lock                            |   7 +
 Cargo.toml                            |   7 +-
 src/adapters/capabilities.rs          |  10 +-
 src/adapters/descriptor.rs            | 130 +++++++++---
 src/adapters/descriptor/validation.rs |  17 +-
 src/adapters/descriptor_adapter.rs    |   6 +
 src/adapters/registry.rs              |  42 +++-
 src/cli/args.rs                       |  60 ++++++
 src/cli/commands/harness.rs           | 284 ++++++++++++++++++++++++++
 src/cli/commands/mod.rs               |   2 +
 src/cli/mod.rs                        |   1 +
 tests/cli/harness.rs                  | 194 ++++++++++++++++++
 12 files changed, 706 insertions(+), 54 deletions(-)
 create mode 100644 src/cli/commands/harness.rs

diff --git a/Cargo.lock b/Cargo.lock
index 851c6b0..149d274 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1047,6 +1047,7 @@ dependencies = [
  "serde_spanned",
  "toml_datetime",
  "toml_parser",
+ "toml_writer",
  "winnow 0.7.15",
 ]
 
@@ -1068,6 +1069,12 @@ dependencies = [
  "winnow 1.0.3",
 ]
 
+[[package]]
+name = "toml_writer"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "756daf9b1013ebe47a8776667b466417e2d4c5679d441c26230efd9ef78692db"
+
 [[package]]
 name = "unicode-general-category"
 version = "1.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index 7e10e34..0e74a50 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -44,9 +44,10 @@ regex = { version = "1.12.3", default-features = false, features = ["std", "perf
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["preserve_order"] }
 thiserror = "2.0.18"
-# Harness descriptor files (harnesses/*.toml). Parse-only: descriptors are
-# embedded and read, never written, so `display` is dropped.
-toml = { version = "0.9", default-features = false, features = ["parse", "serde"] }
+# Harness descriptor files (harnesses/*.toml). `display` serializes the
+# resolved (layer-merged) descriptor back to authorable TOML for
+# `harness show`.
+toml = { version = "0.9", default-features = false, features = ["parse", "serde", "display"] }
 walkdir = "2.5.0"
 
 [dev-dependencies]
diff --git a/src/adapters/capabilities.rs b/src/adapters/capabilities.rs
index 2449b8e..83a3f5c 100644
--- a/src/adapters/capabilities.rs
+++ b/src/adapters/capabilities.rs
@@ -15,7 +15,7 @@ use std::io;
 use std::path::{Path, PathBuf};
 use std::time::Duration;
 
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 
 use crate::core::ToolInvocation;
 
@@ -24,7 +24,7 @@ use super::skill_shadow::PluginShadowReport;
 
 /// Transcript parsers: turn a captured CLI events file into tool invocations
 /// and a [`super::TranscriptSummary`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum TranscriptParser {
     /// `claude -p --output-format stream-json` events.
@@ -56,7 +56,7 @@ impl TranscriptParser {
 }
 
 /// Write-guard engines: install a PreToolUse-style hook under the staged env.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum GuardEngine {
     /// Hook merged into `.claude/settings.local.json`.
@@ -107,7 +107,7 @@ impl GuardEngine {
 
 /// Staged-slug generators, for harnesses whose naming rules need
 /// sanitization/truncation beyond a format string.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum SlugCapability {
     /// OpenCode's lowercase-alphanumeric-single-hyphen names, length-capped.
@@ -132,7 +132,7 @@ impl SlugCapability {
 }
 
 /// Shadow preflights: detect installed skills that shadow a staged slug.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum ShadowPreflight {
     /// Claude Code plugin/skill scan rooted at the user config dir.
diff --git a/src/adapters/descriptor.rs b/src/adapters/descriptor.rs
index f92ba9a..531ac30 100644
--- a/src/adapters/descriptor.rs
+++ b/src/adapters/descriptor.rs
@@ -13,7 +13,7 @@
 //! same checks.
 
 use regex::Regex;
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
 
 use crate::validation::{SchemaName, ValidationError, validate_against_schema};
 
@@ -44,30 +44,36 @@ pub const EMBEDDED_DESCRIPTORS: [(&str, &str); 3] = [
 /// Field docs live in `schema/harness-descriptor.schema.json` (the schema gate
 /// and this struct are kept honest against each other by
 /// [`validate_against_schema`]'s deserialize step).
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct HarnessDescriptor {
     pub label: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub skills_dir: Option<String>,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub config_dirs: Vec<String>,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "RunSection::is_default")]
     pub run: RunSection,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "ToolsSection::is_empty")]
     pub tools: ToolsSection,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "StagingSection::is_unconfigured")]
     pub staging: StagingSection,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub skills_block: Option<SkillsBlockSection>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub transcript: Option<TranscriptSection>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub model: Option<ModelSection>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub guard: Option<GuardSection>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub shadow: Option<ShadowSection>,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "DispatchSection::is_empty")]
     pub dispatch: DispatchSection,
 }
 
 /// Run-option capabilities. The `Default` mirrors the baseline every harness
 /// gets without opting in: no guard, bootstrap/stage-name allowed unstaged.
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
 pub struct RunSection {
     #[serde(default)]
     pub supports_guard: bool,
@@ -77,6 +83,14 @@ pub struct RunSection {
     pub supports_stage_name_with_no_stage: bool,
 }
 
+impl RunSection {
+    /// True when every capability sits at its baseline default — the signal
+    /// `harness show` uses to omit the section from authorable output.
+    pub fn is_default(&self) -> bool {
+        *self == RunSection::default()
+    }
+}
+
 impl Default for RunSection {
     fn default() -> Self {
         RunSection {
@@ -87,81 +101,149 @@ impl Default for RunSection {
     }
 }
 
-#[derive(Debug, Clone, Default, Deserialize)]
+#[derive(Debug, Clone, Default, Deserialize, Serialize)]
 pub struct ToolsSection {
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub write: Vec<String>,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub patch: Vec<String>,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub shell: Vec<String>,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub read: Vec<String>,
 }
 
-#[derive(Debug, Clone, Default, Deserialize)]
+impl ToolsSection {
+    /// True when no role declares any tool names.
+    pub fn is_empty(&self) -> bool {
+        self.write.is_empty()
+            && self.patch.is_empty()
+            && self.shell.is_empty()
+            && self.read.is_empty()
+    }
+}
+
+#[derive(Debug, Clone, Default, Deserialize, Serialize)]
 pub struct StagingSection {
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub slug_template: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub slug_capability: Option<SlugCapability>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub stage_name_pattern: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub stage_name_max_len: Option<usize>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub stage_name_invalid_message: Option<String>,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "is_false")]
     pub rewrites_frontmatter_name: bool,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "is_false")]
     pub advertises_staged_slug_name: bool,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub surface_phrase: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub unresolved_phrase: Option<String>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+impl StagingSection {
+    /// True when any field departs from the defaults — the signal that the
+    /// descriptor actually configures native staging.
+    pub fn is_configured(&self) -> bool {
+        !self.is_unconfigured()
+    }
+
+    fn is_unconfigured(&self) -> bool {
+        self.slug_template.is_none()
+            && self.slug_capability.is_none()
+            && self.stage_name_pattern.is_none()
+            && self.stage_name_max_len.is_none()
+            && self.stage_name_invalid_message.is_none()
+            && !self.rewrites_frontmatter_name
+            && !self.advertises_staged_slug_name
+            && self.surface_phrase.is_none()
+            && self.unresolved_phrase.is_none()
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct SkillsBlockSection {
     pub header: String,
     pub item: String,
-    #[serde(default)]
+    #[serde(default, skip_serializing_if = "String::is_empty")]
     pub footer: String,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct TranscriptSection {
     pub events_filename: String,
     pub parser: TranscriptParser,
-    #[serde(default = "default_true")]
+    #[serde(default = "default_true", skip_serializing_if = "is_true")]
     pub surfaces_skill_invocation: bool,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct ModelSection {
     pub flag: String,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct GuardSection {
     pub engine: GuardEngine,
     pub armed_message: String,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct ShadowSection {
     pub preflight: ShadowPreflight,
 }
 
-#[derive(Debug, Clone, Default, Deserialize)]
+#[derive(Debug, Clone, Default, Deserialize, Serialize)]
 pub struct DispatchSection {
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub capture_prefix: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub guard_args: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub model_note: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub next_steps_template: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub exec_template: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub parallel_command_template: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub judge_command_template: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub manifest_template: Option<String>,
 }
 
+impl DispatchSection {
+    /// True when no dispatch field is set.
+    pub fn is_empty(&self) -> bool {
+        self.capture_prefix.is_none()
+            && self.guard_args.is_none()
+            && self.model_note.is_none()
+            && self.next_steps_template.is_none()
+            && self.exec_template.is_none()
+            && self.parallel_command_template.is_none()
+            && self.judge_command_template.is_none()
+            && self.manifest_template.is_none()
+    }
+}
+
 fn default_true() -> bool {
     true
 }
 
+/// `skip_serializing_if` helpers for boolean fields at their defaults.
+fn is_false(value: &bool) -> bool {
+    !*value
+}
+
+fn is_true(value: &bool) -> bool {
+    *value
+}
+
 /// A descriptor that failed to load. Every variant carries the descriptor's
 /// source path so the message is actionable on its own.
 #[derive(Debug, thiserror::Error)]
diff --git a/src/adapters/descriptor/validation.rs b/src/adapters/descriptor/validation.rs
index 4d8cc2f..09fd4cf 100644
--- a/src/adapters/descriptor/validation.rs
+++ b/src/adapters/descriptor/validation.rs
@@ -43,7 +43,7 @@ pub(super) fn validate_descriptor(
     // staging copies skills into it, and the guard keeps its marker/manifest
     // there. Without a skills_dir neither has anywhere to operate.
     if d.skills_dir.is_none() {
-        if staging_is_configured(&d.staging) {
+        if d.staging.is_configured() {
             return fail(
                 "[staging] is configured but skills_dir is not declared; native staging \
                  copies skills into skills_dir — declare it, or drop [staging] and let \
@@ -285,21 +285,6 @@ pub(super) fn validate_descriptor(
     Ok(())
 }
 
-/// True when any `[staging]` field departs from the defaults — the signal
-/// that the descriptor actually configures native staging rather than just
-/// inheriting the baseline.
-fn staging_is_configured(staging: &super::StagingSection) -> bool {
-    staging.slug_template.is_some()
-        || staging.slug_capability.is_some()
-        || staging.stage_name_pattern.is_some()
-        || staging.stage_name_max_len.is_some()
-        || staging.stage_name_invalid_message.is_some()
-        || staging.rewrites_frontmatter_name
-        || staging.advertises_staged_slug_name
-        || staging.surface_phrase.is_some()
-        || staging.unresolved_phrase.is_some()
-}
-
 #[cfg(test)]
 mod tests {
     use super::super::load_descriptor;
diff --git a/src/adapters/descriptor_adapter.rs b/src/adapters/descriptor_adapter.rs
index 5eed8be..0b31561 100644
--- a/src/adapters/descriptor_adapter.rs
+++ b/src/adapters/descriptor_adapter.rs
@@ -49,6 +49,12 @@ impl DescriptorAdapter {
         }
     }
 
+    /// The resolved descriptor behind this adapter — the `harness show`/`list`
+    /// data source.
+    pub(crate) fn descriptor(&self) -> &HarnessDescriptor {
+        &self.descriptor
+    }
+
     /// The single-dispatch command: the exec template with `{model_arg}` /
     /// `{guard_args}` filled for this run. Empty when no template is wired.
     fn exec_command(&self, guard: bool, agent_model: Option<&str>) -> String {
diff --git a/src/adapters/registry.rs b/src/adapters/registry.rs
index 1158f77..2249765 100644
--- a/src/adapters/registry.rs
+++ b/src/adapters/registry.rs
@@ -25,11 +25,13 @@ use super::harness::{HarnessAdapter, ToolVocabulary};
 
 /// One registry entry: a harness identity (the descriptor's `label`), the
 /// descriptor sources that contributed to it (for `harness list`/`show`
-/// provenance), and its descriptor-backed adapter.
+/// provenance), the merged descriptor value (the base `harness lint` merges
+/// candidate overlays onto), and its descriptor-backed adapter.
 #[derive(Debug)]
 struct RegistryEntry {
     label: &'static str,
     sources: Vec<(Layer, String)>,
+    value: serde_json::Value,
     adapter: DescriptorAdapter,
 }
 
@@ -230,6 +232,7 @@ fn build_registry(sources: Vec<DescriptorSource>) -> Result<BuiltRegistry, Regis
             // handle.
             label: Box::leak(p.label.into_boxed_str()),
             sources: p.sources,
+            value: p.value,
             adapter: DescriptorAdapter::from_descriptor(p.descriptor),
         })
         .collect();
@@ -291,11 +294,8 @@ impl Default for Harness {
     fn default() -> Self {
         // A `--harness-file` descriptor becomes the session default, so the
         // one-off harness doesn't have to be repeated via `--harness`.
-        let name = SESSION_DEFAULT_HARNESS
-            .get()
-            .copied()
-            .unwrap_or(DEFAULT_HARNESS_NAME);
-        Harness::resolve(name).expect("the session default resolves against the registry")
+        Harness::resolve(default_harness_name())
+            .expect("the session default resolves against the registry")
     }
 }
 
@@ -317,6 +317,36 @@ pub fn adapter_for(harness: Harness) -> &'static dyn HarnessAdapter {
         .adapter
 }
 
+/// One registered harness as `harness list`/`show`/`lint` see it: identity,
+/// contributing sources in layer order, the merged descriptor value, and the
+/// resolved descriptor.
+pub struct HarnessInfo {
+    pub label: &'static str,
+    pub sources: &'static [(Layer, String)],
+    pub value: &'static serde_json::Value,
+    pub descriptor: &'static HarnessDescriptor,
+}
+
+/// Every registered harness in registry order, with provenance and the
+/// resolved descriptor — the data source for the `harness` subcommands.
+pub fn harness_info() -> impl Iterator<Item = HarnessInfo> {
+    registry().iter().map(|e| HarnessInfo {
+        label: e.label,
+        sources: &e.sources,
+        value: &e.value,
+        descriptor: e.adapter.descriptor(),
+    })
+}
+
+/// The effective default harness name: the `--harness-file` descriptor's
+/// label when one is loaded, else [`DEFAULT_HARNESS_NAME`].
+pub fn default_harness_name() -> &'static str {
+    SESSION_DEFAULT_HARNESS
+        .get()
+        .copied()
+        .unwrap_or(DEFAULT_HARNESS_NAME)
+}
+
 /// The union of every harness's project-local config dir names (sorted,
 /// deduplicated): the dirs harness-agnostic code must treat as protected —
 /// staging's sibling-asset filter, the guard's Bash tamper rule, and
diff --git a/src/cli/args.rs b/src/cli/args.rs
index 43417cf..4810eb4 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -112,6 +112,54 @@ pub struct CommonArgs {
     pub overwrite: bool,
 }
 
+/// `harness` groups the descriptor-inspection subcommands.
+#[derive(Debug, Args)]
+pub struct HarnessArgs {
+    #[command(subcommand)]
+    pub command: HarnessCommands,
+}
+
+#[derive(Debug, Subcommand)]
+pub(crate) enum HarnessCommands {
+    /// List every registered harness: name, source layer(s), enhancements.
+    ///
+    /// One line per harness with the layers that contributed to it (built-in,
+    /// user, project, file — a merged descriptor shows all of them, e.g.
+    /// `built-in + project`) and the enhancements the resolved descriptor
+    /// declares (staging, skills-block, transcript, model-flag, guard,
+    /// shadow-preflight, dispatch-recipes; `baseline` when none). The session's
+    /// default harness — `claude-code`, or the `--harness-file` descriptor when
+    /// one is loaded — is marked `(default)`.
+    List,
+    /// Print one harness's resolved descriptor (after layer merging) as TOML.
+    ///
+    /// The output is authorable: the provenance header lists every contributing
+    /// file as `#` comments, and the body is valid descriptor TOML you can copy
+    /// into a layer file (`.eval-magic/harnesses/<name>.toml`) and edit. Fields
+    /// at their baseline defaults are omitted.
+    Show {
+        /// Registered harness name (see `harness list`).
+        name: String,
+    },
+    /// Validate a descriptor file, or every layer of a registered harness.
+    ///
+    /// A file target runs the full load pipeline with one ✓/✗ line per check:
+    /// TOML syntax + schema (unknown fields, bad capability names), the
+    /// user-layer restrictions (`[guard]` and `run.supports_guard = true` stay
+    /// built-in-only; unguarded runs fall back to the detect-stray-writes
+    /// audit), and the cross-field invariants — merged onto the registered
+    /// harness with the same `label` when one exists, so a partial override is
+    /// checked against its real merge target. A name target re-lints every
+    /// discovered layer file strictly, surfacing descriptors that registry
+    /// initialization skipped with a warning. Exits non-zero when any check
+    /// fails. (A future `--probe` flag is reserved for a live dispatch probe
+    /// through the exec template.)
+    Lint {
+        /// Descriptor file path, or a registered harness name.
+        target: String,
+    },
+}
+
 /// `validate` only needs to know where to look.
 #[derive(Debug, Args)]
 pub struct ValidateArgs {
@@ -445,6 +493,18 @@ pub(crate) enum Commands {
     PromoteBaseline(PromoteBaselineArgs),
     /// Validate `evals.json` files against the bundled schemas.
     Validate(ValidateArgs),
+    /// Inspect and validate harness descriptors (built-in and user-supplied).
+    ///
+    /// Harnesses are described by layered TOML descriptor files: embedded
+    /// built-ins → user-global (`$EVAL_MAGIC_CONFIG_DIR`,
+    /// `$XDG_CONFIG_HOME/eval-magic`, or `~/.config/eval-magic`, each under
+    /// `harnesses/*.toml`) → project-local (`.eval-magic/harnesses/*.toml`) →
+    /// a one-off `--harness-file <path>`. A later file whose `label` matches an
+    /// earlier descriptor overrides individual fields (field-level merge, not
+    /// whole-file shadowing); a new `label` defines a new harness usable with
+    /// `--harness`. `list` surveys the registry, `show` prints one resolved
+    /// descriptor, and `lint` validates a descriptor file or registered name.
+    Harness(HarnessArgs),
     /// Internal PreToolUse hook entry point. Invoked by the installed write-guard
     /// hook as `eval-magic guard <marker>`, not by users; hidden from help.
     #[command(hide = true)]
diff --git a/src/cli/commands/harness.rs b/src/cli/commands/harness.rs
new file mode 100644
index 0000000..6d2f0e8
--- /dev/null
+++ b/src/cli/commands/harness.rs
@@ -0,0 +1,284 @@
+//! The `harness` subcommands: inspect and validate the layered harness
+//! descriptor registry (`list`, `show`, `lint`).
+
+use std::fs;
+use std::path::Path;
+
+use anyhow::{Context, bail};
+
+use crate::adapters::descriptor::layers::{
+    Layer, check_user_layer_restrictions, default_config_root, discover_sources,
+};
+use crate::adapters::descriptor::{
+    HarnessDescriptor, finalize_descriptor, merge_descriptor_value, parse_descriptor_value,
+};
+use crate::adapters::registry::{HarnessInfo, default_harness_name, harness_info};
+use crate::core::Harness;
+
+use crate::cli::args::{HarnessArgs, HarnessCommands};
+
+pub(crate) fn run_harness(args: HarnessArgs) -> anyhow::Result<()> {
+    match args.command {
+        HarnessCommands::List => run_list(),
+        HarnessCommands::Show { name } => run_show(&name),
+        HarnessCommands::Lint { target } => run_lint(&target),
+    }
+}
+
+/// One line per registered harness: label, contributing layers, declared
+/// enhancements.
+fn run_list() -> anyhow::Result<()> {
+    let default_name = default_harness_name();
+    let rows: Vec<(String, String, String)> = harness_info()
+        .map(|info| {
+            let name = if info.label == default_name {
+                format!("{} (default)", info.label)
+            } else {
+                info.label.to_string()
+            };
+            (
+                name,
+                layer_chain(&info),
+                declared_enhancements(info.descriptor),
+            )
+        })
+        .collect();
+    let name_width = rows.iter().map(|(n, _, _)| n.len()).max().unwrap_or(0);
+    let layer_width = rows.iter().map(|(_, l, _)| l.len()).max().unwrap_or(0);
+    for (name, layers, enhancements) in rows {
+        println!("{name:<name_width$}  {layers:<layer_width$}  {enhancements}");
+    }
+    Ok(())
+}
+
+/// Print one harness's resolved (layer-merged) descriptor as authorable TOML,
+/// headed by its provenance chain.
+fn run_show(name: &str) -> anyhow::Result<()> {
+    let Some(info) = harness_info().find(|info| info.label == name) else {
+        return Err(Harness::resolve(name)
+            .expect_err("name is absent from the registry")
+            .into());
+    };
+    println!("# {name} — resolved descriptor (after layer merging)");
+    println!("# sources:");
+    for (layer, path) in info.sources {
+        println!("#   {path} ({})", layer.display_name());
+    }
+    println!();
+    print!("{}", toml::to_string(info.descriptor)?);
+    Ok(())
+}
+
+/// Lint a descriptor file, or every discovered layer of a registered name.
+fn run_lint(target: &str) -> anyhow::Result<()> {
+    let looks_like_path = target.contains(std::path::MAIN_SEPARATOR)
+        || target.ends_with(".toml")
+        || Path::new(target).is_file();
+    if looks_like_path {
+        lint_file(Path::new(target))
+    } else {
+        lint_name(target)
+    }
+}
+
+/// Run one descriptor file through the full load pipeline, reporting each
+/// check as a ✓/✗ line (the `validate` idiom).
+fn lint_file(path: &Path) -> anyhow::Result<()> {
+    let display = path.display();
+    let toml_src = fs::read_to_string(path).with_context(|| format!("cannot read {display}"))?;
+    let mut failed = 0usize;
+
+    let value = match parse_descriptor_value(&toml_src, &display.to_string()) {
+        Ok(value) => {
+            println!("✓ TOML syntax + schema");
+            Some(value)
+        }
+        Err(e) => {
+            eprintln!("✗ {e}");
+            failed += 1;
+            None
+        }
+    };
+
+    if let Some(value) = &value {
+        match check_user_layer_restrictions(value, &display.to_string()) {
+            Ok(()) => println!("✓ user-layer restrictions ([guard] stays built-in-only)"),
+            Err(e) => {
+                eprintln!("✗ {e}");
+                failed += 1;
+            }
+        }
+
+        // Cross-field invariants — merged onto the registered harness with the
+        // same label when one exists, so a partial override file is checked
+        // against its real merge target. Merging is idempotent, so linting a
+        // file the registry already discovered reports identically.
+        let label = value.get("label").and_then(serde_json::Value::as_str);
+        let target = label.and_then(|l| harness_info().find(|info| info.label == l));
+        let (merged, provenance) = match &target {
+            Some(info) => {
+                let mut merged = info.value.clone();
+                merge_descriptor_value(&mut merged, value.clone());
+                (
+                    merged,
+                    format!("{} + {display} (lint)", layer_provenance(info)),
+                )
+            }
+            None => (value.clone(), display.to_string()),
+        };
+        match finalize_descriptor(&merged, &provenance) {
+            Ok(_) => match &target {
+                Some(info) => println!("✓ cross-field invariants (merged onto {})", info.label),
+                None => println!("✓ cross-field invariants"),
+            },
+            Err(e) => {
+                eprintln!("✗ {e}");
+                failed += 1;
+            }
+        }
+    }
+
+    if failed > 0 {
+        bail!("descriptor lint failed for {display}: {failed} check(s) failed");
+    }
+    println!("Linted {display}: all checks passed.");
+    Ok(())
+}
+
+/// Strictly re-lint every discovered layer file, reporting the ones registry
+/// initialization skipped with a warning, and re-validate the named harness's
+/// merged chain.
+fn lint_name(name: &str) -> anyhow::Result<()> {
+    let project_root = std::env::current_dir().unwrap_or_default();
+    let (sources, io_warnings) =
+        discover_sources(default_config_root().as_deref(), &project_root, None)
+            .map_err(anyhow::Error::from)?;
+    let mut failed = io_warnings.len();
+    for warning in io_warnings {
+        eprintln!("✗ {warning}");
+    }
+
+    let mut chain: Option<(serde_json::Value, Vec<String>)> = None;
+    for source in sources {
+        let value = match parse_descriptor_value(&source.toml_src, &source.path) {
+            Ok(value) => value,
+            Err(e) => {
+                // The label is unknowable, so every broken discovered file is
+                // reported — these are exactly the files init skipped.
+                if source.layer != Layer::Embedded {
+                    eprintln!("✗ {e}");
+                    failed += 1;
+                }
+                continue;
+            }
+        };
+        if source.layer != Layer::Embedded
+            && let Err(e) = check_user_layer_restrictions(&value, &source.path)
+        {
+            eprintln!("✗ {e}");
+            failed += 1;
+            continue;
+        }
+        if value.get("label").and_then(serde_json::Value::as_str) != Some(name) {
+            continue;
+        }
+        let step = format!("{} ({})", source.path, source.layer.display_name());
+        println!("✓ {step}: schema + user-layer checks");
+        match &mut chain {
+            None => chain = Some((value, vec![step])),
+            Some((base, steps)) => {
+                let mut merged = base.clone();
+                merge_descriptor_value(&mut merged, value);
+                steps.push(step);
+                let provenance = steps.join(" + ");
+                match finalize_descriptor(&merged, &provenance) {
+                    Ok(_) => *base = merged,
+                    Err(e) => {
+                        eprintln!("✗ {e}");
+                        failed += 1;
+                        steps.pop();
+                    }
+                }
+            }
+        }
+    }
+
+    match &chain {
+        Some((value, steps)) => {
+            let provenance = steps.join(" + ");
+            match finalize_descriptor(value, &provenance) {
+                Ok(_) => println!("✓ resolved descriptor: {provenance}"),
+                Err(e) => {
+                    eprintln!("✗ {e}");
+                    failed += 1;
+                }
+            }
+        }
+        // Discovery missed it, but a `--harness-file` may still have
+        // registered it for this invocation.
+        None => match harness_info().find(|info| info.label == name) {
+            Some(info) => println!("✓ registered: {}", layer_provenance(&info)),
+            None if failed == 0 => {
+                return Err(Harness::resolve(name)
+                    .expect_err("name is absent from every layer")
+                    .into());
+            }
+            None => {}
+        },
+    }
+
+    if failed > 0 {
+        bail!("descriptor lint failed for {name}: {failed} check(s) failed");
+    }
+    println!("Linted {name}: all checks passed.");
+    Ok(())
+}
+
+/// `built-in + project` — the layer chain for `harness list`.
+fn layer_chain(info: &HarnessInfo) -> String {
+    info.sources
+        .iter()
+        .map(|(layer, _)| layer.display_name())
+        .collect::<Vec<_>>()
+        .join(" + ")
+}
+
+/// `harnesses/claude-code.toml (built-in) + …` — the full provenance chain.
+fn layer_provenance(info: &HarnessInfo) -> String {
+    info.sources
+        .iter()
+        .map(|(layer, path)| format!("{path} ({})", layer.display_name()))
+        .collect::<Vec<_>>()
+        .join(" + ")
+}
+
+/// The enhancements a resolved descriptor declares, for `harness list`.
+fn declared_enhancements(descriptor: &HarnessDescriptor) -> String {
+    let mut list: Vec<&str> = Vec::new();
+    if descriptor.skills_dir.is_some() {
+        list.push("staging");
+    }
+    if descriptor.skills_block.is_some() {
+        list.push("skills-block");
+    }
+    if descriptor.transcript.is_some() {
+        list.push("transcript");
+    }
+    if descriptor.model.is_some() {
+        list.push("model-flag");
+    }
+    if descriptor.guard.is_some() {
+        list.push("guard");
+    }
+    if descriptor.shadow.is_some() {
+        list.push("shadow-preflight");
+    }
+    if !descriptor.dispatch.is_empty() {
+        list.push("dispatch-recipes");
+    }
+    if list.is_empty() {
+        "baseline".to_string()
+    } else {
+        list.join(", ")
+    }
+}
diff --git a/src/cli/commands/mod.rs b/src/cli/commands/mod.rs
index 1f04e62..c9b41af 100644
--- a/src/cli/commands/mod.rs
+++ b/src/cli/commands/mod.rs
@@ -5,6 +5,7 @@
 //! [`super`] (`crate::cli`).
 
 mod guard;
+mod harness;
 mod init;
 mod pipeline;
 mod run;
@@ -12,6 +13,7 @@ mod validate;
 mod workspace;
 
 pub(crate) use guard::{run_guard, run_guard_codex, run_teardown_guard};
+pub(crate) use harness::run_harness;
 pub(crate) use init::run_init;
 pub(crate) use pipeline::{
     run_aggregate, run_detect_stray_writes, run_fill_transcripts, run_finalize, run_grade,
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 6bc07f3..0974b12 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -71,6 +71,7 @@ fn dispatch(command: Option<Commands>) -> anyhow::Result<()> {
         Commands::DetectStrayWrites(args) => run_detect_stray_writes(args),
         Commands::Grade(args) => run_grade(args),
         Commands::Aggregate(args) => run_aggregate(args),
+        Commands::Harness(args) => run_harness(args),
         Commands::Snapshot(args) => run_snapshot(args),
         Commands::Teardown(args) => run_teardown(args),
         Commands::PromoteBaseline(args) => run_promote_baseline(args),
diff --git a/tests/cli/harness.rs b/tests/cli/harness.rs
index f29c861..1626371 100644
--- a/tests/cli/harness.rs
+++ b/tests/cli/harness.rs
@@ -121,6 +121,200 @@ fn broken_harness_file_is_fatal() {
         .stderr(contains("broken.toml").and(contains("invalid TOML")));
 }
 
+#[test]
+fn harness_list_names_layers_and_enhancements() {
+    let tmp = TempDir::new().unwrap();
+    write_project_descriptor(tmp.path(), "cool.toml", "label = \"cool-custom-harness\"\n");
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "list"])
+        .assert()
+        .success()
+        .stdout(
+            contains("claude-code")
+                .and(contains("(default)"))
+                .and(contains("built-in"))
+                .and(contains("opencode"))
+                .and(contains("cool-custom-harness"))
+                .and(contains("project"))
+                .and(contains("baseline"))
+                .and(contains("transcript")),
+        );
+}
+
+#[test]
+fn harness_list_marks_merged_builtins() {
+    let tmp = TempDir::new().unwrap();
+    write_project_descriptor(
+        tmp.path(),
+        "claude-code.toml",
+        "label = \"claude-code\"\n\n[model]\nflag = \"--model-x\"\n",
+    );
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "list"])
+        .assert()
+        .success()
+        .stdout(contains("built-in + project"));
+}
+
+#[test]
+fn harness_show_prints_the_merged_descriptor_as_toml() {
+    let tmp = TempDir::new().unwrap();
+    write_project_descriptor(
+        tmp.path(),
+        "claude-code.toml",
+        "label = \"claude-code\"\n\n[model]\nflag = \"--model-x\"\n",
+    );
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "show", "claude-code"])
+        .assert()
+        .success()
+        .stdout(
+            contains("label = \"claude-code\"")
+                .and(contains("--model-x"))
+                .and(contains("harnesses/claude-code.toml (built-in)"))
+                .and(contains("claude-code.toml (project)"))
+                // The rest of the embedded descriptor survives the merge.
+                .and(contains("skills_dir = \".claude/skills\"")),
+        );
+}
+
+#[test]
+fn harness_show_unknown_name_lists_known_harnesses() {
+    let tmp = TempDir::new().unwrap();
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "show", "nonexistent"])
+        .assert()
+        .failure()
+        .stderr(contains("unknown harness 'nonexistent'").and(contains("claude-code")));
+}
+
+#[test]
+fn harness_lint_passes_a_valid_file() {
+    let tmp = TempDir::new().unwrap();
+    let file = tmp.path().join("cool.toml");
+    fs::write(&file, "label = \"cool-custom-harness\"\n").unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "lint"])
+        .arg(&file)
+        .assert()
+        .success()
+        .stdout(contains("✓"));
+}
+
+#[test]
+fn harness_lint_reports_schema_violations() {
+    let tmp = TempDir::new().unwrap();
+    let file = tmp.path().join("bad.toml");
+    fs::write(&file, "label = \"bad\"\nmystery = 1\n").unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "lint"])
+        .arg(&file)
+        .assert()
+        .failure()
+        .stderr(contains("✗").and(contains("mystery")));
+}
+
+#[test]
+fn harness_lint_rejects_a_user_guard_block() {
+    let tmp = TempDir::new().unwrap();
+    let file = tmp.path().join("armed.toml");
+    fs::write(
+        &file,
+        "label = \"armed\"\n\n[guard]\nengine = \"claude-hooks\"\narmed_message = \"x\"\n",
+    )
+    .unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "lint"])
+        .arg(&file)
+        .assert()
+        .failure()
+        .stderr(contains("may not declare [guard]").and(contains("detect-stray-writes")));
+}
+
+#[test]
+fn harness_lint_reports_invariant_breaks() {
+    let tmp = TempDir::new().unwrap();
+    let file = tmp.path().join("slug.toml");
+    fs::write(
+        &file,
+        "label = \"demo\"\nskills_dir = \".demo/skills\"\nconfig_dirs = [\".demo\"]\n\n\
+         [staging]\nslug_template = \"{prefix}{iteration}-{condition}\"\n",
+    )
+    .unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "lint"])
+        .arg(&file)
+        .assert()
+        .failure()
+        .stderr(contains("staging.slug_template").and(contains("{skill_name}")));
+}
+
+#[test]
+fn harness_lint_checks_a_partial_override_against_its_merge_target() {
+    let tmp = TempDir::new().unwrap();
+    // Standalone this partial is fine; merged onto claude-code it orphans
+    // skills_dir's parent — lint must catch the post-merge break.
+    let file = tmp.path().join("claude-code.toml");
+    fs::write(
+        &file,
+        "label = \"claude-code\"\nconfig_dirs = [\".other\"]\n",
+    )
+    .unwrap();
+
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "lint"])
+        .arg(&file)
+        .assert()
+        .failure()
+        .stderr(contains("parent of skills_dir"));
+}
+
+#[test]
+fn harness_lint_accepts_a_registered_harness_name() {
+    let tmp = TempDir::new().unwrap();
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "lint", "claude-code"])
+        .assert()
+        .success()
+        .stdout(contains("✓"));
+}
+
+#[test]
+fn harness_lint_of_a_name_reports_the_skipped_project_file() {
+    let tmp = TempDir::new().unwrap();
+    write_project_descriptor(
+        tmp.path(),
+        "broken.toml",
+        "label = \"broken\"\nmystery = 1\n",
+    );
+
+    // Init skips the broken file with a warning; linting the name surfaces
+    // the full per-file report and fails.
+    skill_eval()
+        .current_dir(tmp.path())
+        .args(["harness", "lint", "broken"])
+        .assert()
+        .failure()
+        .stderr(contains("✗").and(contains("mystery")));
+}
+
 #[test]
 fn missing_harness_file_is_fatal() {
     let tmp = TempDir::new().unwrap();

From 0eda51eb8e67ce3575b838f4776807cad8a81971 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:35:02 -0400
Subject: [PATCH 06/10] feat(run): preflight warns about undeclared
 enhancements, never rejects

The harness preflight now follows the #126 model: each enhancement the
selected harness doesn't declare produces a warning naming the fallback
that carries the run, and the run proceeds degraded. --guard on a
guard-less harness (e.g. opencode) is forced off with a pointer at the
detect-stray-writes audit instead of erroring; a harness without a
skills_dir falls back to --no-stage with each SKILL.md inlined; a
missing transcript parser warns that transcript_check grades as
unverifiable with llm_judge carrying the grading; requested models
without a descriptor model flag are recorded as provenance only. Only
genuinely contradictory flag combinations (--bootstrap/--stage-name
where the descriptor declares them incompatible with --no-stage) remain
hard errors. ingest prints a matching note on transcript-less
harnesses, which previously skipped transcript work silently.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/cli/commands/pipeline.rs       |  10 ++
 src/cli/run/orchestrate/mod.rs     |   9 ++
 src/cli/run/orchestrate/resolve.rs |   5 +-
 src/cli/run/util.rs                | 156 +++++++++++++++++++++++++----
 tests/run/opencode.rs              |  32 ++++--
 5 files changed, 184 insertions(+), 28 deletions(-)

diff --git a/src/cli/commands/pipeline.rs b/src/cli/commands/pipeline.rs
index a8bbc8c..d3587b7 100644
--- a/src/cli/commands/pipeline.rs
+++ b/src/cli/commands/pipeline.rs
@@ -69,6 +69,16 @@ pub(crate) fn run_ingest(args: CommonArgs) -> anyhow::Result<()> {
     let ctx = run_context_from(&args)?;
     let iteration = resolve_iteration(&ctx, args.iteration)?;
 
+    let adapter = crate::adapters::adapter_for(ctx.harness);
+    if adapter.cli_events_filename().is_none() {
+        eprintln!(
+            "ℹ --harness {}: no transcript parser — records come from outputs/final-message.md \
+             only; steps/tokens/duration go unrecorded and transcript_check assertions grade \
+             as unverifiable (llm_judge carries the grading).",
+            adapter.label()
+        );
+    }
+
     let steps = run::steps::build_ingest_commands(&run::steps::StepParams {
         skill_dir: args.skill_dir.as_deref(),
         skill: args.skill.as_deref(),
diff --git a/src/cli/run/orchestrate/mod.rs b/src/cli/run/orchestrate/mod.rs
index 53c15f1..52d99df 100644
--- a/src/cli/run/orchestrate/mod.rs
+++ b/src/cli/run/orchestrate/mod.rs
@@ -85,6 +85,15 @@ struct Staged {
 
 /// Build the iteration workspace and dispatch plan for a run.
 pub fn command_run(ctx: &RunContext, opts: &RunOptions) -> Result<(), RunError> {
+    // The harness preflight warns about undeclared enhancements (naming each
+    // fallback) and adjusts the options — it only rejects genuinely
+    // contradictory flag combinations.
+    let preflight = super::util::harness_run_preflight(opts, ctx)?;
+    for warning in &preflight.warnings {
+        eprintln!("⚠ {warning}");
+    }
+    let opts = &preflight.opts;
+
     let resolved = resolve::resolve_request(ctx, opts)?;
 
     // Redirect staging into the isolated env dir. `resolve_request` has now
diff --git a/src/cli/run/orchestrate/resolve.rs b/src/cli/run/orchestrate/resolve.rs
index 48fd403..abee50d 100644
--- a/src/cli/run/orchestrate/resolve.rs
+++ b/src/cli/run/orchestrate/resolve.rs
@@ -13,9 +13,7 @@ use super::super::RunError;
 use super::super::dispatch::select_evals;
 use super::super::fixtures::fixture_pairs;
 use super::super::grouping::{GroupInput, compute_groups};
-use super::super::util::{
-    condition_names_for, make_run_nonce, next_iteration, validate_harness_run_options,
-};
+use super::super::util::{condition_names_for, make_run_nonce, next_iteration};
 use super::{Resolved, RunOptions};
 
 pub(super) fn resolve_request(ctx: &RunContext, opts: &RunOptions) -> Result<Resolved, RunError> {
@@ -30,7 +28,6 @@ pub(super) fn resolve_request(ctx: &RunContext, opts: &RunOptions) -> Result<Res
     if opts.runs == 0 {
         return Err(RunError::msg("--runs must be at least 1"));
     }
-    validate_harness_run_options(opts, ctx)?;
 
     let skill_md_path = ctx.skill_subdir.join("SKILL.md");
     if !skill_md_path.exists() {
diff --git a/src/cli/run/util.rs b/src/cli/run/util.rs
index c42c7a1..7b2d60f 100644
--- a/src/cli/run/util.rs
+++ b/src/cli/run/util.rs
@@ -63,16 +63,33 @@ pub(crate) fn resolve_plan_mode_profile() -> &'static str {
     include_str!("../../../profiles/shared/plan-mode.md")
 }
 
-/// Reject run options not supported by the selected harness's current mechanism.
-pub(crate) fn validate_harness_run_options(
-    opts: &RunOptions,
+/// The harness preflight verdict: possibly-adjusted run options plus the
+/// warnings to print, each naming the fallback that carries the run.
+pub(crate) struct HarnessPreflight<'a> {
+    pub opts: RunOptions<'a>,
+    pub warnings: Vec<String>,
+}
+
+/// Check the run options against the selected harness's declared enhancements
+/// — the #126 model: a missing enhancement *warns* naming its fallback and the
+/// run continues degraded; only genuinely contradictory flag combinations
+/// (options the harness declares incompatible with `--no-stage`) stay errors.
+///
+/// Adjustments: `--guard` on a guard-less harness is forced off (the
+/// detect-stray-writes audit is the fallback), and a harness without a
+/// `skills_dir` forces `--no-stage` (each SKILL.md is inlined into its
+/// dispatch prompt).
+pub(crate) fn harness_run_preflight<'a>(
+    opts: &RunOptions<'a>,
     ctx: &RunContext,
-) -> Result<(), RunError> {
-    let capabilities = adapter_for(ctx.harness).run_capabilities();
+) -> Result<HarnessPreflight<'a>, RunError> {
+    let adapter = adapter_for(ctx.harness);
+    let capabilities = adapter.run_capabilities();
+    let label = harness_label(ctx.harness);
+
+    // Contradictory-flag declarations stay hard errors: the harness's staging
+    // mechanism conflicts with these options, so no fallback can honor them.
     let mut unsupported: Vec<&str> = Vec::new();
-    if opts.guard && !capabilities.supports_guard {
-        unsupported.push("--guard");
-    }
     if ctx.bootstrap_path.is_some()
         && opts.no_stage
         && !capabilities.supports_bootstrap_with_no_stage
@@ -83,15 +100,49 @@ pub(crate) fn validate_harness_run_options(
     {
         unsupported.push("--stage-name with --no-stage");
     }
-    if unsupported.is_empty() {
-        Ok(())
-    } else {
-        Err(RunError::msg(format!(
+    if !unsupported.is_empty() {
+        return Err(RunError::msg(format!(
             "Unsupported for --harness {}: {}.",
-            harness_label(ctx.harness),
+            label,
             unsupported.join(", ")
-        )))
+        )));
+    }
+
+    let mut opts = opts.clone();
+    let mut warnings = Vec::new();
+    if opts.guard && !capabilities.supports_guard {
+        opts.guard = false;
+        warnings.push(format!(
+            "--guard: --harness {label} declares no write guard — continuing unguarded; \
+             out-of-bounds writes are detected after the fact by the detect-stray-writes \
+             audit (folded into `ingest`), never blocked."
+        ));
+    }
+    if !opts.no_stage && adapter.skills_dir(Path::new(".")).is_none() {
+        opts.no_stage = true;
+        warnings.push(format!(
+            "--harness {label} declares no skills_dir — native staging is unavailable; \
+             falling back to --no-stage (each SKILL.md is inlined into its dispatch prompt)."
+        ));
+    }
+    if adapter.cli_events_filename().is_none() {
+        warnings.push(format!(
+            "--harness {label} declares no transcript parser — transcript_check assertions \
+             will grade as unverifiable and llm_judge carries the grading; tokens/duration \
+             go unrecorded. Recover each final message into outputs/final-message.md \
+             (see RUNBOOK.md)."
+        ));
     }
+    if (opts.agent_model.is_some() || opts.judge_model.is_some())
+        && adapter.cli_model_flag().is_none()
+    {
+        warnings.push(format!(
+            "--harness {label} declares no model flag — models are recorded in \
+             conditions.json as provenance only; dispatches run on the harness's \
+             default model."
+        ));
+    }
+    Ok(HarnessPreflight { opts, warnings })
 }
 
 /// A per-run nonce (`<millis-base36>-<6 hex>`) that namespaces dispatch
@@ -161,15 +212,86 @@ mod tests {
     }
 
     #[test]
-    fn claude_allows_guard() {
+    fn claude_preflight_is_quiet_and_keeps_guard() {
         // `claude -p` loads the project `.claude/settings.local.json` PreToolUse
-        // hook from its cwd, so the write guard fires under CLI dispatch.
+        // hook from its cwd, so the write guard fires under CLI dispatch. A
+        // fully-enhanced harness produces no fallback warnings.
         let (_t, ctx) = ctx_for(Harness::resolve("claude-code").unwrap());
         let opts = RunOptions {
             guard: true,
             ..Default::default()
         };
-        assert!(validate_harness_run_options(&opts, &ctx).is_ok());
+        let preflight = harness_run_preflight(&opts, &ctx).unwrap();
+        assert!(preflight.opts.guard);
+        assert!(preflight.warnings.is_empty(), "{:?}", preflight.warnings);
+    }
+
+    #[test]
+    fn guard_on_a_guardless_harness_warns_and_continues_unguarded() {
+        let (_t, ctx) = ctx_for(Harness::resolve("opencode").unwrap());
+        let opts = RunOptions {
+            guard: true,
+            ..Default::default()
+        };
+        let preflight = harness_run_preflight(&opts, &ctx).unwrap();
+        assert!(!preflight.opts.guard, "guard is forced off, not rejected");
+        let warning = preflight
+            .warnings
+            .iter()
+            .find(|w| w.contains("--guard"))
+            .expect("a guard warning fires");
+        assert!(
+            warning.contains("detect-stray-writes"),
+            "names the fallback: {warning}"
+        );
+        assert!(warning.contains("never blocked"), "{warning}");
+    }
+
+    #[test]
+    fn transcriptless_harness_warns_naming_the_llm_judge_fallback() {
+        let (_t, ctx) = ctx_for(Harness::resolve("opencode").unwrap());
+        let preflight = harness_run_preflight(&RunOptions::default(), &ctx).unwrap();
+        let warning = preflight
+            .warnings
+            .iter()
+            .find(|w| w.contains("transcript"))
+            .expect("a transcript warning fires");
+        assert!(warning.contains("unverifiable"), "{warning}");
+        assert!(
+            warning.contains("llm_judge"),
+            "names the fallback: {warning}"
+        );
+        assert!(warning.contains("final-message.md"), "{warning}");
+    }
+
+    #[test]
+    fn model_flags_without_a_descriptor_model_flag_warn_provenance_only() {
+        let (_t, ctx) = ctx_for(Harness::resolve("opencode").unwrap());
+        let opts = RunOptions {
+            agent_model: Some("some-model"),
+            ..Default::default()
+        };
+        let preflight = harness_run_preflight(&opts, &ctx).unwrap();
+        let warning = preflight
+            .warnings
+            .iter()
+            .find(|w| w.contains("model flag"))
+            .expect("a model warning fires");
+        assert!(
+            warning.contains("provenance"),
+            "names the fallback: {warning}"
+        );
+    }
+
+    #[test]
+    fn no_model_warning_when_no_models_are_requested() {
+        let (_t, ctx) = ctx_for(Harness::resolve("opencode").unwrap());
+        let preflight = harness_run_preflight(&RunOptions::default(), &ctx).unwrap();
+        assert!(
+            !preflight.warnings.iter().any(|w| w.contains("model flag")),
+            "{:?}",
+            preflight.warnings
+        );
     }
 
     #[test]
diff --git a/tests/run/opencode.rs b/tests/run/opencode.rs
index 447aff8..43db1c2 100644
--- a/tests/run/opencode.rs
+++ b/tests/run/opencode.rs
@@ -1,9 +1,10 @@
 //! OpenCode-harness behavior: `.opencode/skills` staging, slug sanitization,
 //! native `<available_skills>` dispatch rendering, plan-mode approximation, and
-//! the `--guard` rejection. Characterization tests pinning current behavior so
-//! the run-mode refactor stays behavior-preserving.
+//! the `--guard` warn-and-continue fallback. Characterization tests pinning
+//! current behavior so the run-mode refactor stays behavior-preserving.
 
 use crate::helpers::*;
+use predicates::prelude::PredicateBooleanExt;
 use predicates::str::contains;
 use std::fs;
 use std::path::Path;
@@ -148,9 +149,11 @@ fn opencode_plan_mode_injects_profile_and_records_flag() {
 }
 
 #[test]
-fn opencode_rejects_guard() {
+fn opencode_guard_warns_and_continues_unguarded() {
     let tmp = tempfile::TempDir::new().unwrap();
     let (skill_dir, cwd) = setup(tmp.path(), DEFAULT_EVALS);
+    // The #126 model: an undeclared enhancement warns naming its fallback and
+    // the run proceeds — it never rejects.
     skill_eval()
         .current_dir(&cwd)
         .args(["run", "--skill-dir"])
@@ -165,11 +168,26 @@ fn opencode_rejects_guard() {
             "--guard",
         ])
         .assert()
-        .failure()
-        .stderr(contains("Unsupported for --harness opencode: --guard"));
+        .success()
+        .stderr(
+            contains("declares no write guard")
+                .and(contains("detect-stray-writes"))
+                .and(contains("Unsupported for --harness").not()),
+        );
 
-    assert!(!cwd.join(".opencode/skills").exists());
-    assert!(!iteration_dir(&cwd).exists());
+    // The run was built (staged, dispatch written) — just without a guard.
+    assert!(iteration_dir(&cwd).exists());
+    let with_skill_env = cli_env_dir(&cwd, "g1", "with_skill");
+    assert!(
+        with_skill_env.join(".opencode/skills").exists(),
+        "staging proceeded"
+    );
+    assert!(
+        !with_skill_env
+            .join(".opencode/skills/.slow-powers-eval-guard.json")
+            .exists(),
+        "no guard marker was installed"
+    );
 }
 
 #[test]

From 855f6d278b4af06bb8f88b3f6c741a6d2bf974b0 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:38:00 -0400
Subject: [PATCH 07/10] feat(dispatch): generic recipes for descriptor-only
 harnesses

A descriptor with just a label and an exec_template now earns real
dispatch guidance: cli_next_steps renders a generic iterate-dispatch
recipe around the rendered exec command, and dispatch-manifest.md gains
a generic '## Dispatch recipe' section with the final-message capture
contract. A baseline descriptor (no exec template) gets the
harness-agnostic handoff naming outputs/final-message.md and the ingest
line. Built-in harnesses all declare their own templates, so the golden
artifacts are untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 src/adapters/descriptor_adapter.rs | 102 ++++++++++++++++++++++++++++-
 1 file changed, 100 insertions(+), 2 deletions(-)

diff --git a/src/adapters/descriptor_adapter.rs b/src/adapters/descriptor_adapter.rs
index 0b31561..4daf49a 100644
--- a/src/adapters/descriptor_adapter.rs
+++ b/src/adapters/descriptor_adapter.rs
@@ -265,8 +265,26 @@ impl HarnessAdapter for DescriptorAdapter {
     }
 
     fn cli_next_steps(&self, ctx: CliDispatchContext<'_>) -> String {
+        let ingest_line = format!(
+            "ingest{} --iteration {} --harness {}",
+            ctx.target_args, ctx.iteration, self.descriptor.label
+        );
         let Some(template) = &self.descriptor.dispatch.next_steps_template else {
-            return String::new();
+            // Generic fallbacks: a descriptor with just an exec template still
+            // earns a copy-pasteable recipe; a baseline descriptor gets the
+            // harness-agnostic handoff.
+            return match &self.descriptor.dispatch.exec_template {
+                Some(_) => format!(
+                    "\nNext: iterate the tasks[] array in dispatch.json and dispatch each task \
+                     with:\n{}\nThen run `{ingest_line}`.",
+                    self.exec_command(ctx.guard, ctx.agent_model)
+                ),
+                None => format!(
+                    "\nNext: read dispatch-manifest.md and dispatch each task through your \
+                     harness's one-shot CLI from the task's eval_root, saving the agent's \
+                     final reply to outputs/final-message.md.\nThen run `{ingest_line}`."
+                ),
+            };
         };
         let exec_command = self.exec_command(ctx.guard, ctx.agent_model);
         let iteration = ctx.iteration.to_string();
@@ -287,7 +305,24 @@ impl HarnessAdapter for DescriptorAdapter {
     }
 
     fn cli_manifest_section(&self, ctx: CliManifestContext<'_>) -> Option<Vec<String>> {
-        let template = self.descriptor.dispatch.manifest_template.as_ref()?;
+        let Some(template) = self.descriptor.dispatch.manifest_template.as_ref() else {
+            // An exec template without a manifest template still earns a
+            // generic recipe section; without either, the manifest's shared
+            // header text already covers the baseline handoff.
+            self.descriptor.dispatch.exec_template.as_ref()?;
+            let exec_command = self.exec_command(ctx.guard, ctx.agent_model);
+            return Some(
+                format!(
+                    "## Dispatch recipe\n\nFrom each task's `eval_root`, dispatch with:\n\
+                     {exec_command}\n\nEnsure the agent's final reply lands in the task's \
+                     `outputs/final-message.md` (capture it yourself if the command does not \
+                     write it).\n"
+                )
+                .split('\n')
+                .map(String::from)
+                .collect(),
+            );
+        };
         let exec_command = self.exec_command(ctx.guard, ctx.agent_model);
         let parallel_recipe = match &self.descriptor.dispatch.parallel_command_template {
             Some(block_template) => {
@@ -361,6 +396,69 @@ mod tests {
         })
     }
 
+    fn adapter_from(toml_src: &str) -> super::DescriptorAdapter {
+        super::DescriptorAdapter::from_descriptor(
+            crate::adapters::descriptor::load_descriptor(toml_src, "test.toml").unwrap(),
+        )
+    }
+
+    #[test]
+    fn exec_template_alone_yields_generic_dispatch_recipes() {
+        use crate::adapters::harness::{CliManifestContext, HarnessAdapter};
+        let adapter = adapter_from(
+            "label = \"cool-custom-harness\"\n\n[dispatch]\nexec_template = \"cool-cli run <dispatch_prompt_path>{model_arg}\"\n",
+        );
+        let next = adapter.cli_next_steps(CliDispatchContext {
+            guard: false,
+            target_args: " --skill-dir /s --skill x",
+            iteration: 3,
+            agent_model: None,
+        });
+        assert!(next.contains("cool-cli run"), "{next}");
+        assert!(
+            next.contains(
+                "ingest --skill-dir /s --skill x --iteration 3 --harness cool-custom-harness"
+            ),
+            "{next}"
+        );
+        let manifest = adapter
+            .cli_manifest_section(CliManifestContext {
+                guard: false,
+                agent_model: None,
+            })
+            .expect("an exec template earns a generic manifest recipe")
+            .join("\n");
+        assert!(manifest.contains("cool-cli run"), "{manifest}");
+        assert!(manifest.contains("final-message.md"), "{manifest}");
+    }
+
+    #[test]
+    fn baseline_descriptor_yields_the_generic_handoff() {
+        use crate::adapters::harness::{CliManifestContext, HarnessAdapter};
+        let adapter = adapter_from("label = \"cool-custom-harness\"\n");
+        let next = adapter.cli_next_steps(CliDispatchContext {
+            guard: false,
+            target_args: " --skill x",
+            iteration: 1,
+            agent_model: None,
+        });
+        assert!(next.contains("one-shot CLI"), "{next}");
+        assert!(next.contains("outputs/final-message.md"), "{next}");
+        assert!(
+            next.contains("ingest --skill x --iteration 1 --harness cool-custom-harness"),
+            "{next}"
+        );
+        assert!(
+            adapter
+                .cli_manifest_section(CliManifestContext {
+                    guard: false,
+                    agent_model: None,
+                })
+                .is_none(),
+            "the manifest's generic header already covers the no-recipe baseline"
+        );
+    }
+
     #[test]
     fn exec_recipe_includes_model_only_when_declared() {
         let with = next_steps(Harness::resolve("claude-code").unwrap(), Some("opus"));

From b2c2da22d3167fb85dd8a99032919e9402889c3c Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:41:00 -0400
Subject: [PATCH 08/10] test(byoh): end-to-end acceptance coverage for
 descriptor-only harnesses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three integration tests pin the bring-your-own-harness contract: a
project-local descriptor with just a label and exec template carries a
complete run — fallback warnings, generic recipes in RUNBOOK.md and
dispatch-manifest.md, simulated dispatches, ingest with the
stray-writes audit, and llm_judge grading; a --harness-file descriptor
becomes the invocation's default harness; and a descriptor referencing
the codex-items parser by name gets full transcript ingest (parsed
tool invocations in run.json) with zero code.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 tests/run/byoh.rs | 241 ++++++++++++++++++++++++++++++++++++++++++++++
 tests/run/main.rs |   1 +
 2 files changed, 242 insertions(+)
 create mode 100644 tests/run/byoh.rs

diff --git a/tests/run/byoh.rs b/tests/run/byoh.rs
new file mode 100644
index 0000000..967f7b5
--- /dev/null
+++ b/tests/run/byoh.rs
@@ -0,0 +1,241 @@
+//! Bring-your-own-harness end to end: a project-local descriptor file alone
+//! carries a complete run — build, dispatch simulation, ingest with the
+//! stray-writes audit, and llm_judge grading — plus the `--harness-file`
+//! session default and zero-code transcript ingest via a named capability.
+
+use crate::helpers::*;
+use predicates::prelude::PredicateBooleanExt;
+use predicates::str::contains;
+use serde_json::Value;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+/// A minimal BYOH descriptor: label + exec template, nothing else.
+const COOL_DESCRIPTOR: &str = r#"label = "cool-custom-harness"
+
+[dispatch]
+exec_template = "cool-cli run --cd <eval-root>{model_arg} <dispatch_prompt_path> > <outputs_dir>/final-message.md"
+"#;
+
+/// Write `<cwd>/.eval-magic/harnesses/cool.toml`.
+fn write_project_descriptor(cwd: &Path, contents: &str) {
+    let dir = cwd.join(".eval-magic").join("harnesses");
+    fs::create_dir_all(&dir).unwrap();
+    fs::write(dir.join("cool.toml"), contents).unwrap();
+}
+
+/// Resolve a dispatch.json path (they may be cwd-relative) against `cwd`.
+fn resolve(cwd: &Path, path: &str) -> PathBuf {
+    let path = Path::new(path);
+    if path.is_absolute() {
+        path.to_path_buf()
+    } else {
+        cwd.join(path)
+    }
+}
+
+/// The tasks[] array from the iteration's dispatch.json.
+fn dispatch_tasks(cwd: &Path) -> Vec<Value> {
+    read_json(&iteration_dir(cwd).join("dispatch.json"))["tasks"]
+        .as_array()
+        .expect("dispatch.json carries tasks[]")
+        .clone()
+}
+
+/// Criterion: a descriptor file alone produces a complete llm_judge-graded
+/// run with the stray-writes audit — warnings name their fallbacks, and the
+/// exec recipe lands in RUNBOOK.md and dispatch-manifest.md.
+#[test]
+fn descriptor_alone_carries_a_complete_run() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let (skill_dir, cwd) = setup(tmp.path(), DEFAULT_EVALS);
+    write_project_descriptor(&cwd, COOL_DESCRIPTOR);
+
+    // Build the run: every undeclared enhancement warns naming its fallback.
+    skill_eval()
+        .current_dir(&cwd)
+        .args(["run", "--skill-dir"])
+        .arg(&skill_dir)
+        .args([
+            "--skill",
+            "mr-review",
+            "--mode",
+            "new-skill",
+            "--harness",
+            "cool-custom-harness",
+            "--agent-model",
+            "some-model",
+        ])
+        .assert()
+        .success()
+        .stderr(
+            contains("declares no skills_dir")
+                .and(contains("--no-stage"))
+                .and(contains("declares no transcript parser"))
+                .and(contains("llm_judge"))
+                .and(contains("declares no model flag"))
+                .and(contains("provenance")),
+        );
+
+    // The exec recipe reached both human-facing artifacts.
+    let runbook = read_str(&iteration_dir(&cwd).join("RUNBOOK.md"));
+    assert!(runbook.contains("cool-cli run"), "{runbook}");
+    let manifest = read_str(&iteration_dir(&cwd).join("dispatch-manifest.md"));
+    assert!(manifest.contains("## Dispatch recipe"), "{manifest}");
+    assert!(manifest.contains("cool-cli run"), "{manifest}");
+
+    // Forced --no-stage: nothing was staged, so no task carries a staged slug.
+    let tasks = dispatch_tasks(&cwd);
+    assert_eq!(tasks.len(), 2, "one eval × two conditions");
+    assert!(
+        tasks.iter().all(|t| t["staged_skill_slug"].is_null()),
+        "no-stage run stages nothing"
+    );
+
+    // Simulate the dispatches: recover each final message by hand.
+    for task in &tasks {
+        let outputs = resolve(&cwd, task["outputs_dir"].as_str().unwrap());
+        fs::create_dir_all(&outputs).unwrap();
+        fs::write(outputs.join("final-message.md"), "I reviewed the MR.\n").unwrap();
+    }
+
+    // Ingest: record-runs from final messages, the stray-writes audit, and
+    // grade's llm_judge hand-off all run without any harness code.
+    skill_eval()
+        .current_dir(&cwd)
+        .args(["ingest", "--skill-dir"])
+        .arg(&skill_dir)
+        .args([
+            "--skill",
+            "mr-review",
+            "--harness",
+            "cool-custom-harness",
+            "--iteration",
+            "1",
+        ])
+        .assert()
+        .success()
+        .stderr(contains("no transcript parser"));
+
+    assert!(
+        iteration_dir(&cwd).join("stray-writes.json").exists(),
+        "the stray-writes audit ran"
+    );
+    let judge_tasks = read_json(&iteration_dir(&cwd).join("judge-tasks.json"));
+    assert!(
+        judge_tasks["total_tasks"].as_u64().unwrap_or(0) >= 1,
+        "llm_judge carries the grading: {judge_tasks}"
+    );
+    for task in &tasks {
+        let record = read_json(&resolve(&cwd, task["run_record_path"].as_str().unwrap()));
+        assert_eq!(record["final_message"], "I reviewed the MR.");
+    }
+}
+
+/// A `--harness-file` descriptor becomes the invocation's default harness
+/// when `--harness` is omitted.
+#[test]
+fn harness_file_label_is_the_default_harness() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let (skill_dir, cwd) = setup(tmp.path(), DEFAULT_EVALS);
+    let file = tmp.path().join("cool.toml");
+    fs::write(&file, COOL_DESCRIPTOR).unwrap();
+
+    skill_eval()
+        .current_dir(&cwd)
+        .args(["run", "--skill-dir"])
+        .arg(&skill_dir)
+        .args(["--skill", "mr-review", "--mode", "new-skill"])
+        .arg("--harness-file")
+        .arg(&file)
+        .assert()
+        .success();
+
+    let conditions = read_json(&iteration_dir(&cwd).join("conditions.json"));
+    assert_eq!(
+        conditions["harness"], "cool-custom-harness",
+        "the one-off descriptor's label is the run's default harness"
+    );
+}
+
+/// Scope item 4: a user descriptor referencing a built-in transcript parser by
+/// name (`codex-items`) gets full transcript ingest with zero code.
+#[test]
+fn named_capability_gives_zero_code_transcript_ingest() {
+    let tmp = tempfile::TempDir::new().unwrap();
+    let (skill_dir, cwd) = setup(tmp.path(), DEFAULT_EVALS);
+    write_project_descriptor(
+        &cwd,
+        r#"label = "cool-custom-harness"
+
+[tools]
+write = ["file_change"]
+shell = ["command_execution"]
+
+[transcript]
+events_filename = "cool-events.jsonl"
+parser = "codex-items"
+
+[dispatch]
+exec_template = "cool-cli run --cd <eval-root> <dispatch_prompt_path> > <outputs_dir>/cool-events.jsonl"
+"#,
+    );
+
+    skill_eval()
+        .current_dir(&cwd)
+        .args(["run", "--skill-dir"])
+        .arg(&skill_dir)
+        .args([
+            "--skill",
+            "mr-review",
+            "--mode",
+            "new-skill",
+            "--harness",
+            "cool-custom-harness",
+        ])
+        .assert()
+        .success()
+        .stderr(contains("declares no transcript parser").not());
+
+    // Simulate dispatches that emit Codex-compatible JSONL events.
+    for task in dispatch_tasks(&cwd) {
+        let outputs = resolve(&cwd, task["outputs_dir"].as_str().unwrap());
+        fs::create_dir_all(&outputs).unwrap();
+        fs::write(outputs.join("final-message.md"), "Done.\n").unwrap();
+        fs::write(
+            outputs.join("cool-events.jsonl"),
+            concat!(
+                r#"{"type":"item.completed","item":{"id":"item_1","type":"command_execution","command":"bash -lc 'cat notes.md'","output":"notes","status":"completed"}}"#,
+                "\n",
+                r#"{"type":"item.completed","item":{"id":"item_2","type":"agent_message","text":"Done."}}"#,
+                "\n",
+            ),
+        )
+        .unwrap();
+    }
+
+    skill_eval()
+        .current_dir(&cwd)
+        .args(["ingest", "--skill-dir"])
+        .arg(&skill_dir)
+        .args([
+            "--skill",
+            "mr-review",
+            "--harness",
+            "cool-custom-harness",
+            "--iteration",
+            "1",
+        ])
+        .assert()
+        .success()
+        .stderr(contains("no transcript parser").not());
+
+    // The run records carry parsed tool invocations — full transcript ingest
+    // from configuration alone.
+    for task in dispatch_tasks(&cwd) {
+        let record = read_json(&resolve(&cwd, task["run_record_path"].as_str().unwrap()));
+        let invocations = record["tool_invocations"].as_array().unwrap();
+        assert_eq!(invocations.len(), 1, "{record}");
+        assert_eq!(invocations[0]["name"], "command_execution");
+    }
+}
diff --git a/tests/run/main.rs b/tests/run/main.rs
index 42cd0f7..4e2a975 100644
--- a/tests/run/main.rs
+++ b/tests/run/main.rs
@@ -9,6 +9,7 @@
 
 mod helpers;
 
+mod byoh;
 mod claude_cli;
 mod codex;
 mod env_layout;

From f12d6acd85c98a93f0364822665080b5c017b9fb Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:43:46 -0400
Subject: [PATCH 09/10] docs(byoh): authoring guide, enhancement-contract
 updates, README + help
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New docs/byoh.md — the user-facing bring-your-own-harness guide: the
minimum viable descriptor, the exec-template contract (eval_root cwd,
final-message recovery), layer order and field-level merge semantics,
the named-capability reference, the guard restriction, the
warning/fallback table, and the lint/show/list workflow.
progressive-enhancements.md catches up with the layered registry (label
is the only required field, warn-never-reject preflight, layers.rs and
registry init in the code map) and its Adding-a-new-harness checklist
now starts from a user descriptor instead of the retired enum variant
step. README gains the BYOH paragraph, a docs-table row, and the
guard-fallback wording; --help's examples cover harness lint/list/show
and --harness-file.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md                        |   5 +-
 docs/byoh.md                     | 172 +++++++++++++++++++++++++++++++
 docs/progressive-enhancements.md |  63 +++++++----
 src/cli/help.rs                  |  11 ++
 4 files changed, 228 insertions(+), 23 deletions(-)
 create mode 100644 docs/byoh.md

diff --git a/README.md b/README.md
index e220990..4217faa 100644
--- a/README.md
+++ b/README.md
@@ -256,6 +256,8 @@ For the `without_skill` / baseline condition, the dispatch reflects "this skill
 
 Every artifact follows a JSON Schema in [`schema/`](schema/), so a run record means the same thing regardless of which harness produced it. Harness support is **a minimal baseline plus progressive enhancements**: any harness with a headless one-shot CLI can run evals at baseline (`--no-stage` inlines the skill into each dispatch prompt, `llm_judge` grades, `detect-stray-writes` audits), and each enhancement a harness's adapter wires raises fidelity from there. What each enhancement is, why it needs harness-specific support, and what its fallback is are documented in [docs/progressive-enhancements.md](docs/progressive-enhancements.md).
 
+**Bring your own harness:** a harness eval-magic has never seen is added with a TOML descriptor file — no code. Descriptors layer (embedded built-ins → `~/.config/eval-magic/harnesses/` → `.eval-magic/harnesses/` → `--harness-file`) with field-level merge, so a project can also retune a single field of a built-in. `eval-magic harness list|show|lint` inspect and validate the registry; the authoring guide is [docs/byoh.md](docs/byoh.md).
+
 ### How dispatch works
 
 Every eval test and judge is dispatched the same way: through the harness's one-shot CLI (`claude -p`, `codex exec`), one subprocess per task, each `cd`'d into its `(group, condition)` env and writing its events transcript to disk. `run` prepares the envs and `RUNBOOK.md`; from there an **agent session** can drive the loop (reading the runbook and shelling out each recipe) or a **human** can follow the same runbook by hand. The generated `RUNBOOK.md` / `dispatch-manifest.md` carry the exact per-task recipes for the selected harness — they, not this README, are the runtime reference for dispatch commands.
@@ -272,7 +274,7 @@ This table is the source of truth for per-harness enhancement support:
 
 ¹ `run --harness opencode` stages skills and emits native dispatch prompts, but prints manual `opencode run` guidance instead of a copy-pasteable recipe.
 
-A missing enhancement degrades fidelity, never correctness — every column has a fallback: without native staging, `--no-stage` inlines each `SKILL.md` into its dispatch prompt; without transcript ingest, `transcript_check` assertions grade as unverifiable and `llm_judge` carries the grading (tokens and duration go unrecorded); without a model flag, `--agent-model` / `--judge-model` are recorded as provenance only; without a write guard, `--guard` is rejected and `detect-stray-writes` audits after the fact.
+A missing enhancement degrades fidelity, never correctness — every column has a fallback, and the `run` preflight warns naming it: without native staging, `--no-stage` inlines each `SKILL.md` into its dispatch prompt; without transcript ingest, `transcript_check` assertions grade as unverifiable and `llm_judge` carries the grading (tokens and duration go unrecorded); without a model flag, `--agent-model` / `--judge-model` are recorded as provenance only; without a write guard, `--guard` continues unguarded and `detect-stray-writes` audits after the fact.
 
 Per-harness implementation notes for developers wiring features live in [docs/claude-notes.md](docs/claude-notes.md), [docs/codex-notes.md](docs/codex-notes.md), and [docs/opencode-notes.md](docs/opencode-notes.md).
 
@@ -281,6 +283,7 @@ Per-harness implementation notes for developers wiring features live in [docs/cl
 | Where | What's in it |
 |-------|--------------|
 | `eval-magic --help` / `eval-magic <cmd> --help` | The flag-by-flag reference: every subcommand and flag, worked examples, the `--skill-dir` model, the skill-invocation meta-check |
+| [docs/byoh.md](docs/byoh.md) | Bring your own harness: authoring a descriptor file for an unknown harness, layering/merge rules, named capabilities, and the `harness list`/`show`/`lint` workflow |
 | [docs/progressive-enhancements.md](docs/progressive-enhancements.md) | Development doc: the harness baseline-vs-enhancement contract — what each enhancement unlocks, why it needs harness-specific code, and its fallback |
 | [docs/claude-notes.md](docs/claude-notes.md) / [docs/codex-notes.md](docs/codex-notes.md) / [docs/opencode-notes.md](docs/opencode-notes.md) | Development docs: per-harness implementation notes for working on eval-magic's harness support |
 | [GitHub issues](https://github.com/slowdini/eval-magic/issues) | Planned features and known limitations |
diff --git a/docs/byoh.md b/docs/byoh.md
new file mode 100644
index 0000000..5ae1358
--- /dev/null
+++ b/docs/byoh.md
@@ -0,0 +1,172 @@
+# Bring your own harness
+
+> **Audience:** anyone (human or agent) pointing eval-magic at a harness it has never seen. No Rust
+> required — a harness declares its capabilities in a TOML descriptor file, and every capability it
+> *doesn't* declare degrades to a documented fallback with a warning, never a rejection. The
+> baseline-vs-enhancement contract behind this is
+> [progressive-enhancements.md](progressive-enhancements.md).
+
+## The five-minute version
+
+From inside a project that dispatches through `cool-custom-harness`:
+
+```sh
+mkdir -p .eval-magic/harnesses
+cat > .eval-magic/harnesses/cool-custom-harness.toml <<'EOF'
+label = "cool-custom-harness"
+
+[dispatch]
+exec_template = '''
+cool-cli run --cd <eval-root>{model_arg} \
+  "Read the file at <dispatch_prompt_path> and follow its instructions exactly." \
+  > <outputs_dir>/final-message.md'''
+EOF
+
+eval-magic harness lint .eval-magic/harnesses/cool-custom-harness.toml
+eval-magic harness list
+eval-magic run --harness cool-custom-harness
+```
+
+That run is complete: `run` warns about each enhancement the descriptor doesn't declare (naming the
+fallback that carries it), builds `dispatch.json` / `RUNBOOK.md` / `dispatch-manifest.md` with your
+exec recipe, and after you dispatch the tasks, `ingest` assembles records from each task's
+`outputs/final-message.md`, runs the `detect-stray-writes` audit, and hands grading to `llm_judge`.
+
+For a one-off descriptor that shouldn't live in the project, pass it directly — its label becomes
+the invocation's default harness, so `--harness` can be omitted:
+
+```sh
+eval-magic run --harness-file ./cool-custom-harness.toml
+```
+
+## The minimum viable descriptor
+
+`label` alone loads:
+
+```toml
+label = "cool-custom-harness"
+```
+
+That is a **baseline** harness: staging is unavailable (runs fall back to `--no-stage`, inlining
+each `SKILL.md` into its dispatch prompt), and dispatch guidance is generic. Add an
+`[dispatch] exec_template` and the generated `RUNBOOK.md` / `dispatch-manifest.md` carry a
+copy-pasteable per-task recipe instead.
+
+### The exec-template contract
+
+`exec_template` is the one-shot command that dispatches a single task. eval-magic substitutes
+`{model_arg}` (the harness's model flag + requested model, empty unless `[model].flag` is declared)
+and `{guard_args}` (guard-only arguments, built-ins only); the `<eval-root>`,
+`<dispatch_prompt_path>`, and `<outputs_dir>` placeholders are filled per task by whoever dispatches
+(the runbook explains this). Two hard requirements:
+
+1. **Run from the task's `eval_root`** — each task's per-`(group, condition)` env dir is the
+   subprocess cwd.
+2. **Recover the final message** — the agent's final reply must land in
+   `outputs/final-message.md`. If your CLI can't write it directly (like the example above
+   redirecting stdout), capture it yourself before running `ingest`.
+
+## Layering and field-level merge
+
+Descriptor files stack in precedence order; **later layers override individual fields** of an
+earlier descriptor with the same `label` (tables merge key-by-key; scalars and arrays replace
+wholesale — never whole-file shadowing). A new `label` defines a new harness.
+
+1. **Embedded built-ins** — `claude-code`, `codex`, `opencode` (bundled in the binary).
+2. **User-global** — `<config-root>/harnesses/*.toml`, where the config root is
+   `$EVAL_MAGIC_CONFIG_DIR` (empty value disables the layer), else `$XDG_CONFIG_HOME/eval-magic`,
+   else `~/.config/eval-magic`.
+3. **Project-local** — `<cwd>/.eval-magic/harnesses/*.toml`.
+4. **`--harness-file <path>`** — a one-off top layer; when `--harness` is omitted its label is the
+   invocation's default harness.
+
+Files within one directory apply in filename order; one file per label per layer (a duplicate is
+skipped with a warning). So a project can retune a single built-in field without restating the
+descriptor:
+
+```toml
+# .eval-magic/harnesses/claude-code.toml — override one field of a built-in
+label = "claude-code"
+
+[model]
+flag = "--model-x"
+```
+
+`eval-magic harness show claude-code` prints the resolved post-merge descriptor (as authorable
+TOML, headed by the contributing files) — the fastest way to see what a layer actually changed.
+Note the merge can't *delete*: an override can replace a field's value but cannot remove an
+embedded table.
+
+**Broken discovered files never brick the CLI** — they are skipped with a warning pointing at
+`eval-magic harness lint <file>`. A broken `--harness-file` is a hard error (you named it
+explicitly).
+
+## Field reference
+
+The authoritative field-by-field reference is the bundled schema,
+[`schema/harness-descriptor.schema.json`](../schema/harness-descriptor.schema.json); the semantics
+and fallbacks per enhancement are in
+[progressive-enhancements.md](progressive-enhancements.md). The short map:
+
+| Table | Declares | Fallback when absent |
+|-------|----------|----------------------|
+| (top level) | `label` (required), `skills_dir`, `config_dirs` | no `skills_dir` ⇒ forced `--no-stage`, SKILL.md inlined |
+| `[dispatch]` | exec/parallel/judge/next-steps/manifest templates | generic handoff text; with only `exec_template`, generic recipes are built around it |
+| `[transcript]` | `events_filename` + `parser` (a named capability) | `transcript_check` grades unverifiable, `llm_judge` carries grading, tokens/duration unrecorded |
+| `[model]` | `flag` | `--agent-model`/`--judge-model` recorded as provenance only |
+| `[staging]` + `[skills_block]` | slug/naming rules, skills-block format | `--no-stage` inlining |
+| `[tools]` | tool-name vocabulary by role | required alongside `[transcript]` (the stray-writes audit classifies by it) |
+| `[shadow]` | `preflight` (named capability) | no shadow report — correct for harnesses that load nothing global |
+| `[guard]` | **built-ins only** — see below | `detect-stray-writes` audits after the fact |
+
+### Named capabilities: real code for free
+
+Everything that is genuinely code — transcript stitching, guard hooks, slug sanitization, shadow
+scanning — is a **named capability** a descriptor references. If your harness emits a compatible
+stream, you get the full feature from configuration alone:
+
+- `transcript.parser = "claude-stream-json"` — Claude Code `-p --output-format stream-json` events.
+- `transcript.parser = "codex-items"` — Codex `item.started`/`item.completed` JSONL.
+- `staging.slug_capability = "opencode"` — OpenCode's sanitizing slug rules.
+- `shadow.preflight = "claude-plugins"` — the Claude plugin/global-skills shadow scan.
+
+For example, a harness that logs Codex-compatible item JSONL gets full transcript ingest — parsed
+tool invocations, `transcript_check` grading, the works — with:
+
+```toml
+[tools]
+write = ["file_change"]
+shell = ["command_execution"]
+
+[transcript]
+events_filename = "cool-events.jsonl"
+parser = "codex-items"
+```
+
+An unknown capability name fails the schema gate listing the allowed values.
+
+### The guard restriction
+
+User-supplied descriptors may **not** declare `[guard]` or set `run.supports_guard = true`: the
+write guard installs native hook config into dispatch environments and stays restricted to
+built-in descriptors until the guard engine is opened up (fail-open safety). Unguarded runs fall
+back to the `detect-stray-writes` audit. A project-local overlay of a guarded built-in is fine —
+the restriction applies to the user file's own content, and the embedded guard merges through
+underneath it.
+
+## The workflow
+
+```sh
+eval-magic harness lint <file>   # full per-file report: TOML + schema, user-layer
+                                 # restrictions, cross-field invariants (merged onto the
+                                 # registered harness with the same label, if any)
+eval-magic harness lint <name>   # strictly re-lint every discovered layer of a name —
+                                 # surfaces files that registry init skipped with a warning
+eval-magic harness list          # every registered harness: layers + declared enhancements
+eval-magic harness show <name>   # the resolved post-merge descriptor as authorable TOML
+```
+
+Then `run --harness <name>` and read the warnings: each one names the fallback carrying that part
+of the run, which doubles as your wiring roadmap — declare the enhancement and the warning
+disappears. (A `harness lint --probe` live dispatch check — rendering the exec template with a
+trivial prompt and verifying final-message recovery — is planned; see the tracking issue.)
diff --git a/docs/progressive-enhancements.md b/docs/progressive-enhancements.md
index d34e49c..25acf8f 100644
--- a/docs/progressive-enhancements.md
+++ b/docs/progressive-enhancements.md
@@ -3,7 +3,9 @@
 > **Audience:** developers working on the eval-magic codebase. The README and `eval-magic --help`
 > are the user-facing docs; this file explains how harness support is structured in code and what
 > wiring more of it buys. Per-harness implementation notes live in [claude-notes.md](claude-notes.md),
-> [codex-notes.md](codex-notes.md), and [opencode-notes.md](opencode-notes.md).
+> [codex-notes.md](codex-notes.md), and [opencode-notes.md](opencode-notes.md). Pointing eval-magic
+> at a harness it doesn't know — user-supplied descriptor files, layering, `harness
+> list`/`show`/`lint` — is the user-facing [byoh.md](byoh.md).
 
 Harness compatibility is not a parity checklist to audit — it is **a minimal baseline every harness
 satisfies, plus optional enhancements** a harness's adapter opts into. A missing enhancement
@@ -34,9 +36,12 @@ That baseline already yields a working eval: `llm_judge` assertions grade every
 run records exist. Run records without a transcript parser are assembled by hand per
 `schema/run-record.schema.json`.
 
-In descriptor terms the baseline is two required fields: `label` and `skills_dir`. Everything else
-in a harness descriptor is optional — an absent field or table gets a working generic fallback or
-an `Unsupported` error naming the enhancement it belongs to.
+In descriptor terms the baseline is one required field: `label`. Everything else in a harness
+descriptor is optional — an absent field or table gets a working generic fallback, and the `run`
+preflight *warns* naming that fallback rather than rejecting (a harness without `skills_dir`
+forces `--no-stage`; `--guard` without a declared guard continues unguarded behind the
+`detect-stray-writes` audit; requested models without a model flag are recorded as provenance
+only). Only genuinely contradictory flag combinations stay errors.
 
 ## Where this lives in code
 
@@ -44,20 +49,30 @@ an `Unsupported` error naming the enhancement it belongs to.
   declarative value (labels, dirs, capability booleans, phrases, command templates, banner prose).
   Descriptors are schema-gated (`schema/harness-descriptor.schema.json`) and invariant-checked at
   load time.
+- `src/adapters/registry.rs` — the label-keyed registry: `init_registry` loads every **layer**
+  (embedded → user-global → project-local → `--harness-file`) with field-level merge per label,
+  and `adapter_for()` resolves each `Harness` handle to its descriptor-backed adapter — still the
+  single dispatch point. Broken discovered files skip with a warning; the layer model itself is
+  documented in [byoh.md](byoh.md).
+- `src/adapters/descriptor/layers.rs` — layer discovery (config-root resolution, per-directory
+  scans, the `--harness-file` top layer) and the user-layer restrictions (no `[guard]`).
 - `src/adapters/harness.rs` — the `HarnessAdapter` trait, tiered into baseline and enhancement
-  sections; `adapter_for()` resolves each `Harness` variant to a descriptor-backed adapter in the
-  embedded registry — still the single place a concrete harness is named.
-- `src/adapters/descriptor.rs` — the descriptor model, TOML loading, and `validate_descriptor`
-  (the load-time invariants); `src/adapters/descriptor_adapter.rs` — the one generic
-  `DescriptorAdapter` implementing the trait from a descriptor.
+  sections.
+- `src/adapters/descriptor.rs` — the descriptor model, the per-file schema gate
+  (`parse_descriptor_value`), field-level merge (`merge_descriptor_value`), and
+  `finalize_descriptor` (the load-time invariants, with merged-file provenance in every message);
+  `src/adapters/descriptor_adapter.rs` — the one generic `DescriptorAdapter` implementing the
+  trait from a descriptor.
 - `src/adapters/capabilities.rs` — the **named capabilities**: closed enums a descriptor references
   by kebab-case name for everything that is real code (transcript parsers, guard engines, slug
   generation, shadow preflight).
 - `src/adapters/<harness>/` — only the code behind those capabilities: transcript parsers, guard
   hooks, the plugin-shadow scan, the OpenCode slug sanitizer.
-- `run_capabilities()` (descriptor table `[run]`) — the narrow table the `run` preflight uses to
-  accept or reject run options (`--guard`, `--bootstrap`/`--stage-name` with `--no-stage`) per
-  harness.
+- `run_capabilities()` (descriptor table `[run]`) + `harness_run_preflight()`
+  (`src/cli/run/util.rs`) — the `run` preflight: undeclared enhancements warn naming their
+  fallback and adjust the options (`--guard` forced off, missing `skills_dir` forces
+  `--no-stage`); only contradictory flag combinations (`--bootstrap`/`--stage-name` where the
+  descriptor declares them incompatible with `--no-stage`) reject.
 
 ## The enhancements
 
@@ -141,7 +156,9 @@ The guard arbiter and `detect-stray-writes` classify tool names against the cros
 vocabulary union (`all_tool_vocabulary`), so wiring a guard or transcript parser without declaring
 the harness's tool names is rejected at descriptor load. The hidden `guard` / `guard-codex`
 subcommands are the hook entry points — their names are a stable on-disk contract. Shared
-marker/manifest/teardown machinery lives in `src/sandbox/`.
+marker/manifest/teardown machinery lives in `src/sandbox/`. **User-supplied descriptors may not
+declare `[guard]`** (fail-open safety — the engine installs native hook config); the restriction
+lifts when the guard engine is opened up.
 
 ### Shadow preflight
 
@@ -195,18 +212,20 @@ enhancement — keep it in sync with the adapters when wiring or dropping one.
 
 ## Adding a new harness
 
-1. Add the variant to `Harness` in `src/core/context.rs` (it derives `clap::ValueEnum`).
-2. Create `harnesses/<label>.toml` with the baseline fields (`label`, `skills_dir`, `config_dirs`),
-   embed it in `EMBEDDED_DESCRIPTORS` (`src/adapters/descriptor.rs`), and register it in the
-   registry behind `adapter_for()` (`src/adapters/harness.rs`). The label must match the variant's
-   kebab-case identifier — the registry asserts it.
+1. **Start as a user descriptor** — author `.eval-magic/harnesses/<label>.toml` per
+   [byoh.md](byoh.md) and iterate with `harness lint`/`show` and real runs. No Rust, no rebuild;
+   this is also where the descriptor's field set gets proven.
+2. **Promote to a built-in** once it earns bundling: move the file to `harnesses/<label>.toml` and
+   add it to `EMBEDDED_DESCRIPTORS` (`src/adapters/descriptor.rs`). The registry keys on the
+   descriptor's `label`.
 3. Create `docs/<harness>-notes.md` with the implementation notes discovered along the way.
 4. Add the harness to the README support table (all enhancements ❌ at baseline).
 5. Wire enhancements in leverage order — dispatch recipes and transcript parser first (they carry
-   the most fidelity), then staging, model flag, guard — updating the table as each lands. Most
-   enhancements are descriptor fields; add a named capability in
-   `src/adapters/capabilities.rs` (plus its `src/adapters/<harness>/` module) only when the
-   harness's stream or hooks are incompatible with every existing capability.
+   the most fidelity), then staging, model flag, guard (guard requires built-in status — user
+   descriptors may not declare one) — updating the table as each lands. Most enhancements are
+   descriptor fields; add a named capability in `src/adapters/capabilities.rs` (plus its
+   `src/adapters/<harness>/` module) only when the harness's stream or hooks are incompatible with
+   every existing capability.
 
 ## Guardrails
 
diff --git a/src/cli/help.rs b/src/cli/help.rs
index 937c14f..015b994 100644
--- a/src/cli/help.rs
+++ b/src/cli/help.rs
@@ -50,4 +50,15 @@ EXAMPLES:
   eval-magic run --harness opencode
   # ...dispatch each task with `opencode run`, then assemble records manually
   # until OpenCode transcript ingest is wired.
+
+  # Bring your own harness: describe it in a TOML file (see docs/byoh.md) —
+  # project-local descriptors live in .eval-magic/harnesses/*.toml
+  eval-magic harness lint .eval-magic/harnesses/cool-custom-harness.toml
+  eval-magic harness list
+  eval-magic run --harness cool-custom-harness
+  # ...or load a one-off descriptor (its label becomes the default harness):
+  eval-magic run --harness-file ./cool-custom-harness.toml
+
+  # Inspect the resolved descriptor after layer merging (built-ins included)
+  eval-magic harness show claude-code
 ";

From ff31449266a17b1da3a32923b4de9dab6a466cf2 Mon Sep 17 00:00:00 2001
From: Max Haarhaus <samiamorwas@gmail.com>
Date: Tue, 14 Jul 2026 18:59:28 -0400
Subject: [PATCH 10/10] fix(guard): keep the hook entry points off layered
 descriptor discovery
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hidden guard/guard-codex hooks fire on every PreToolUse in a
dispatched session and only ever need the embedded descriptors, so
cli::run() no longer runs init_registry for them — the lazy
embedded-only registry fallback serves the hook path, and a broken user
descriptor can't add a skip-warning (or discovery latency) per tool
call. Also from review: refresh the three doc comments that still
described the retired --harness value parser, caveat harness show's
copy-paste claim for guarded built-ins (drop [guard] before reusing as
a user layer), and reword lint's name-target failure summary to say the
✗ lines may belong to other discovered files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/byoh.md                |  5 +++--
 src/adapters/registry.rs    |  6 +++---
 src/cli/args.rs             |  5 ++++-
 src/cli/commands/harness.rs |  6 +++++-
 src/cli/mod.rs              | 12 +++++++++++-
 src/core/context.rs         |  8 ++++----
 tests/cli/guard.rs          | 22 ++++++++++++++++++++++
 7 files changed, 52 insertions(+), 12 deletions(-)

diff --git a/docs/byoh.md b/docs/byoh.md
index 5ae1358..e762709 100644
--- a/docs/byoh.md
+++ b/docs/byoh.md
@@ -94,8 +94,9 @@ flag = "--model-x"
 
 `eval-magic harness show claude-code` prints the resolved post-merge descriptor (as authorable
 TOML, headed by the contributing files) — the fastest way to see what a layer actually changed.
-Note the merge can't *delete*: an override can replace a field's value but cannot remove an
-embedded table.
+Two caveats: the merge can't *delete* (an override can replace a field's value but cannot remove
+an embedded table), and a guarded built-in's output isn't copy-paste-safe as a user layer until
+you drop its `[guard]` table and `run.supports_guard` (see the guard restriction below).
 
 **Broken discovered files never brick the CLI** — they are skipped with a warning pointing at
 `eval-magic harness lint <file>`. A broken `--harness-file` is a hard error (you named it
diff --git a/src/adapters/registry.rs b/src/adapters/registry.rs
index 2249765..871f3f2 100644
--- a/src/adapters/registry.rs
+++ b/src/adapters/registry.rs
@@ -3,9 +3,9 @@
 //!
 //! Descriptor sources load into label-keyed entries, and every way the rest of
 //! the crate names a harness funnels through them: [`Harness::resolve`] turns
-//! a string into a validated handle (also behind the `--harness` value parser
-//! and the artifact `Deserialize`), [`Harness::known`] enumerates the entries,
-//! and [`adapter_for`] serves each handle's [`HarnessAdapter`].
+//! a string into a validated handle (resolving `--harness` after parsing, and
+//! behind the artifact `Deserialize`), [`Harness::known`] enumerates the
+//! entries, and [`adapter_for`] serves each handle's [`HarnessAdapter`].
 
 use std::path::Path;
 use std::sync::{LazyLock, OnceLock};
diff --git a/src/cli/args.rs b/src/cli/args.rs
index 4810eb4..b3c4843 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -136,7 +136,10 @@ pub(crate) enum HarnessCommands {
     /// The output is authorable: the provenance header lists every contributing
     /// file as `#` comments, and the body is valid descriptor TOML you can copy
     /// into a layer file (`.eval-magic/harnesses/<name>.toml`) and edit. Fields
-    /// at their baseline defaults are omitted.
+    /// at their baseline defaults are omitted. When reusing a guarded built-in's
+    /// output as a user layer, drop its `[guard]` table and
+    /// `run.supports_guard` first — user-supplied descriptors may not declare
+    /// them.
     Show {
         /// Registered harness name (see `harness list`).
         name: String,
diff --git a/src/cli/commands/harness.rs b/src/cli/commands/harness.rs
index 6d2f0e8..5803e54 100644
--- a/src/cli/commands/harness.rs
+++ b/src/cli/commands/harness.rs
@@ -228,7 +228,11 @@ fn lint_name(name: &str) -> anyhow::Result<()> {
     }
 
     if failed > 0 {
-        bail!("descriptor lint failed for {name}: {failed} check(s) failed");
+        bail!(
+            "descriptor lint found {failed} failing check(s) across the discovered layers \
+             (see ✗ lines above; broken files are reported even when their label is not \
+             {name:?}, since a file that fails to parse has no readable label)"
+        );
     }
     println!("Linted {name}: all checks passed.");
     Ok(())
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 0974b12..a220a64 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -26,7 +26,17 @@ use commands::*;
 /// subcommand, and return its result. Called by the binary entry point.
 pub fn run() -> anyhow::Result<()> {
     let cli = Cli::parse();
-    crate::adapters::registry::init_registry(cli.harness_file.as_deref().map(Path::new))?;
+    // The hidden guard hooks fire on every PreToolUse in a dispatched session
+    // and only ever need the embedded descriptors — skip layered discovery so
+    // a broken user descriptor can't add noise or latency per tool call (the
+    // lazy registry fallback serves them embedded-only).
+    let is_guard_hook = matches!(
+        cli.command,
+        Some(Commands::Guard { .. } | Commands::GuardCodex { .. })
+    );
+    if !is_guard_hook {
+        crate::adapters::registry::init_registry(cli.harness_file.as_deref().map(Path::new))?;
+    }
     dispatch(cli.command)
 }
 
diff --git a/src/core/context.rs b/src/core/context.rs
index bd3ef36..f22fab4 100644
--- a/src/core/context.rs
+++ b/src/core/context.rs
@@ -14,7 +14,7 @@ use serde::Serialize;
 /// a held `Harness` always names a registered harness and adapter lookup never
 /// fails. The registry-dependent behavior lives next to the registry in
 /// `crate::adapters::harness`: `Harness::resolve` (the string-to-handle
-/// gateway, also behind the `--harness` value parser), `Harness::known` (every
+/// gateway, resolving `--harness` after parsing), `Harness::known` (every
 /// registered harness), `Default` (the registry's default harness), and
 /// `Deserialize` (resolves artifact values, rejecting unknown names).
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -58,9 +58,9 @@ pub struct RunContext {
 }
 
 /// Already-parsed flag values handed to [`detect_run_context`]. `clap` owns the
-/// actual argv parsing (including the registry-driven `--harness` rejection);
-/// this struct carries the raw values through to filesystem validation and
-/// defaulting.
+/// actual argv parsing, and `--harness` is resolved against the registry before
+/// this struct is built (unknown names are rejected there); it carries the raw
+/// values through to filesystem validation and defaulting.
 #[derive(Debug, Clone, Default)]
 pub struct DetectInput {
     pub skill_dir: Option<String>,
diff --git a/tests/cli/guard.rs b/tests/cli/guard.rs
index c05cd20..9e05d28 100644
--- a/tests/cli/guard.rs
+++ b/tests/cli/guard.rs
@@ -149,3 +149,25 @@ fn teardown_guard_removes_installed_guard() {
             .exists()
     );
 }
+
+/// The guard hook fires on every PreToolUse in a dispatched session, so it
+/// must not run layered descriptor discovery: a broken user descriptor in the
+/// eval env must not spam a skip-warning (or any other noise) per tool call.
+#[test]
+fn guard_hook_skips_descriptor_discovery() {
+    let tmp = TempDir::new().unwrap();
+    let marker = write_armed_marker(tmp.path(), &tmp.path().join(".eval-magic"));
+    let harnesses = tmp.path().join(".eval-magic").join("harnesses");
+    fs::create_dir_all(&harnesses).unwrap();
+    fs::write(harnesses.join("broken.toml"), "label = ").unwrap();
+
+    skill_eval()
+        .arg("guard")
+        .arg(&marker)
+        .current_dir(tmp.path())
+        .write_stdin(r#"{ "tool_name": "Write", "tool_input": { "file_path": "/etc/passwd" } }"#)
+        .assert()
+        .success()
+        .stdout(contains(r#""permissionDecision":"deny""#))
+        .stderr(contains("skipping harness descriptor").not());
+}