REACH + OCTO

Appearance

What is TRACE? ​

TRACE — Timestamped Record of Agentic Chain Execution.

Timestamp. Record. Append. Compose. Execute.

REACH produces findings. OCTO surfaces decisions. Neither remembers what it did. TRACE is the memory layer — a flat, append-only NDJSON file written alongside your .reach and .octo files. Every event in every run appends one line. Claude reads those lines on demand and can reconstruct, visualize, query, or audit any run without re-executing it.

No database. No dashboard. No always-on process. Just a file and a reader.

Where TRACE Fits ​

REACH    →  reaches into systems, surfaces findings
             writes to TRACE as a side effect

OCTO     →  coordinates arms, generates decision surface
             writes to TRACE as a side effect

TRACE    →  records everything that happened, immutably
             read by Claude through the MCP server

MCP      →  lets Claude read, write, execute, and author
             the only interface to the TRACE file

Each does one thing. None requires the others to exist. Together they compose into a fully auditable, zero-infrastructure workflow practice.

The File ​

reach-trace.ndjson

One JSON object per line. Append-only. Never modified after writing. Lives alongside your .reach and .octo files — or in a .trace/ subfolder for per-run isolation.

Every line is a TRACE event:

json
{
  "trace_id":   "uuid-v4",
  "run_id":     "uuid-v4",
  "timestamp":  "2026-06-16T08:45:01Z",
  "event_type": "ARM_COMPLETE",
  "source":     "morning.octo",
  "payload":    {
    "arm_name":        "git.commits",
    "duration_ms":     980,
    "exit_code":       0,
    "finding_summary": "2 commits yesterday, on track"
  }
}

run_id groups all events from a single REACH or OCTO execution. trace_id identifies the individual event. Together they make any run reconstructable from the file alone.

The Most Important Convention ​

Write at the moment of occurrence, not at completion.

✓  write ARM_START → run script → write ARM_COMPLETE or ARM_FAIL
✗  run script → write ARM_START and ARM_COMPLETE together on success

A script that crashes between ARM_START and ARM_COMPLETE leaves a detectable open event — an arm that started and never closed. That is useful signal. A script that writes both events only on success leaves a silent gap. Silent gaps are invisible and therefore dangerous.

What TRACE Does Not Do ​

  • No dashboard. Visualization happens on demand through Claude. Nothing persists on screen.
  • No schema enforcement. The event schema is a convention, not a validator. A malformed line is skipped, not fatal.
  • No event modification. Append-only is not a preference — it is the design. A TRACE file that has been modified is not a TRACE file.
  • No always-on process. The MCP server runs when you need it. The trace file exists when you don't.

File Conventions ​

Single shared file (default) ​

project/
  morning.octo
  sprint-review.reach
  reach-trace.ndjson        ← all runs, all time

Good for personal workflow. Simple. Rotate by month or size as needed.

Per-run isolation ​

project/
  morning.octo
  .trace/
    r1-morning-2026-06-16.ndjson
    r2-sprint-2026-06-16.ndjson

Good for audit scenarios. Each file is self-contained and independently verifiable.

Next ​

GitHub: semanticintent/trace · DOI: 10.5281/zenodo.20739404