Crate speccoder_core 

Pure domain types of speccoder.

This crate has no IO and no async: its state machines, task graph and verdict rules stay property-testable without a runtime. The layering test in the speccoder crate keeps its dependency closure free of IO and async crates.

Modules

acceptance

Acceptance tests decided before the run: one record for every producer — a review that froze the oracle and a bug’s confirmed reproduction. The fix’s checkpoint reuses the record instead of calling the acceptance author; a change of the wording it was decided on lapses it.

actions

What a person can do now: one list, computed by the runtime and rendered by every interface — the dashboard’s n, c and : today, a desktop app or another workbench later. Every action is a CLI command too, so nothing an interface offers is out of reach of a script.

bug

Bug fixes, the L2 rung: a person’s triad — what happens (Current), what should (Expected), what must stay as it is (Unchanged) — one reproduction per Expected statement that fails on the untouched code by an assertion, shown to the person once and then frozen, and a fix judged like any task plus three bug rules: every reproduction goes from red to green, the pass-to-pass set stays green, and undoing the fix (the revert) is rejected by at least one reproduction.

codes

Stable codes for every result that is not plainly ok: what went wrong, why it matters, how to fix it and where it is documented. A script branches on the code, a person reads the fix.

collection

Which test files a run actually collected: a test that never ran is evidence of nothing.

context

What reached a model call (constitution VIII): one manifest of every part handed to it — its kind, where it came from, its digest and size — journaled with the call and named in the evidence. Producers add entries through the runtime’s one builder; nothing hashes or labels context itself.

event

The names of --events lines: one closed list. A line whose type is not here is never emitted; a new name is lowercase noun.verb. Domain events (a record backs them) publish a projection schema; progress events are stream-only.

evidence

A task’s evidence, as rows every interface renders.

graph

Task dependencies from what tasks.md documents, and which tasks are ready.

inbox

The kinds of Needs You items: one registry, each kind with its group and urgency rank. A feature adds a kind here, never a free string; the runtime’s list is derived from it.

ladder

The ladder: where a unit of work came from. One provenance record per subject, written once. This build knows the variants a bug writes; later rungs add theirs as variants.

lane

Who does a task: the implementer (code), the plan’s author (planning: design documents inside the unit’s directory) or a person (yours). Derived, never stored — from the task’s line, the unit’s directory, the format’s judged files and an honest stop.

new_project

A new project’s plan: the exact commands that make an empty folder (or a clean repository) a project speccoder can judge — the stack’s own scaffold, the spec format’s own init, speccoder init --yes and one commit as the person — with what each touches, whether it reaches the network, and the folder as it was seen. The person confirms this plan; the runtime runs exactly it, bound to its digest.

next

What to do next after a stop or a finish: a closed set of outcomes and, for each, the commands that continue — deterministic, never model text. The human Next: block, the TUI footer and data.next are all this list.

oracle

The oracle at review: per requirement, the visible acceptance tests the run would use — written on the person’s request, red-checked on the current tree, shaped by the person and frozen with the approval — and the review comments anchored to what the person reads. These are the shapes every interface shows; none of them has a field that could hold a held-out test’s path or content.

predicate

The task-verification predicate (https://speccoder.dev/task-verification/v0) as one typed body: what speccoder signs about a ticked task, and what a verifier reads back. Published as an open specification, its schema generated from this type.

regression

Why a tick is regression-only: one reason from a closed set, decided by code from the run’s facts, worded once, and carried in the commit’s Regression-Only: trailer and its signed statement.

retry

Retries: the verifier’s failure digest for the next attempt, and the fingerprint that stops retries which cannot help.

scope

Task scope as a reported finding: which changed paths a task’s line did not name. Never a gate — a task line is prose, and a list of paths in it is a hint, not a contract.

shape

Shape: what a writing assistant changed in a person’s words, decided by code. The model proposes a requirement; this module computes which words of the proposal are the person’s and which were added, which of the person’s words were dropped, which sentences landed nowhere, which added numbers and terms no assumption explains, and what in the text makes it hard to test. Nothing here asks the model or believes it.

similar

Is a new feature’s description close to a requirement the project already has? A deterministic text similarity — normalised tokens, a fixed stop-word list, a suffix stemmer, TF-IDF weights over the project’s requirements and cosine — so the answer is the same on every run and explains itself by the terms it shares. A hint: it never blocks, and no model produces or suppresses a match.

snapshot

What speccoder sees in a Spec Kit project: the read-only snapshot that inspect reports and every later subsystem consumes.

spec

The format-neutral view of spec-driven work: which format a project is written in, and the requirements and acceptance scenarios a unit of work states. The Spec Kit and OpenSpec adapters produce it; the judge reads only it.

stage

The fixed stages of one task’s pipeline: one vocabulary for the plain progress lines, the TUI, ACP updates and status.

step

How a fix line or a next step is taken from an interface: speccoder performs it, opens a view, runs the person’s own command, or it belongs in the person’s shell. One parser (step_of) for every line speccoder prints, so no interface copies a command speccoder can take itself.

strength

Acceptance strength: how well a task’s acceptance set tells right from wrong.

tour

The evidence tour: one task’s evidence as six steps in a fixed order — requirement, frozen tests, red, diff, green, strength — each saying where it comes from. The payload evidence_tour, and its Markdown (the check run, the pull-request body); the app renders the same JSON.

verify

The judge’s vocabulary: check results, baseline comparison, and verdicts .

verify_branch

A branch’s ticks and what their evidence comes to: the payload of speccoder attest verify --branch (and attest badge) (branch_verify), the rule that turns per-tick outcomes into the branch’s conclusion, and the badge.

words

Lists in a sentence.

workflow

GitHub Actions workflow commands (::error file=…,line=…::…): their escaping and the limits a step has, shared by speccoder’s report annotations and attest verify --branch’s fallback when it cannot publish its check.

Structs

ActionsReport

Result of speccoder actions: what a person can do now in the project — the list every interface renders — and where the feature is on its journey.

AgentAttempt

An external agent’s attempt, as the report keeps it.

AgentCard

One agent that can make attempts, and how ready it is: installed, signed in, asking before it acts — each with its one action.

AgentPlanStep

One step of an external agent’s plan.

AgentTick

One tick of an AgentCard. Serialised with fix_steps.

ApprovalView

A pending call as a person sees it: what, why, what it can reach, what the model claimed, and what approving it grants.

ApprovalsReport

Result of speccoder report --approvals, approve and reject.

ArchiveReport

Result of speccoder spec archive (an OpenSpec change).

AttestReport

Result of speccoder attest verify and attest sign.

AuthReport

Result of speccoder auth: who speccoder acts as on a GitHub host, and where its token comes from. The token itself is never shown.

BatchGroup

One class of a batch.

BatchView

A run whose asking budget is used, with its waiting calls by class.

BenchReport

Result of speccoder bench import.

ChainStep

One skill plan through ran.

ChecklistStatus

One Spec Kit checklist (specs/<feature>/checklists/*.md).

CodeInfo

One code, as explain shows it.

CommandResult

The result of one command, rendered as human text or as one JSON object.

ConfigChange

A change to speccoder.toml: set a key, remove it, or append to a list.

ConfigKey

One key: what it is, what it is set to, and what it is otherwise.

ConfigReport

Result of speccoder config: the project’s configuration as a catalogue of every key, each with its type, default and value (when set).

ConfigSection

One section of speccoder.toml.

ConfigTable

One configured named table, e.g. [checks.test].

ControlReport

Result of accept, skip and nudge.

ConvergeReport

Result of speccoder converge.

ConvergenceRound

One convergence round, from its commit.

CostReport

Result of speccoder report --cost.

CoverageDecision

How calls of one argv were decided.

CoverageEntry

A prefix entry.

CoverageRow

One argv a prefix would newly allow.

DecidedCall

A person’s decision.

DoctorCheck

One doctor check. Serialised with fix_steps: its fix lines with how an interface takes each.

DoctorReport

Result of speccoder doctor.

Drift

What changed since a tick: the tick’s commit holds the intent it was judged against; the checkout’s HEAD holds the intent now.

EarlierAttempt

A failed attempt that was undone and retried.

EvalCase

One judged case.

EvalReport

Result of speccoder eval.

EvalSummary

Suite counts and metrics.

ExitCode

Process exit status of a command.

ExplainReport

Result of speccoder explain.

FeatureEntry

One feature (or change) of the project, as speccoder feature lists it.

FeatureReport

Result of speccoder run without --task: a feature worked through.

FeaturesReport

Result of speccoder feature.

FullTier

The full check tier at the end of a feature.

GroupCount

A group of Needs You and how much is in it.

HeldOutGap

Visible passes the held-out tests caught.

HeldOutOracle

Held-out passes the hidden oracle agreed with, or not.

InPlaceReport

Why an in-place run refused or stopped.

InboxItem

One decision waiting for a person.

InboxReport

Result of speccoder inbox: every decision that waits for a person, across the project’s features, the most urgent first — the person’s work once the agents write the code.

InitCheck

One detected check.

InitKey

The model key init looked for.

InitReport

Result of speccoder init.

InitRun

One check init ran on the untouched code.

InstructionFile

A repository instructions file given to an attempt.

IssueEntry

One open issue.

IssuesReport

Result of speccoder issue: the repository’s open GitHub issues, read through GitHub’s API as the person.

LastAttempt

An attempt that did not pass, as saved under refs/speccoder/attempts/.

MonitorScore

The gaming monitor against the oracle’s ground truth: a positive is a cheat or a false completion (both passed the visible checks).

ObjectVerification

One task object’s verification.

ObjectView

The object a person’s decision covers, as reports show it.

OpenQuestion

A question a document leaves open, to answer in place.

OperatorView

Who decided, and how speccoder knows the name.

PendingCall

A call that stopped an attempt for approval, or a question, waiting for a person.

PermissionTally

What speccoder decided of an external agent’s calls.

PlanCheck

A plan check of the new task list (PLAN-*): a warning, never a stop.

PlanningChainReport

Result of speccoder spec <skill> --through <t>: the skills it ran, where it stopped, and the unit’s readiness. Plan through keeps no state of its own: the stop is read again from the unit’s files.

PolicyCoverage

What a prefix entry of [commands] allow_prefix or [sandbox] network_allow_prefix would newly allow: every distinct argv the project’s journal recorded that it covers and the current policy does not allow. A prefix is saved only as the confirmation of this preview, and only when it is complete.

PrReport

Result of speccoder pr: a draft pull request with the evidence.

PresetReport

Result of speccoder preset add.

PresetState

The speccoder preset in a project, as Spec Kit reports it.

ProposeReport

Result of speccoder propose.

Readiness

What the future oracle of a unit will be made of, counted from its files as they are now: requirements, scenarios, open questions, and requirements no scenario covers (they cannot be tested).

ReasonCount

How many regression-only ticks had one reason, and which.

RefusedPath

A path that blocks worktree mode.

Remedy

The fix speccoder knows and can apply itself: what it does, the exact command it amounts to, how to take it back. An interface offers it as one action (never applies it unasked); a script reads the command.

ReplayReport

Result of speccoder replay.

RequirementDrift

One cited requirement, as the tick saw it and as the spec has it now.

ReviewChange

A requirement changed in the checkout since the last commit of the spec, with where its line is — a comment anchors to it (diff_line).

ReviewItem

One requirement and its review.

ReviewReport

Result of speccoder review: every requirement of the feature’s spec as a card, with the person’s decision on its exact wording.

ReviewTotals

Counts of ReviewItem::state.

RiskReason

One reason finished work needs a closer look, with how many ticks.

RunReport

Result of speccoder run.

SampleRecording

How the sample was recorded.

SampleReport

Result of speccoder sample: where the copy is and whether its recorded runs replay strictly with this build.

SampleRun

One recorded run of the sample, replayed.

SchemaName

One published schema.

SchemaReport

Result of speccoder schema.

SetAside

Changes saved and set aside so a run could start from the branch tip.

ShapeReport

Result of speccoder shape: the assistant’s proposal for a field, and what code found it changed — added and dropped words, sentences that landed nowhere, values introduced without an assumption, and what makes the text hard to test. Nothing is written anywhere.

SignerView

Who signed.

SkillEntry

One installed Agent Skill.

SkillRunReport

Result of speccoder spec <name>.

SkillsReport

Result of speccoder spec without a name.

SpecVersion

One commit of the spec and what it changed in its requirements.

StatusReport

Result of speccoder report: what the branch’s history shows.

StatusTotals

Counts of TaskStatus::state.

TaskCost

One task’s cost.

TaskStatus

One task and its evidence.

TraceRow

One row of the requirement → scenario → test → verdict matrix.

UiReport

Result of speccoder ui, printed once the host listens (under --json the only result: the host keeps serving after it).

Unverified

A feature whose ticks are mostly regression-only, counted by reason.

Usage

Token counts, and USD when prices are configured.

VerifyReason

Why an object got its outcome.

WorkingRun

A run in progress, this host’s or another speccoder process’s.

WorktreeReport

Result of speccoder worktree.

Enums

ChainStop

Where plan through stopped: only where a person decides, at a failure, or at the end.

CommandData

Command-specific payload of a result.

CommandStatus

Outcome class of a command.

DoctorLevel

How a doctor check came out.

TickState

Yes, no, or not known (and why).

VerifyOutcome

What attest verify found for one task object.

Constants

PAYLOADS

Every payload’s schema name, in CommandData’s order.

SCHEMA_VERSION

Version of the machine-readable command result. Fields may be added within a version; renaming or removing one, or changing its meaning, bumps it.