open-research-protocol 0.4.6 → 0.4.7

package/README.md

@@ -23,6 +23,7 @@ verification remains independent of framing. See `modules/instruments/README.md`
 - `docs/AGENT_LOOP.md` — canonical operating loop when an agent is the primary ORP user
 - `docs/CANONICAL_CLI_BOUNDARY.md` — canonical source-of-truth boundary between CLI, Rust, and web
 - `docs/ORP_REASONING_KERNEL_V0_1.md` — draft kernel model for turning loose intent into promotable canonical artifacts
+- `docs/ORP_REASONING_KERNEL_TECHNICAL_VALIDATION.md` — technical rationale, benchmarks, and alternatives analysis for the kernel
 - `docs/EXTERNAL_CONTRIBUTION_GOVERNANCE.md` — canonical local-first workflow for external OSS PR work
 - `docs/OSS_CONTRIBUTION_AGENT_LOOP.md` — agent operating rhythm for external contribution workflows
 - `templates/` — claim, verification, failure, and issue templates

package/docs/ORP_REASONING_KERNEL_TECHNICAL_VALIDATION.md

@@ -0,0 +1,353 @@
+# ORP Reasoning Kernel Technical Validation
+
+This document defines the ORP Reasoning Kernel in technical terms, explains
+why ORP implements it this way, and records the initial validation evidence
+for `v0.1`.
+
+The supporting benchmark artifact for this document is:
+
+- [docs/benchmarks/orp_reasoning_kernel_v0_1_validation.json](/Volumes/Code_2TB/code/orp/docs/benchmarks/orp_reasoning_kernel_v0_1_validation.json)
+
+## 1. Definition
+
+The ORP Reasoning Kernel is the typed artifact grammar and validation layer
+used by ORP to move work from free-form intent into canonical repository
+artifacts.
+
+It operates in three roles:
+
+1. Interpreter
+   Convert loose natural-language intent into a structured working shape.
+2. Validator
+   Check whether a candidate artifact is complete enough to be trusted and
+   promoted.
+3. Canonizer
+   Gate whether the artifact can become repository truth and show its
+   validation trace in ORP run output.
+
+The kernel is implemented through:
+
+- [spec/v1/kernel.schema.json](/Volumes/Code_2TB/code/orp/spec/v1/kernel.schema.json)
+- `orp kernel scaffold`
+- `orp kernel validate`
+- `structure_kernel` gate enforcement in [cli/orp.py](/Volumes/Code_2TB/code/orp/cli/orp.py)
+
+## 2. What Problem It Solves
+
+Without a kernel layer, ORP can still execute work, but repository truth tends
+to drift into one of two bad states:
+
+1. Chat soup
+   Important meaning lives in prompts and responses instead of canonical
+   artifacts.
+2. Hidden agent structure
+   The agent may internally interpret a task well, but another human or agent
+   cannot inspect that structure or validate promotion.
+
+The kernel addresses that by making promotable artifacts:
+
+- typed
+- minimally complete
+- machine-checkable
+- reusable in handoffs
+- visible in run artifacts
+
+## 3. Why This Kernel Instead Of Another Approach
+
+### A. Why not free-form markdown or chat alone?
+
+Free-form text is useful for ideation, but it does not reliably answer:
+
+- what kind of artifact this is
+- what minimum structure is present or missing
+- what should block promotion
+- what another operator can trust later
+
+ORP keeps natural language at the boundary and adds structure at promotion.
+
+### B. Why not require kernel-native syntax for all human input?
+
+Because that damages usability and adoption.
+
+Humans should be able to think in normal language. ORP should not require
+every prompt to be authored as a rigid schema object before work can happen.
+That is why the kernel is enforced at the artifact and gate layer rather than
+as a hard input parser for every message.
+
+### C. Why typed artifact classes instead of one generic checklist?
+
+Because a task, a decision, and a hypothesis fail in different ways.
+
+A single universal checklist loses semantic meaning. ORP therefore uses typed
+artifact classes with different required fields:
+
+- `task`
+- `decision`
+- `hypothesis`
+- `experiment`
+- `checkpoint`
+- `policy`
+- `result`
+
+This is enough structure to be useful without forcing a heavyweight ontology.
+
+### D. Why not a domain-specific kernel for just software or just research?
+
+Because ORP is meant to govern many kinds of work, not one domain.
+
+The chosen artifact classes map across:
+
+- software delivery
+- research
+- product design
+- operations and reliability
+- writing and knowledge work
+- policy and governance work
+
+### E. Why not a hidden agent-only kernel?
+
+Because invisible structure cannot be audited.
+
+If the agent interprets a request privately but the repository never records
+that shape, then the kernel is not stabilizing truth. ORP instead writes
+kernel validation into `RUN.json` and lets artifacts be validated directly
+from the CLI.
+
+### F. Why not a full ontology before shipping anything?
+
+Because `v0.1` is meant to be operational, not metaphysical.
+
+The current kernel is intentionally minimal:
+
+- a small number of classes
+- a small number of required fields
+- explicit hard vs soft gate behavior
+- compatibility with existing `structure_kernel` gates
+
+That lowers rollout risk and makes the kernel easier to test and adopt.
+
+## 4. The Current Technical Shape
+
+### Artifact classes
+
+The schema currently supports:
+
+- `task`
+- `decision`
+- `hypothesis`
+- `experiment`
+- `checkpoint`
+- `policy`
+- `result`
+
+Each class has a minimum required field set in:
+
+- [kernel.schema.json](/Volumes/Code_2TB/code/orp/spec/v1/kernel.schema.json)
+- [cli/orp.py](/Volumes/Code_2TB/code/orp/cli/orp.py)
+
+### CLI operations
+
+The kernel currently exposes:
+
+- `orp kernel scaffold`
+- `orp kernel validate`
+
+### Gate integration
+
+ORP now treats `structure_kernel` as a real validation lane when a gate
+declares a `kernel` block. That gives:
+
+- `soft` mode
+  Validation issues are recorded but do not block the run.
+- `hard` mode
+  Validation issues fail the gate and block promotion.
+
+Legacy `structure_kernel` gates without explicit `kernel` configuration remain
+compatible.
+
+### Bootstrap behavior
+
+`orp init` now seeds a starter task artifact at:
+
+- `analysis/orp.kernel.task.yml`
+
+and the default profile validates it in hard mode.
+
+## 5. Benchmark And Validation Method
+
+The repeatable harness is:
+
+- [scripts/orp-kernel-benchmark.py](/Volumes/Code_2TB/code/orp/scripts/orp-kernel-benchmark.py)
+
+The harness benchmarks and validates:
+
+1. Bootstrap path
+   `orp init` -> starter artifact -> `orp kernel validate` -> `orp gate run`
+2. Roundtrip path
+   `orp kernel scaffold` + `orp kernel validate` for every artifact class
+3. Enforcement path
+   hard mode, soft mode, and legacy compatibility
+
+The benchmark report was generated on:
+
+- commit `5c87faf4fbd54d203cc0ca05683544355c306d55`
+- package version `0.4.6`
+- Python `3.9.6`
+- Node `v24.10.0`
+- `macOS-26.3-arm64-arm-64bit`
+
+## 6. What The Benchmarks Show
+
+### A. Bootstrap ergonomics
+
+Reference run, 5 iterations:
+
+- `orp init` mean: `245.958 ms`
+- starter `orp kernel validate` mean: `165.837 ms`
+- default `orp gate run` mean: `240.768 ms`
+
+Interpretation:
+
+- Kernel bootstrap is comfortably sub-second.
+- The one-shot local developer experience is fast enough to be used in normal
+  repo workflow without feeling heavy.
+- These timings include the real `node -> python CLI` invocation path, which is
+  the correct path to benchmark for npm-installed ORP use.
+
+### B. Roundtrip across all artifact classes
+
+All seven artifact classes successfully scaffolded and validated.
+
+Observed means:
+
+- scaffold mean: `157.864 ms`
+- validate mean: `156.060 ms`
+
+Interpretation:
+
+- The kernel is not only task-shaped.
+- The CLI surface is already general enough for multiple project artifact
+  types.
+
+### C. Enforcement semantics
+
+Reference single-run timings:
+
+- hard mode invalid artifact: `164.938 ms`, `FAIL`
+- soft mode invalid artifact: `163.174 ms`, `PASS` with advisory invalid state
+- legacy compatibility gate: `161.567 ms`, `PASS` without `kernel_validation`
+
+Interpretation:
+
+- hard mode and soft mode are enforced and testable
+- existing `structure_kernel` surfaces do not regress when no explicit kernel
+  config is present
+
+## 7. Claims And Evidence
+
+The benchmark report records five claims, all currently passing:
+
+1. `starter_kernel_bootstrap`
+   ORP seeds a valid starter artifact and a passing default kernel gate.
+2. `typed_artifact_roundtrip`
+   All seven artifact classes scaffold and validate successfully.
+3. `promotion_enforcement_modes`
+   Hard mode blocks invalid artifacts; soft mode records advisory invalidity.
+4. `legacy_structure_kernel_compatibility`
+   Older `structure_kernel` gates remain compatible.
+5. `local_cli_kernel_ergonomics`
+   One-shot kernel operations remain within human-scale local latency
+   thresholds on the reference machine.
+
+These claims are backed by:
+
+- [tests/test_orp_kernel.py](/Volumes/Code_2TB/code/orp/tests/test_orp_kernel.py)
+- [tests/test_orp_init.py](/Volumes/Code_2TB/code/orp/tests/test_orp_init.py)
+- [tests/test_orp_kernel_benchmark.py](/Volumes/Code_2TB/code/orp/tests/test_orp_kernel_benchmark.py)
+- [docs/benchmarks/orp_reasoning_kernel_v0_1_validation.json](/Volumes/Code_2TB/code/orp/docs/benchmarks/orp_reasoning_kernel_v0_1_validation.json)
+
+## 8. Why This Applies To All Project Types
+
+The kernel is not a software-only mechanism. It is a project-structure
+mechanism.
+
+### Software
+
+- feature task
+- architectural decision
+- release policy
+- implementation result
+
+### Research
+
+- hypothesis
+- experiment
+- result
+- checkpoint
+
+### Product and design
+
+- task
+- decision
+- experiment
+- result
+
+### Operations and reliability
+
+- policy
+- checkpoint
+- result
+- task
+
+### Writing and knowledge work
+
+- task
+- decision
+- hypothesis
+- result
+
+The kernel applies because most serious projects need the same underlying
+capabilities:
+
+- define the object of work
+- define boundaries and constraints
+- promote only sufficiently structured truth
+- preserve handoff-quality artifacts
+
+## 9. Limits Of v0.1
+
+The current kernel validates structural sufficiency, not semantic truth.
+
+It can tell us:
+
+- whether required fields are present
+- whether an artifact is typed correctly
+- whether promotion rules are satisfied
+- whether a gate should block or advise
+
+It cannot tell us:
+
+- whether the task is strategically wise
+- whether a hypothesis is scientifically correct
+- whether a result interpretation is deeply valid
+- whether the chosen artifact class was the best possible framing
+
+That is an acceptable `v0.1` limitation. ORP is not trying to ship a truth
+oracle. It is shipping a minimum structure standard for canonical work.
+
+## 10. Bottom Line
+
+The ORP Reasoning Kernel is technically justified because it gives ORP a
+repeatable, inspectable, and enforceable way to turn natural-language project
+intent into typed canonical artifacts.
+
+The current evidence supports that claim:
+
+- it boots cleanly in new repos
+- it works across all current artifact classes
+- it enforces hard vs soft promotion semantics correctly
+- it preserves compatibility with pre-kernel `structure_kernel` gates
+- it stays within human-scale local CLI latency targets
+
+That makes it a good `v0.1` kernel: minimal, general, validated, and already
+useful.

package/docs/ORP_REASONING_KERNEL_V0_1.md

@@ -11,6 +11,10 @@ The ORP Reasoning Kernel is the artifact-shaping grammar that interprets
 intent, validates structure, and governs promotion into canonical repository
 truth.
 
+For the supporting benchmark evidence and alternatives analysis behind this
+design, see
+[docs/ORP_REASONING_KERNEL_TECHNICAL_VALIDATION.md](/Volumes/Code_2TB/code/orp/docs/ORP_REASONING_KERNEL_TECHNICAL_VALIDATION.md).
+
 It should make three things true at once:
 
 - humans can speak naturally at the boundary

package/docs/benchmarks/orp_reasoning_kernel_v0_1_validation.json

@@ -0,0 +1,197 @@
+{
+  "schema_version": "1.0.0",
+  "kind": "orp_reasoning_kernel_validation_report",
+  "metadata": {
+    "generated_at_utc": "2026-03-23T04:42:53Z",
+    "repo_commit": "5c87faf4fbd54d203cc0ca05683544355c306d55",
+    "repo_branch": "main",
+    "package_version": "0.4.7",
+    "python_version": "3.9.6",
+    "node_version": "v24.10.0",
+    "platform": "macOS-26.3-arm64-arm-64bit"
+  },
+  "benchmarks": {
+    "init_starter_kernel": {
+      "iterations": 5,
+      "observed": {
+        "init": {
+          "mean_ms": 245.853,
+          "median_ms": 242.029,
+          "min_ms": 239.454,
+          "max_ms": 257.57
+        },
+        "validate": {
+          "mean_ms": 169.097,
+          "median_ms": 167.938,
+          "min_ms": 165.273,
+          "max_ms": 173.245
+        },
+        "gate_run": {
+          "mean_ms": 242.618,
+          "median_ms": 239.599,
+          "min_ms": 238.174,
+          "max_ms": 252.913
+        }
+      },
+      "targets": {
+        "init_mean_lt_ms": 350.0,
+        "validate_mean_lt_ms": 200.0,
+        "gate_mean_lt_ms": 300.0
+      },
+      "meets_targets": {
+        "init": true,
+        "validate": true,
+        "gate_run": true
+      },
+      "sample_run_records": [
+        "orp/artifacts/run-20260323-044247-956825/RUN.json",
+        "orp/artifacts/run-20260323-044248-621472/RUN.json"
+      ]
+    },
+    "artifact_roundtrip": {
+      "artifact_classes_total": 7,
+      "rows": [
+        {
+          "artifact_class": "task",
+          "scaffold_ms": 162.963,
+          "validate_ms": 161.02
+        },
+        {
+          "artifact_class": "decision",
+          "scaffold_ms": 162.639,
+          "validate_ms": 161.466
+        },
+        {
+          "artifact_class": "hypothesis",
+          "scaffold_ms": 162.337,
+          "validate_ms": 165.228
+        },
+        {
+          "artifact_class": "experiment",
+          "scaffold_ms": 171.011,
+          "validate_ms": 160.825
+        },
+        {
+          "artifact_class": "checkpoint",
+          "scaffold_ms": 161.705,
+          "validate_ms": 163.51
+        },
+        {
+          "artifact_class": "policy",
+          "scaffold_ms": 160.807,
+          "validate_ms": 163.85
+        },
+        {
+          "artifact_class": "result",
+          "scaffold_ms": 163.882,
+          "validate_ms": 162.509
+        }
+      ],
+      "observed": {
+        "scaffold": {
+          "mean_ms": 163.621,
+          "median_ms": 162.639,
+          "min_ms": 160.807,
+          "max_ms": 171.011
+        },
+        "validate": {
+          "mean_ms": 162.63,
+          "median_ms": 162.509,
+          "min_ms": 160.825,
+          "max_ms": 165.228
+        }
+      },
+      "targets": {
+        "scaffold_mean_lt_ms": 200.0,
+        "validate_mean_lt_ms": 200.0
+      },
+      "meets_targets": {
+        "scaffold": true,
+        "validate": true
+      }
+    },
+    "gate_modes": {
+      "hard_mode": {
+        "ms": 174.339,
+        "exit_code": 1,
+        "overall": "FAIL",
+        "kernel_valid": false,
+        "missing_fields": [
+          "constraints",
+          "success_criteria"
+        ]
+      },
+      "soft_mode": {
+        "ms": 173.082,
+        "exit_code": 0,
+        "overall": "PASS",
+        "kernel_valid": false
+      },
+      "legacy_compatibility": {
+        "ms": 172.431,
+        "exit_code": 0,
+        "overall": "PASS",
+        "has_kernel_validation": false
+      },
+      "meets_expectations": {
+        "hard_blocks_invalid_artifact": true,
+        "soft_allows_invalid_artifact_with_advisory": true,
+        "legacy_structure_kernel_remains_compatible": true
+      }
+    }
+  },
+  "claims": [
+    {
+      "id": "starter_kernel_bootstrap",
+      "claim": "orp init seeds a valid starter kernel artifact and a passing default structure_kernel gate.",
+      "status": "pass",
+      "evidence": [
+        "benchmarks.init_starter_kernel",
+        "cli/orp.py",
+        "tests/test_orp_init.py"
+      ]
+    },
+    {
+      "id": "typed_artifact_roundtrip",
+      "claim": "All seven v0.1 artifact classes can be scaffolded and validated through the CLI.",
+      "status": "pass",
+      "evidence": [
+        "benchmarks.artifact_roundtrip",
+        "spec/v1/kernel.schema.json",
+        "tests/test_orp_kernel.py"
+      ]
+    },
+    {
+      "id": "promotion_enforcement_modes",
+      "claim": "Hard mode blocks invalid promotable artifacts, while soft mode records advisory issues without blocking.",
+      "status": "pass",
+      "evidence": [
+        "benchmarks.gate_modes",
+        "tests/test_orp_kernel.py"
+      ]
+    },
+    {
+      "id": "legacy_structure_kernel_compatibility",
+      "claim": "Existing structure_kernel gates without explicit kernel config remain compatible.",
+      "status": "pass",
+      "evidence": [
+        "benchmarks.gate_modes",
+        "cli/orp.py"
+      ]
+    },
+    {
+      "id": "local_cli_kernel_ergonomics",
+      "claim": "One-shot kernel CLI operations remain within human-scale local ergonomics targets on the reference machine.",
+      "status": "pass",
+      "evidence": [
+        "benchmarks.init_starter_kernel",
+        "benchmarks.artifact_roundtrip"
+      ]
+    }
+  ],
+  "summary": {
+    "all_claims_pass": true,
+    "artifact_classes_total": 7,
+    "all_performance_targets_met": true
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "ORP CLI (Open Research Protocol): agent-friendly research workflows, runtime, reports, and pack tooling.",
   "license": "MIT",
   "repository": {

package/scripts/orp-kernel-benchmark.py

@@ -0,0 +1,452 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import platform
+import statistics
+import subprocess
+import sys
+import tempfile
+import time
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+CLI = ["node", "bin/orp.js"]
+ARTIFACT_CLASSES = [
+    "task",
+    "decision",
+    "hypothesis",
+    "experiment",
+    "checkpoint",
+    "policy",
+    "result",
+]
+
+
+def _run(
+    args: list[str],
+    *,
+    cwd: Path = REPO_ROOT,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    proc = subprocess.run(
+        args,
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+    )
+    if check and proc.returncode != 0:
+        raise RuntimeError(
+            f"command failed: {' '.join(args)}\nstdout:\n{proc.stdout}\nstderr:\n{proc.stderr}"
+        )
+    return proc
+
+
+def _run_orp(repo_root: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+    return _run([*CLI, "--repo-root", str(repo_root), *args], check=check)
+
+
+def _timed_orp(repo_root: Path, *args: str, check: bool = True) -> tuple[float, subprocess.CompletedProcess[str]]:
+    started = time.perf_counter()
+    proc = _run_orp(repo_root, *args, check=check)
+    return (time.perf_counter() - started) * 1000.0, proc
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _stats(values: list[float]) -> dict[str, float]:
+    return {
+        "mean_ms": round(statistics.mean(values), 3),
+        "median_ms": round(statistics.median(values), 3),
+        "min_ms": round(min(values), 3),
+        "max_ms": round(max(values), 3),
+    }
+
+
+def _benchmark_init_starter(iterations: int) -> dict[str, Any]:
+    init_times: list[float] = []
+    validate_times: list[float] = []
+    gate_times: list[float] = []
+    run_records: list[str] = []
+
+    for _ in range(iterations):
+        with tempfile.TemporaryDirectory(prefix="orp-kernel-bench-init.") as td:
+            root = Path(td)
+            _run(["git", "init", str(root)])
+            init_ms, init_proc = _timed_orp(root, "init", "--json")
+            init_payload = json.loads(init_proc.stdout)
+            validate_ms, validate_proc = _timed_orp(
+                root, "kernel", "validate", "analysis/orp.kernel.task.yml", "--json"
+            )
+            validate_payload = json.loads(validate_proc.stdout)
+            gate_ms, gate_proc = _timed_orp(root, "gate", "run", "--profile", "default", "--json")
+            gate_payload = json.loads(gate_proc.stdout)
+
+            if not init_payload.get("ok"):
+                raise RuntimeError("orp init benchmark did not report ok=true")
+            if not validate_payload.get("ok"):
+                raise RuntimeError("starter kernel validate benchmark did not report ok=true")
+            if gate_payload.get("overall") != "PASS":
+                raise RuntimeError("starter kernel gate benchmark did not pass")
+
+            init_times.append(init_ms)
+            validate_times.append(validate_ms)
+            gate_times.append(gate_ms)
+            run_records.append(gate_payload["run_record"])
+
+    targets = {
+        "init_mean_lt_ms": 350.0,
+        "validate_mean_lt_ms": 200.0,
+        "gate_mean_lt_ms": 300.0,
+    }
+    observed = {
+        "init": _stats(init_times),
+        "validate": _stats(validate_times),
+        "gate_run": _stats(gate_times),
+    }
+    return {
+        "iterations": iterations,
+        "observed": observed,
+        "targets": targets,
+        "meets_targets": {
+            "init": observed["init"]["mean_ms"] < targets["init_mean_lt_ms"],
+            "validate": observed["validate"]["mean_ms"] < targets["validate_mean_lt_ms"],
+            "gate_run": observed["gate_run"]["mean_ms"] < targets["gate_mean_lt_ms"],
+        },
+        "sample_run_records": run_records[:2],
+    }
+
+
+def _benchmark_artifact_roundtrip() -> dict[str, Any]:
+    rows: list[dict[str, Any]] = []
+    scaffold_times: list[float] = []
+    validate_times: list[float] = []
+
+    for artifact_class in ARTIFACT_CLASSES:
+        with tempfile.TemporaryDirectory(prefix=f"orp-kernel-bench-{artifact_class}.") as td:
+            root = Path(td)
+            path = f"analysis/{artifact_class}.kernel.yml"
+            scaffold_ms, scaffold_proc = _timed_orp(
+                root,
+                "kernel",
+                "scaffold",
+                "--artifact-class",
+                artifact_class,
+                "--out",
+                path,
+                "--name",
+                f"{artifact_class} benchmark",
+                "--json",
+            )
+            validate_ms, validate_proc = _timed_orp(root, "kernel", "validate", path, "--json")
+            scaffold_payload = json.loads(scaffold_proc.stdout)
+            validate_payload = json.loads(validate_proc.stdout)
+            if not scaffold_payload.get("ok") or not validate_payload.get("ok"):
+                raise RuntimeError(f"roundtrip benchmark failed for artifact_class={artifact_class}")
+            scaffold_times.append(scaffold_ms)
+            validate_times.append(validate_ms)
+            rows.append(
+                {
+                    "artifact_class": artifact_class,
+                    "scaffold_ms": round(scaffold_ms, 3),
+                    "validate_ms": round(validate_ms, 3),
+                }
+            )
+
+    observed = {
+        "scaffold": _stats(scaffold_times),
+        "validate": _stats(validate_times),
+    }
+    targets = {
+        "scaffold_mean_lt_ms": 200.0,
+        "validate_mean_lt_ms": 200.0,
+    }
+    return {
+        "artifact_classes_total": len(rows),
+        "rows": rows,
+        "observed": observed,
+        "targets": targets,
+        "meets_targets": {
+            "scaffold": observed["scaffold"]["mean_ms"] < targets["scaffold_mean_lt_ms"],
+            "validate": observed["validate"]["mean_ms"] < targets["validate_mean_lt_ms"],
+        },
+    }
+
+
+def _benchmark_gate_modes() -> dict[str, Any]:
+    with tempfile.TemporaryDirectory(prefix="orp-kernel-bench-gates.") as td:
+        root = Path(td)
+        _write_json(
+            root / "analysis" / "invalid-task.kernel.json",
+            {
+                "schema_version": "1.0.0",
+                "artifact_class": "task",
+                "object": "terminal trace widget",
+                "goal": "surface lane state and drift",
+                "boundary": "terminal-first workflow",
+            },
+        )
+        _write_json(
+            root / "orp.kernel.bench.json",
+            {
+                "profiles": {
+                    "hard": {
+                        "description": "hard kernel gate",
+                        "mode": "test",
+                        "packet_kind": "problem_scope",
+                        "gate_ids": ["kernel_hard"],
+                    },
+                    "soft": {
+                        "description": "soft kernel gate",
+                        "mode": "test",
+                        "packet_kind": "problem_scope",
+                        "gate_ids": ["kernel_soft"],
+                    },
+                    "legacy": {
+                        "description": "legacy structure kernel gate",
+                        "mode": "test",
+                        "packet_kind": "problem_scope",
+                        "gate_ids": ["kernel_legacy"],
+                    },
+                },
+                "gates": [
+                    {
+                        "id": "kernel_hard",
+                        "phase": "structure_kernel",
+                        "command": "true",
+                        "pass": {"exit_codes": [0]},
+                        "kernel": {
+                            "mode": "hard",
+                            "artifacts": [
+                                {
+                                    "path": "analysis/invalid-task.kernel.json",
+                                    "artifact_class": "task",
+                                }
+                            ],
+                        },
+                    },
+                    {
+                        "id": "kernel_soft",
+                        "phase": "structure_kernel",
+                        "command": "true",
+                        "pass": {"exit_codes": [0]},
+                        "kernel": {
+                            "mode": "soft",
+                            "artifacts": [
+                                {
+                                    "path": "analysis/invalid-task.kernel.json",
+                                    "artifact_class": "task",
+                                }
+                            ],
+                        },
+                    },
+                    {
+                        "id": "kernel_legacy",
+                        "phase": "structure_kernel",
+                        "command": "true",
+                        "pass": {"exit_codes": [0]},
+                    },
+                ],
+            },
+        )
+
+        hard_ms, hard_proc = _timed_orp(
+            root,
+            "--config",
+            "orp.kernel.bench.json",
+            "gate",
+            "run",
+            "--profile",
+            "hard",
+            "--json",
+            check=False,
+        )
+        soft_ms, soft_proc = _timed_orp(
+            root,
+            "--config",
+            "orp.kernel.bench.json",
+            "gate",
+            "run",
+            "--profile",
+            "soft",
+            "--json",
+        )
+        legacy_ms, legacy_proc = _timed_orp(
+            root,
+            "--config",
+            "orp.kernel.bench.json",
+            "gate",
+            "run",
+            "--profile",
+            "legacy",
+            "--json",
+        )
+
+        hard_payload = json.loads(hard_proc.stdout)
+        soft_payload = json.loads(soft_proc.stdout)
+        legacy_payload = json.loads(legacy_proc.stdout)
+
+        hard_result = json.loads((root / hard_payload["run_record"]).read_text(encoding="utf-8"))["results"][0]
+        soft_result = json.loads((root / soft_payload["run_record"]).read_text(encoding="utf-8"))["results"][0]
+        legacy_result = json.loads((root / legacy_payload["run_record"]).read_text(encoding="utf-8"))["results"][0]
+
+        return {
+            "hard_mode": {
+                "ms": round(hard_ms, 3),
+                "exit_code": hard_proc.returncode,
+                "overall": hard_payload["overall"],
+                "kernel_valid": hard_result["kernel_validation"]["valid"],
+                "missing_fields": hard_result["kernel_validation"]["artifacts"][0]["missing_fields"],
+            },
+            "soft_mode": {
+                "ms": round(soft_ms, 3),
+                "exit_code": soft_proc.returncode,
+                "overall": soft_payload["overall"],
+                "kernel_valid": soft_result["kernel_validation"]["valid"],
+            },
+            "legacy_compatibility": {
+                "ms": round(legacy_ms, 3),
+                "exit_code": legacy_proc.returncode,
+                "overall": legacy_payload["overall"],
+                "has_kernel_validation": "kernel_validation" in legacy_result,
+            },
+            "meets_expectations": {
+                "hard_blocks_invalid_artifact": hard_proc.returncode == 1
+                and hard_payload["overall"] == "FAIL"
+                and hard_result["kernel_validation"]["valid"] is False,
+                "soft_allows_invalid_artifact_with_advisory": soft_proc.returncode == 0
+                and soft_payload["overall"] == "PASS"
+                and soft_result["kernel_validation"]["valid"] is False,
+                "legacy_structure_kernel_remains_compatible": legacy_proc.returncode == 0
+                and legacy_payload["overall"] == "PASS"
+                and "kernel_validation" not in legacy_result,
+            },
+        }
+
+
+def _gather_metadata() -> dict[str, Any]:
+    package_version = json.loads((REPO_ROOT / "package.json").read_text(encoding="utf-8"))["version"]
+    commit = _run(["git", "rev-parse", "HEAD"]).stdout.strip()
+    branch = _run(["git", "rev-parse", "--abbrev-ref", "HEAD"]).stdout.strip()
+    node_version = _run(["node", "--version"]).stdout.strip()
+    return {
+        "generated_at_utc": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "repo_commit": commit,
+        "repo_branch": branch,
+        "package_version": package_version,
+        "python_version": sys.version.split()[0],
+        "node_version": node_version,
+        "platform": platform.platform(),
+    }
+
+
+def build_report(iterations: int) -> dict[str, Any]:
+    init_benchmark = _benchmark_init_starter(iterations)
+    roundtrip_benchmark = _benchmark_artifact_roundtrip()
+    gate_mode_benchmark = _benchmark_gate_modes()
+
+    claims = [
+        {
+            "id": "starter_kernel_bootstrap",
+            "claim": "orp init seeds a valid starter kernel artifact and a passing default structure_kernel gate.",
+            "status": "pass",
+            "evidence": [
+                "benchmarks.init_starter_kernel",
+                "cli/orp.py",
+                "tests/test_orp_init.py",
+            ],
+        },
+        {
+            "id": "typed_artifact_roundtrip",
+            "claim": "All seven v0.1 artifact classes can be scaffolded and validated through the CLI.",
+            "status": "pass" if roundtrip_benchmark["artifact_classes_total"] == 7 else "fail",
+            "evidence": [
+                "benchmarks.artifact_roundtrip",
+                "spec/v1/kernel.schema.json",
+                "tests/test_orp_kernel.py",
+            ],
+        },
+        {
+            "id": "promotion_enforcement_modes",
+            "claim": "Hard mode blocks invalid promotable artifacts, while soft mode records advisory issues without blocking.",
+            "status": "pass"
+            if gate_mode_benchmark["meets_expectations"]["hard_blocks_invalid_artifact"]
+            and gate_mode_benchmark["meets_expectations"]["soft_allows_invalid_artifact_with_advisory"]
+            else "fail",
+            "evidence": [
+                "benchmarks.gate_modes",
+                "tests/test_orp_kernel.py",
+            ],
+        },
+        {
+            "id": "legacy_structure_kernel_compatibility",
+            "claim": "Existing structure_kernel gates without explicit kernel config remain compatible.",
+            "status": "pass"
+            if gate_mode_benchmark["meets_expectations"]["legacy_structure_kernel_remains_compatible"]
+            else "fail",
+            "evidence": [
+                "benchmarks.gate_modes",
+                "cli/orp.py",
+            ],
+        },
+        {
+            "id": "local_cli_kernel_ergonomics",
+            "claim": "One-shot kernel CLI operations remain within human-scale local ergonomics targets on the reference machine.",
+            "status": "pass"
+            if all(init_benchmark["meets_targets"].values())
+            and all(roundtrip_benchmark["meets_targets"].values())
+            else "fail",
+            "evidence": [
+                "benchmarks.init_starter_kernel",
+                "benchmarks.artifact_roundtrip",
+            ],
+        },
+    ]
+
+    return {
+        "schema_version": "1.0.0",
+        "kind": "orp_reasoning_kernel_validation_report",
+        "metadata": _gather_metadata(),
+        "benchmarks": {
+            "init_starter_kernel": init_benchmark,
+            "artifact_roundtrip": roundtrip_benchmark,
+            "gate_modes": gate_mode_benchmark,
+        },
+        "claims": claims,
+        "summary": {
+            "all_claims_pass": all(row["status"] == "pass" for row in claims),
+            "artifact_classes_total": roundtrip_benchmark["artifact_classes_total"],
+            "all_performance_targets_met": all(init_benchmark["meets_targets"].values())
+            and all(roundtrip_benchmark["meets_targets"].values()),
+        },
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Benchmark and validate ORP Reasoning Kernel v0.1")
+    parser.add_argument("--out", default="", help="Optional JSON output path")
+    parser.add_argument("--iterations", type=int, default=5, help="Iterations for bootstrap benchmark")
+    parser.add_argument("--quick", action="store_true", help="Use a single bootstrap iteration for fast checks")
+    args = parser.parse_args()
+
+    iterations = 1 if args.quick else max(1, args.iterations)
+    report = build_report(iterations)
+    payload = json.dumps(report, indent=2) + "\n"
+    if args.out:
+        out_path = Path(args.out)
+        if not out_path.is_absolute():
+            out_path = REPO_ROOT / out_path
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(payload, encoding="utf-8")
+    print(payload, end="")
+    return 0 if report["summary"]["all_claims_pass"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())