Trail by GraycodeAI

Every outcome has a path.

Trail is an independent product by GraycodeAI for coordinating people, agents, services, repositories, and independently administered organizations. Its hosted product surface is intended for trail.graycodeai.com. It coordinates outcomes through explicit commitments, scoped authority, evidence, and selective federation.

This directory contains the research and planning baseline plus a bounded Phase 1 executable domain experiment. The experiment validates protocol semantics in memory; it is not product infrastructure. Phase 0 field validation remains open.

Product thesis

Trail is not a decentralized clone of Jira, Linear, Asana, Monday, ClickUp, or GraphDone. Tasks, boards, lists, timelines, and graphs are useful views. The stable product model is:

situation -> desired outcome -> request/offer -> commitment
          -> authorized execution -> evidence -> review -> acceptance

The human-to-agent ratio is measured, never configured as a product constant. A workflow may be 10/90, 80/20, 90/10, or change at each transition. Policy, risk, authority, confidence, capability, and available attention decide who may act.

Document map

Planning

• Research plan
• Product requirements
• Edge case catalog
• Phased roadmap
• Pre-build gate
• Problem interview guide
• Public interview candidate shortlist
• Design-partner brief
• Concierge prototype specification
• Pilot scorecard
• Risk register
• Open questions and experiments

Architecture

• System architecture
• Domain model
• Distributed systems model
• Security and threat model

Protocol and decisions

• Trail Protocol v0 draft
• Protocol v0 JSON Schema
• Protocol v0 executable fixtures
• Architecture decisions

Research

• Research index and method
• Open source landscape
• Market, OSS, and startup signals
• Industry standards and readiness
• Research literature
• Protocols and standards
• GraycodeAI integration audit
• Field evidence ledger
• Initial research archive

Current decisions

1. The product is Trail, endorsed publicly as Trail by GraycodeAI.
2. Trail owns outcome and commitment coordination. It does not own model routing, coding-agent interaction, Git hosting, worktree execution, or raw engineering memory.
3. The core is a typed temporal coordination model with a signed event journal and rebuildable projections.
4. Local-first behavior applies where operations merge safely. Scarce, revocable, or exclusive rights coordinate at the owning authority.
5. Federation is selective exchange between trust domains. There is no global database, token, blockchain, or universal consensus requirement.
6. Agents are principals with bounded capabilities. Natural-language output alone never authorizes a side effect or proves completion.
7. Product work is proposed to begin as a modular monolith and protocol package. Federation and service extraction follow evidence from a working local kernel.
8. Trail is independently deployable and self-hostable. Graycode Platform integration is optional and occurs through versioned HTTP APIs; there is no shared database or required Platform runtime.

Executable reference model

ADR 0006 authorizes a dependency-free Go kernel and deterministic simulator under a narrow Phase 1 boundary. It currently exercises explicit commitment formation, scoped grants, leases and fencing, bounded runs, independent evidence, exact-version acceptance, idempotency, policy decisions, event replay, JSON Schema, and portable conformance fixtures. The canonical lifecycle enters through the public JSON command envelope and must reproduce the checked-in 11-event journal byte for byte.

make check
make simulate
go run ./cmd/trail-sim -mode scenario

See the implementation status for covered requirements and remaining gates.

Planning gates

Production implementation starts only after these artifacts are reviewed together:

• named pilot scenarios and users;
• protocol vocabulary and lifecycle invariants;
• authority, privacy, and federation boundaries;
• adversarial edge cases and threat mitigations;
• measurable phase exit criteria;
• explicit decisions for storage, runtime, and licensing.

The in-memory experiment does not satisfy these field, operational, or product gates.

Status vocabulary

Documents use these labels:

• Observed: verified in a repository, specification, paper, or product source.
• Inferred: a conclusion drawn from multiple observations.
• Proposed: a Trail design choice that still needs validation.
• Decided: an accepted project decision recorded in an ADR.
• Open: unresolved and attached to an experiment or decision gate.