docs: give every package a front door

Eight packages, no package documentation, so pkg.go.dev would have shown
an adopter a list of symbols and nothing else. Each package now says what
it is for and what assumption it was built under, which is the part a
reader cannot recover by reading signatures.

These are package documents, not comments in the code. The style rule
holds: names still carry the meaning inside a function, and nothing was
annotated line by line.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: eastriverlee

agentcontract/doc.go

@@ -0,0 +1,18 @@
+// Package agentcontract is the contract a host and a harness compile against.
+//
+// The port is one method:
+//
+//	type Harness interface {
+//		RunTurn(context.Context, AgentTurnRequest) (AgentTurnResult, error)
+//	}
+//
+// It used to be nine. Routing, addressing, follow-up classification and one-shot
+// replies were verbs on the port until it became clear they are host policy
+// rather than harness behaviour, so a harness that implements only RunTurn is
+// complete.
+//
+// AgentTurnRequest is how a host tells the harness everything the harness
+// refuses to assume: who is asking, what identity the agent answers to, where
+// the workspace is, which instructions and skills apply, and what the company
+// is. AgentTurnResult carries the answer back with the task state it reached.
+package agentcontract

agentcontract/harnesstest/doc.go

@@ -0,0 +1,5 @@
+// Package harnesstest is a harness that records what it was asked to do.
+//
+// It lets a host's tests assert on the turn request it built without running a
+// model.
+package harnesstest

doc.go

@@ -0,0 +1,21 @@
+// Package bluecollar is an agent harness: the loop that takes a request,
+// decides what to do, calls tools, and answers.
+//
+// It is built for work nobody is watching. A request arrives from someone else,
+// the person who sent it goes back to their day, and the answer has to be right
+// without anyone checking. That assumption is why the loop carries an outcome
+// contract agreed before the work starts, a completion gate that will not accept
+// the model's own word that it is done, approval as a state a task can sit in
+// for days and resume from, a tier ladder that picks the model from the
+// difficulty, and failure text written for the person who asked.
+//
+// The harness owns no tools, no identity, and no storage. A host hands it a
+// tool set and a task store and calls RunTurn; every tool call executes back in
+// the host, as whoever asked for the work. See [agentcontract] for the port both
+// sides compile against.
+//
+// The harness has no identity or filesystem layout of its own either. The host
+// supplies AgentIdentity, the workspace paths, the instruction bundle and the
+// company context; given none of them, the agent is "the assistant" and knows
+// nothing about where it runs.
+package bluecollar

intake/doc.go

@@ -0,0 +1,11 @@
+// Package intake decides what an inbound message means before anything runs.
+//
+// A turn router chooses whether a message becomes a task, a quick reply, or
+// nothing at all. A classifier answers the two questions a chat platform forces:
+// whether a message in a busy channel is addressed to the agent, and whether it
+// continues a task already running.
+//
+// These are host policy rather than harness behaviour — a host that answers its
+// own messenger may bring its own — which is why they live beside the loop
+// instead of on the harness port.
+package intake

model/doc.go

@@ -0,0 +1,9 @@
+// Package model is the port a language model reaches the harness through.
+//
+// LanguageModelProvider is deliberately small: generate a response, or generate
+// one constrained to a schema. Anything satisfying it works, and the provider
+// may change between steps of a running turn — the tier ladder relies on that,
+// escalating a task from a cheap model to a strong one without restarting it.
+//
+// There is no provider implementation here. The host brings one.
+package model

taskstate/doc.go

@@ -0,0 +1,12 @@
+// Package taskstate is the durable record of work.
+//
+// A TaskRun is one unit of work with one of nine statuses, and its event ledger
+// is the append-only sequence of everything that happened to it. Event names
+// follow a fixed grammar — tool.<name>.requested, tool.<name>.result,
+// approval.pending_call, approval.executed — so a reader can reconstruct a run
+// without access to any harness's internal types.
+//
+// The ledger is what makes a task survive its process. A run is resumed by
+// re-driving a turn from what the ledger says, never by attaching to a live one,
+// which is why a task can wait days for an approval and continue afterwards.
+package taskstate

toolcontract/doc.go

@@ -0,0 +1,12 @@
+// Package toolcontract describes tools to a harness and carries their results
+// back.
+//
+// A ToolDescriptor says what a tool is called, what it accepts, and — through
+// ApprovalScope and SideEffectClass — what kind of effect running it has. Those
+// two fields are how a host decides which calls need a person's approval, so
+// that the decision comes from what a tool does rather than from what it is
+// named.
+//
+// ToolSet is the set of tools a particular requester may call this turn. The
+// harness chooses from it; the host executes.
+package toolcontract

turnstream/doc.go

@@ -0,0 +1,6 @@
+// Package turnstream mirrors a turn as it happens, for a caller that wants to
+// watch rather than wait.
+//
+// It is a view, not a control surface: the turn runs the same whether or not
+// anyone is reading.
+package turnstream