cmd

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 7, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	VerdictApprove = "approve"
	VerdictReject  = "reject"
)

The two verdicts. There is no third, and no default: an unknown verdict fails closed, and an absent one records nothing at all.

View Source 
const ReviewerVariable = "SPECD_REVIEWER"

ReviewerVariable names the second human. Reviewer identity is resolved from a trusted source exactly as approval identity is; a claim that disagrees with the trusted identity is refused rather than believed.

Variables

This section is empty.

Functions

func Approve 

func Approve(root, change string, options ApproveOptions) (core.ApprovalRecord, error)

func Archive 

func Archive(root, change string, options ArchiveOptions) (core.ArchiveResult, error)

Archive moves one reconciled change into the local archive. The actor is checked by core.Archive, which owns that refusal; this entry only supplies the clock core requires.

func Check 

func Check(root, change string) (core.CheckResult, error)

Check runs the planning gates under the default policy. Findings reach both surfaces as envelope diagnostics; this package renders nothing of its own.

func Complete 

func Complete(root, change, taskID string, expectedRevision uint64, actor string) (core.Completion, error)

Complete closes one task against applicable passing evidence. An empty or unauthorized actor is refused by the core transition, not restated here.

func Context 

func Context(root, change, taskID string, budgetBytes int) (contextmodel.Manifest, error)

func Envelope 

func Envelope(outcome Outcome) (agentjson.Envelope, error)

Envelope projects one canonical result or refusal into the agent document.

func ExitCode 

func ExitCode(err error) int

ExitCode maps a dispatch outcome to its declared exit class: 0 success, 1 failure, 2 usage or fail-closed refusal.

func RenderJSON 

func RenderJSON(outcome Outcome) ([]byte, int, error)

RenderJSON is the one machine surface: one document and its exit code.

func RenderText 

func RenderText(envelope agentjson.Envelope) string

RenderText is the one human surface. It renders the same envelope, so the terminal cannot disagree with JSON about facts, diagnostics, exit, or the legal next action.

func Reopen added in v0.5.0 

func Reopen(root, change string, revision uint64, reason, actor string) (core.ReopenResult, error)

Reopen adapts CLI values once; core owns every recovery decision.

func Sync 

func Sync(root, change string, options SyncOptions) (core.SyncResult, error)

Types

type ActivityCounts 

type ActivityCounts struct {
	Pending    int `json:"pending"`
	InProgress int `json:"inProgress"`
	Completed  int `json:"completed"`
	Failed     int `json:"failed"`
	Blocked    int `json:"blocked"`
}

type ApproveOptions 

type ApproveOptions struct {
	Approver, Reason string
	// Input and Output carry the confirmation prompt. Both default to the
	// process's own streams; they exist so tests need no pseudo-terminal.
	// Interactivity is derived from Input, never supplied by the caller.
	Input  io.Reader
	Output io.Writer
}

type ArchiveOptions 

type ArchiveOptions struct {
	Actor string
	Now   time.Time
}

ArchiveOptions carries the acting identity and the injected clock. Now is local time on purpose: the archive prefix is a local calendar date.

type FrictionResult 

type FrictionResult struct {
	Change      string                     `json:"change"`
	TaskID      string                     `json:"task"`
	Domain      string                     `json:"domain"`
	Operation   string                     `json:"operation"`
	Blocker     string                     `json:"blocker"`
	Consequence string                     `json:"consequence"`
	Actor       string                     `json:"actor"`
	Revision    uint64                     `json:"revision"`
	StateHash   string                     `json:"state_hash"`
	EvidenceSet string                     `json:"evidence_set"`
	Eligibility []core.FrictionEligibility `json:"eligibility"`
}

FrictionResult is the canonical friction outcome: the observation that was appended and the D14 eligibility it now contributes to. Eligibility is a projection, not a grant — it reports that the root owner may decide, never that a deferred domain became available.

func Friction 

func Friction(root, change string, request core.FrictionRequest) (FrictionResult, error)

Friction records one blocked-work observation through the canonical recorder and projects the resulting D14 eligibility. It adds no rule of its own: the recorder owns identity, staleness, blocked-task, and domain refusals.

type InitResult 

type InitResult struct {
	Root Root `json:"root"`
	// Guidance is the generated agent surface installed into the project root.
	// A fresh agent resumes from it, so adoption installs it rather than
	// leaving the file to a route only a Go caller can reach.
	Guidance string `json:"guidance"`
}

func Init 

func Init(root string) (InitResult, error)

type NewResult 

type NewResult struct {
	Root Root `json:"root"`
	state.Projection
}

func New 

func New(root, change, actor, capability string) (NewResult, error)

New creates a change with its scaffolded planning artifacts. The capability names the one delta spec to scaffold; the CLI defaults it to the change name, which is already a valid segment. An empty capability scaffolds no delta.

type NextRefusal 

type NextRefusal struct {
	*failure.Refusal
	Owner  string
	TaskID string
}

func (*NextRefusal) Unwrap 

func (refusal *NextRefusal) Unwrap() error

type NextResult 

type NextResult struct {
	Root           Root                   `json:"root"`
	Change         string                 `json:"change"`
	Revision       uint64                 `json:"revision"`
	Frontier       []string               `json:"frontier"`
	Selected       *core.TaskReadiness    `json:"selected,omitempty"`
	Classification string                 `json:"classification"`
	Blocker        *core.ReadinessBlocker `json:"blocker,omitempty"`
	Action         string                 `json:"action"`
}

func Next 

func Next(root, change, taskID string) (NextResult, error)

Next is a read-only view of the same frontier returned by Status. An empty task ID returns every eligible task; a non-empty ID only validates membership.

type Outcome 

type Outcome struct {
	Operation string
	Root      string
	Change    string
	Task      string
	Value     any
	Err       error
	Exit      int
}

Outcome is one dispatched invocation as the renderer sees it: the canonical result or its error, plus the selectors resolved before the handler ran. The renderer projects it; it decides nothing about lifecycle, evidence, or scope.

type ReportFact 

type ReportFact struct {
	Field string `json:"field"`
	Value string `json:"value"`
}

ReportFact is one normalized report value, keyed by its field name. Both surfaces render this list and nothing else, so the terminal and the JSON document cannot disagree about a value or about the order it appears in.

type ReportResult 

type ReportResult struct {
	Root   Root         `json:"root"`
	Change string       `json:"change"`
	Kind   string       `json:"kind"`
	Facts  []ReportFact `json:"facts"`
}

ReportResult is one projected report. It carries identities, counts, codes, and bounded facts only: no authored bodies, no command output, no patch text, no logs. Rendering owns no truth — every value comes from a canonical model.

func Report 

func Report(root, change, kind, profile string) (ReportResult, error)

Report projects exactly one of the four canonical reports. It reads through the report owner alone: it writes nothing, transitions nothing, executes nothing, and reaches no network.

type Request 

type Request struct {
	Args  []string
	Root  string
	Actor string
	Route Route
}

Request is one invocation. Args is the full argv beginning with the operation id; Root is the fallback root when the invocation selects none.

type Result 

type Result struct {
	Operation string
	Value     any
	Exit      int
}

Result is one dispatched operation's outcome. Exit keeps the distinct exit classes the registry declares.

func Dispatch 

func Dispatch(ctx context.Context, request Request) (Result, error)

Dispatch resolves one invocation against the operation registry and runs its handler only after every declared check passes. Nothing here restates operation semantics: every rule is read from metadata.

type ReviewOptions 

type ReviewOptions struct {
	// Actor is the harness identity recording the verdict. It is provenance,
	// never the verdict itself: the reviewer must be someone else.
	Actor    string
	Reviewer string
	Verdict  string
	Findings string
	Now      time.Time
}

type ReviewResult 

type ReviewResult struct {
	Change            string                  `json:"change"`
	TaskID            string                  `json:"task"`
	AttemptID         string                  `json:"attempt"`
	PolicyDigest      string                  `json:"policy_digest"`
	PacketHash        string                  `json:"packet_hash"`
	EvidenceSet       string                  `json:"evidence_set"`
	Approvable        bool                    `json:"approvable"`
	Blockers          []core.ReadinessBlocker `json:"blockers"`
	Verdict           evidence.ReviewVerdict  `json:"verdict"`
	RecordID          string                  `json:"record,omitempty"`
	Findings          string                  `json:"findings,omitempty"`
	FindingsTruncated bool                    `json:"findings_truncated,omitempty"`
}

ReviewResult is the canonical review outcome: the bounded packet identity the verdict was taken against, the projected verdict state, and the recorded findings excerpt. It carries no packet body, no patch text, and no prose.

func Review 

func Review(root, change, task, attempt string, options ReviewOptions) (ReviewResult, error)

Review projects the bounded review packet and records or reports one separate reviewer verdict. An omitted verdict writes nothing: it reports whether the current review is approved, rejected, stale, or missing.

type Root 

type Root struct {
	Path string `json:"path"`
}

type Route 

type Route string

Route is how an invocation reached the harness. It is provenance, never proof: only a conformant host can attest that a human is at the keyboard. 

const (
	RouteHumanTerminal Route = "human_terminal"
	RouteAgent         Route = "agent_capable"
)

type StartResult 

type StartResult struct {
	Change         string   `json:"change"`
	TaskID         string   `json:"task"`
	AttemptID      string   `json:"attempt"`
	BaselineHEAD   string   `json:"baselineHead"`
	RevisionBefore uint64   `json:"revisionBefore"`
	RevisionAfter  uint64   `json:"revisionAfter"`
	DeclaredFiles  []string `json:"declaredFiles"`
	Assurance      string   `json:"assurance"`
}

func Start 

func Start(root, change, taskID string, expectedRevision uint64, actor string) (StartResult, error)

Start opens one attempt. An unauthorized or empty actor is refused by the core transition itself, which is the one owner of that boundary.

type StatusNextAction 

type StatusNextAction struct {
	Kind      string `json:"kind"`
	Operation string `json:"operation,omitempty"`
	Owner     string `json:"owner,omitempty"`
	Action    string `json:"action"`
}

type StatusResult 

type StatusResult struct {
	Root             Root                  `json:"root"`
	Approval         *core.ApprovalHandoff `json:"approval,omitempty"`
	ApprovalStatus   core.ApprovalStatus   `json:"approvalStatus"`
	Counts           ActivityCounts        `json:"counts"`
	Tasks            []core.TaskReadiness  `json:"tasks"`
	Frontier         []string              `json:"frontier"`
	Next             StatusNextAction      `json:"next"`
	AllTasksComplete bool                  `json:"allTasksComplete"`
	state.Projection
}

StatusResult is canonical status. Policy, assurance, review approvability, and deferred-domain eligibility are not restated here: `report` owns those projections, and a second copy of them is a second source of truth.

func Status 

func Status(root, change string) (StatusResult, error)

Status projects canonical status under the default policy. It loads truth once through the report owner, so status and every report read the same snapshot rather than two parsers of the same files.

type SyncOptions 

type SyncOptions struct {
	Approver, Reason string
	Input            io.Reader
	Output           io.Writer
	Now              time.Time
}

SyncOptions mirrors ApproveOptions: sync is the second human gate, so it resolves identity from the same trusted sources and prompts the same way. Now is injected so the archive target a review shows is deterministic.

type UsageRefusal 

type UsageRefusal struct{ *failure.Refusal }

UsageRefusal is a pre-handler refusal: unknown operation, unknown flag or enum, missing selector, lifecycle mismatch, or unauthorized actor. It maps to the fail-closed exit class and guarantees no handler ran.

func (*UsageRefusal) Unwrap 

func (refusal *UsageRefusal) Unwrap() error

type VerifyOptions 

type VerifyOptions struct {
	Actor       string
	Timeout     time.Duration
	OutputLimit int
	// Production options. An empty class keeps the default test-run loop, which
	// runs exactly the approved task verification command.
	Profile      string
	Class        string
	CheckID      string
	Command      string
	Reviewer     string
	ReviewPassed bool
}

type VerifyResult 

type VerifyResult struct {
	Evidence evidence.TestRun `json:"evidence"`
	// Production carries build, lint, and review observations. It is absent for
	// the default profile, whose result shape is unchanged.
	Production *evidence.Production `json:"production,omitempty"`
	RecordID   string               `json:"recordId"`
	Complete   bool                 `json:"complete"`
}

func Verify 

func Verify(ctx context.Context, root, change, taskID, attemptID string, options VerifyOptions) (VerifyResult, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.