Bound the work. Preserve the trail.

Part I / The problem

A capable model can propose work without proving that the work is complete, safe to repeat, or authorized to affect an external system. Trailforge addresses the control layer around that intelligence: admit a finite goal, bound each task, preserve evidence, and keep uncertain outcomes visible.

The application host owns identity, product policy, model selection, real provider limits, and acceptance criteria. The harness records what was admitted and observed; it does not turn a model's confidence into permission. The public package is an MIT alpha, v0.1.0a1, with a standard-library-only base runtime and Python 3.11 or later.

Part II / Architecture

The neutral Harness executes typed Goal and Task records under SQLite authority. Develop is a profile layered on this kernel. A separate OfflineController runs a fixed Review demonstration using fixtures and mock output; its protocol and database integrations must not be confused with generic execution.

LangGraph can schedule a kernel advance, but SQLite remains the neutral resume authority. The PostgreSQL, outbox, and broker adapters belong to the legacy Review/controller path. They are not a generic distributed PostgreSQL backend for the neutral Harness.

Part II / Architecture

A Goal binds tenant, resource, objective, ordered tasks, required checks, allowed effects, and limits. Tasks identify a registered adapter, bounded input, and dependencies on earlier tasks. Between 1 and 128 unique tasks are admitted in topological order; at least one required check must reference a VERIFY adapter.

PURE, SCOPED_READ, and explicitly admitted CANDIDATE_WRITE effects are supported by the neutral plan. EXTERNAL_WRITE is denied there and belongs at a separate publisher boundary. Adapter kinds are integration roles, not operating-system privileges.

Part III / Execution

Start records a READY run. Before each synchronous callback, the kernel reserves declared units and persists the attempt with an active lease. It passes detached JSON observations, validates the returned value, and records a digest-bound result receipt before proceeding.

Completed task outputs are reused after reconstructing the host. Resume requires the same goal, adapter metadata, scope, and store; changed bindings are rejected. A pause after a task records its result without granting approval. Tasks execute sequentially within one run, not concurrently.

Part III / Execution

Exceptions, invalid or oversized output, and expired active attempts retain uncertainty rather than masquerading as success. UNKNOWN holds the run. A trusted host explicitly resolves the affected task with RETRY or CANCEL; retry does not reset the consumed attempts or units.

A lease can reject a late commit; it cannot interrupt synchronous Python or undo a provider call. Cancellation likewise revokes commitment without promising remote cancellation. Hosts need actual provider timeouts, spend policies, and idempotency where those services support them.

Part III / Execution

SQLite stores a canonical run payload, binding digest, state version, and checksum. The latest journal sequence and state digest must agree with that checkpoint when it is loaded. Compare-and-swap updates reject a stale state version or changed binding.

Neutral task admission uses BEGIN IMMEDIATE to reserve tenant/global units and commit the new checkpoint and journal event atomically. Reconstructing a host does not reset its ledger, and configured caps cannot be silently changed. Separate database files are separate authorities.

Part IV / Profiles & evidence

Develop declares one to three six-phase rounds before admission: PLAN, RESEARCH, BUILD, DEBUG, VERIFY, HEALTH. Five phases are host adapters; HEALTH is built in. Only BUILD receives CANDIDATE_WRITE. Other phases may be pure or scoped reads, and protected criteria live outside the candidate tree.

CandidateWorkspace admits an explicit list of 1–128 canonical paths, rejects case aliases and linked-file variants, bounds file bytes, and replaces writes atomically through a temporary file. Pre/post tree checks detect unauthorized candidate changes and altered protected checks.

VERIFY binds host evidence to the candidate, check tree, round, and goal. HEALTH checks candidate continuity. The final round's verification and health are required for completion, and a handoff is rejected if the candidate or checks change afterward.

Part IV / Profiles & evidence

The fixed Offline Review path captures scoped, revision-bound source bytes and validates findings against exact paths, one-based line ranges, preserved quotes, and receipts. Its security, correctness, tests, and documentation roles are configured outputs of one mock callback, not four built-in live agents.

Unsupported files, truncation, malformed findings, and timeouts leave coverage gaps. A draft always needs human review; the critic is not implemented and reliability is unset. COMPLETE means the configured workflow's coverage is complete, not that every reported issue is a real defect.

LocalArtifactStore provides bounded, content-addressed bytes with scope and integrity receipts. LocalRetrieval performs revision-bound, case-insensitive EXACT_LITERAL matching over allowlisted files. It returns matching files in sorted order—not semantic rankings or vector chunks—and marks them as untrusted source data.

Part V / Integration boundaries

GuardedPublisher binds an intent to tenant, resource, goal and policy digests, revision, action, payload, adapter, and execution mode. A live host guard authorizes approval, execution, revocation, and reconciliation. Approval expiry defaults to 300 seconds and cannot be treated as lasting authority.

Before dispatch, approval consumption and a stable SENDING operation are persisted. A valid bound acknowledgement yields ACCEPTED. A lost response or invalid acknowledgement yields UNKNOWN. Replaying the same intent observes the stored operation; reconciliation only calls inspect, never blindly executes it again.

Part V / Integration boundaries

Docker execution receipts bind command, image, candidate/check trees, goal, and output. They default to an UNKNOWN criterion verdict: exit code zero alone cannot establish semantic acceptance. A trusted verifier must interpret that execution evidence against the original requirement.

Telemetry deliberately excludes arbitrary prompts, source text, tokens, and actor/provider fields. Hosts can monitor held attempts, budget denial, stale leases, ambiguous publication, dispatch exhaustion, and cleanup failures while keeping full authority records out of routine operational logs.

Part VI / Evidence & adoption

The v0.1.0a1 guide records installed-package conformance coverage for the alpha release. These are documented release results, not new test runs performed by this portfolio and not measurements of real-provider answer quality.

A separate evaluation would need representative data, independently protected acceptance, diagnostic correctness, cost, latency, and unsafe-action measurements. A repository-owned workflow and test suite cannot substitute for independently administered review.

Part VI / Evidence & adoption

• Pin the release and required extras; keep authority stores and credentials private.
• Define exact tenant/resource identity, finite tasks, explicit effects, and meaningful protected checks.
• Version material adapter/model/prompt choices; enforce real provider timeouts and cost limits separately.
• Make UNKNOWN, exhausted budgets, and cancellation visible to an operator.
• Use a tested Linux runner for untrusted commands; trusted callbacks are not an operating-system isolation boundary.
• Integrate real publishers only with current identity, policy, revision checks and tested inspect/reconciliation behavior.

Potential extensions include a general distributed-authority adapter, richer retrieval, additional product profiles, calibrated model evaluations, and independent acceptance infrastructure. They are roadmap directions—not shipped capabilities of this alpha.