sop

package
v0.2.4 Latest Latest
Warning

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

Go to latest
Published: Sep 26, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	VerdictPass = "PASS"
	VerdictFail = "FAIL"
)

Verdict results.

View Source
const DefaultPDDSOP = `# Prompt-Driven Development (PDD) Standard Operating Procedure

You are running a PDD planning session. Your goal is to drive a structured conversation
with the user to produce high-quality spec artifacts for a feature or task.

CRITICAL: Work back and forth with the user at each phase. Do NOT skip ahead to writing
the plan without the user's explicit approval to proceed. Each phase must be reviewed
before moving to the next.

## Process Overview

Follow these phases in order. Each phase produces artifacts in the spec directory.
Announce the phase transition clearly (e.g., "Moving to Phase 3: Research").

### Phase 1: Skeleton Creation (Already Done)
The spec directory has been created with rough-idea.md and requirements.md.
You can reference rough-idea.md for the original idea.

### Phase 2: Requirements Clarification
- Ask the user questions ONE AT A TIME to clarify requirements
- After each answer, append the Q&A to requirements.md
- Cover: scope, constraints, edge cases, dependencies, acceptance criteria
- Ask 3-8 questions depending on complexity
- When requirements are clear, summarize them and get explicit confirmation before moving on

### Phase 3: Objective Research
- Delegate research to subagents rather than reading files into your own context.
  Split the question into 2-5 independent angles and dispatch them in ONE parallel
  ` + "`" + `subagent` + "`" + ` call: ` + "`" + `{tasks: [{agent: "explore", task: "..."}, ...]}` + "`" + `.
  Each angle gets its own agent, and each returns findings — not file contents.
  This keeps the planning session's context small enough to reach Phase 7.
- Explore the codebase to understand relevant existing code
- IMPORTANT: Focus only on facts — how the code works today, what patterns exist, what
  dependencies are involved. Do NOT propose solutions or implementation ideas during research.
- Investigate: existing patterns, conventions, type signatures, interfaces, test patterns
- Write findings to research/ directory as topic files (e.g., research/existing-api.md)
- Share key findings with the user and ask if anything was missed
- Research must be objective — compress the truth about how the code works, not opinions
  about how it should change

### Phase 4: Design Discussion
- Write design.md — a standalone document covering:
  - Current state of the relevant codebase (from research)
  - Desired end state
  - Architecture overview (with mermaid diagram if helpful)
  - Components and interfaces (with Go signatures where applicable)
  - Data models
  - Patterns to follow (from the existing codebase)
  - Error handling strategy
  - Acceptance criteria (Given/When/Then format)
  - Testing strategy
- This is the alignment step — review design with user, incorporate feedback
- The design should be ~200 lines. It captures everything the implementer needs to know.

### Phase 5: Structure Outline
- Before writing the full plan, write outline.md — a high-level breakdown:
  - List of phases/slices (not individual steps)
  - Order of changes and testing
  - Key type signatures and new interfaces (like a C header file)
- This is a quick review checkpoint — easier to correct a 30-line outline than a 200-line plan
- Get user approval before expanding into the full plan

### Phase 6: Implementation Plan (Vertical Slices)
- Write plan.md using VERTICAL slices, not horizontal layers:

  WRONG (horizontal): 1. Build all models → 2. Build all handlers → 3. Build all tests
  RIGHT (vertical): 1. Build User type + CreateUser handler + test → 2. Build GetUser handler + test → ...

- Each slice is a numbered checklist item (- [ ] Slice N: Title) containing:
  - What to implement (specific files and changes)
  - Verification checkpoint: what build/test command confirms this slice works
  - Dependencies on previous slices
  - Parallel-safe: yes/no — "yes" only when the slice shares no files with any
    other slice that has no ordering dependency on it
- Every slice must compile and pass tests independently
- Steps should build incrementally — never require more than one slice to be done before testing
- **Size every slice to fit one worker subagent's context.** /run does not execute
  the plan in a single agent — a Coordinator delegates one slice per worker. A slice
  that needs more than ~10 files or ~400 lines of change is too big: split it.
  Oversized slices are the single largest cause of failed runs — the worker's context
  grows past the model limit and the provider drops the stream mid-slice.
- **Keep plan.md under 2000 lines.** That is the read tool's window: a file longer
  than it comes back one page at a time, so a worker sent to read its slice may act
  on a partial plan or spend turns paging. design.md has the same ceiling.
- **A plan that will not fit is telling you the spec is too big.** Do not solve it by
  shrinking the prose or splitting plan.md into fragments — split the *feature* into
  sequential specs, each with its own requirements/design/plan/PROMPT.md, and note
  the running order in each one's Constraints. A plan too long to read in one call
  is also too long to execute in one Coordinator.

### Phase 7: PROMPT.md Generation
- Write PROMPT.md — the compressed execution briefing
- Use the template below
- IMPORTANT: Discover the project's build and test commands during research
  and embed them in the Gates section
- IMPORTANT: Fill in the Execution Model and Done Criteria sections. /run reads
  them to drive the Coordinator → Worker → Verifier loop. A PROMPT.md without
  Done Criteria makes the Verifier fall back to checkbox counting alone, which
  cannot tell "implemented" from "stubbed".

## PROMPT.md Template

` + "```" + `markdown
# <Title>

## Objective
<1-3 sentences describing what needs to be built and why>

## Key Requirements
1. **<Name>** — <description of requirement>

## Acceptance Criteria
### <Feature Area>
- Given <precondition>, when <action>, then <expected outcome>

## Implementation Slices
1. **<Slice name>** — <what to implement>, files: ` + "`" + `<paths>` + "`" + `, verify: <build/test command>, parallel-safe: <yes|no>
2. **<Slice name>** — <what to implement>, files: ` + "`" + `<paths>` + "`" + `, verify: <build/test command>, parallel-safe: <yes|no>

## Execution Model
Coordinator → Worker → Verifier. The agent that receives this PROMPT.md is the
**Coordinator**; it delegates rather than implements.

- **Workers**: one ` + "`" + `worker` + "`" + ` subagent per slice (` + "`" + `quick-task` + "`" + ` for a single-file
  mechanical change). Slices marked parallel-safe may be batched in one parallel
  ` + "`" + `subagent` + "`" + ` call, but only up to the concurrency the ` + "`" + `subagent` + "`" + ` tool reports for
  the running process — beyond that the tasks queue inside one call instead of
  overlapping. All other slices run one at a time, in order.
- **Verifier**: after the last slice, a ` + "`" + `code-reviewer` + "`" + ` subagent checks the Done
  Criteria below against the actual diff and returns VERDICT: PASS or VERDICT: FAIL.
- **Loop**: on FAIL the Coordinator dispatches fix workers and re-verifies, up to
  10 cycles total.

## Done Criteria
The Verifier checks these against the diff, not against the checklist. Each must
be objectively checkable by reading code or running a command.
- [ ] <observable outcome, e.g. "POST /api/x returns 202 and enqueues a job — see handler_test.go">
- [ ] <observable outcome>
- [ ] No slice is left as a stub, TODO, or panic("not implemented")

## Gates
- **build**: ` + "`" + `<build command discovered during research>` + "`" + `
- **test**: ` + "`" + `<test command discovered during research>` + "`" + `
- **vet**: ` + "`" + `<vet/lint command if applicable>` + "`" + `

## Reference
- Design: ` + "`" + `specs/<task_name>/design.md` + "`" + `
- Outline: ` + "`" + `specs/<task_name>/outline.md` + "`" + `
- Plan: ` + "`" + `specs/<task_name>/plan.md` + "`" + `
- Requirements: ` + "`" + `specs/<task_name>/requirements.md` + "`" + `
- Research: ` + "`" + `specs/<task_name>/research/` + "`" + `

## Constraints
- <constraints discovered during planning>
` + "```" + `

## Naming Conventions

Follow the conventions in specs/AGENTS.md for spec directory structure and naming:

- Use kebab-case for folder names (e.g., plan-command-sop/, not plan_command_sop/)
- Number folders within categories: 000-, 001-, 002-, ...
- Phase files use specific names: rough-idea.md, requirements.md, design.md, plan.md, PROMPT.md, summary.md
- Keep names descriptive but concise

## Guidelines

- **NEVER modify source code** — /plan only reads code for research, all writes go to specs/*
- Write artifacts incrementally (don't wait until the end)
- Each artifact should be standalone and self-contained
- Use the project's existing patterns and conventions
- The PROMPT.md must contain enough context for an autonomous agent to execute
- Gates should use the project's actual build/test commands
- Be thorough but efficient — ask only necessary questions
- Aim for plans with <50 distinct instructions per phase — large instruction counts degrade LLM compliance
- **Delegate to subagents for anything small and self-contained** — a file lookup,
  an API-shape check, a convention question. Spawn ` + "`" + `explore` + "`" + ` (research) or
  ` + "`" + `quick-task` + "`" + ` (small edits); batch independent ones into a single parallel call,
  sized to the concurrency the ` + "`" + `subagent` + "`" + ` tool reports rather than to the number
  of questions you have.
  Read files directly only when you need the exact text in your own context.
- **Never delegate to a [worktree] agent from /plan or /run** (` + "`" + `task` + "`" + `, ` + "`" + `designer` + "`" + `).
  Their edits land in a nested worktree that is never merged, so the work is lost.
  Use ` + "`" + `worker` + "`" + ` or ` + "`" + `quick-task` + "`" + ` — they edit the current directory.
`

DefaultPDDSOP is the embedded default PDD (Prompt-Driven Development) SOP instruction. It guides the LLM through a structured planning process that produces spec artifacts culminating in a PROMPT.md ready for autonomous execution.

View Source
const ManifestName = ".sop-manifest.json"

ManifestName is the machine-readable record a validated spec carries.

View Source
const RecheckSignal = "RECHECK"

RecheckSignal is the output a looping stage emits to take its loop_back edge. A repair stage that fixes nothing does not emit it, and the loop ends.

View Source
const SOPVersion = 2

SOPVersion is the contract version this build writes and understands. A spec planned under a newer version must fail loudly rather than be executed on assumptions that no longer hold.

Variables

View Source
var StartNodeName = workflow.Start.Name()

StartNodeName is the name of the graph's entry sentinel. Edges out of it are scaffolding, not a stage transition, so renderers skip them.

Functions

func LintDefinition added in v0.0.82

func LintDefinition(def *Definition) validate.Findings

LintDefinition statically checks a SOP definition before anything runs.

The checks that matter most are the ones the prose SOPs could only ask for: a stage that dispatches to a [worktree] agent produces edits in a nested worktree that is never merged, so the slice silently produces nothing. The prose warns about this in two places, in bold. Here it is a compile error.

func LintDefinitionFile added in v0.0.82

func LintDefinitionFile(path string) (validate.Findings, error)

LintDefinitionFile parses and lints a SOP file without installing it, so a user editing an override can check it.

func LoadPDD

func LoadPDD(workDir string) (string, error)

LoadPDD returns the PDD SOP instruction text. Resolution order: project .pi-go/sops/pdd.md → global ~/.pi-go/sops/pdd.md → embedded default.

func NodeConfigFor added in v0.0.82

func NodeConfigFor(s Stage, defaults Defaults) workflow.NodeConfig

NodeConfigFor derives a node's runtime configuration from its stage and the definition's defaults.

This is where the SOP's declared bounds become the engine's: a per-stage timeout instead of one blanket 60-minute spawn timeout, and retry with backoff and jitter instead of a counter that re-sends the whole briefing.

func WriteManifest added in v0.0.82

func WriteManifest(specDir string, m *Manifest) error

WriteManifest writes the manifest into the spec directory.

Types

type ArtifactRecord added in v0.0.82

type ArtifactRecord struct {
	Name    string `json:"name"`
	Present bool   `json:"present"`
	Lines   int    `json:"lines,omitempty"`
	Slices  int    `json:"slices,omitempty"`
}

ArtifactRecord is one artifact's state at validation time.

type Compiled added in v0.0.82

type Compiled struct {
	Definition *Definition
	Edges      []workflow.Edge
	// Nodes is indexed by stage id, and by "<id>.review" for a stage's
	// review checkpoint.
	Nodes map[string]workflow.Node
	Order []string
}

Compiled is a SOP definition turned into a runnable graph.

func Compile added in v0.0.82

func Compile(def *Definition, factory NodeFactory) (*Compiled, error)

Compile turns a definition into workflow edges using factory for the node bodies. It lints first: compiling a definition with a dangling edge would produce a graph that silently stops early.

func (*Compiled) Describe added in v0.0.82

func (c *Compiled) Describe() string

Describe renders a compiled SOP as text: the stages in order, their bounds, and the edges between them.

func (*Compiled) GraphEdges added in v0.0.82

func (c *Compiled) GraphEdges() []GraphEdge

GraphEdges returns the compiled edges in a deterministic order: by source stage, unconditional edge first, then by route. Rendering order must not depend on map iteration, or the sidebar would redraw differently each frame.

func (*Compiled) Timeouts added in v0.0.82

func (c *Compiled) Timeouts() map[string]time.Duration

Timeouts reports each stage's effective timeout, for inspection and tests.

func (*Compiled) Workflow added in v0.0.82

func (c *Compiled) Workflow() (*workflow.Workflow, error)

Workflow assembles the compiled edges into a runnable workflow.

type Defaults added in v0.0.82

type Defaults struct {
	Timeout     Duration `yaml:"timeout"`
	Retry       *Retry   `yaml:"retry"`
	OnRateLimit string   `yaml:"on_rate_limit"` // "throttle" | "fail"
	// MaxConcurrency bounds the whole graph. It is separate from the
	// per-process subagent pool, which multiplies rather than shares when
	// runs nest.
	MaxConcurrency int `yaml:"max_concurrency"`
}

Defaults apply to any stage that does not override them.

type Definition added in v0.0.82

type Definition struct {
	SOP         string    `yaml:"sop"`
	Version     int       `yaml:"version"`
	Description string    `yaml:"description"`
	Workspace   Workspace `yaml:"workspace"`
	Defaults    Defaults  `yaml:"defaults"`
	Preflight   []Stage   `yaml:"preflight"`
	Stages      []Stage   `yaml:"stages"`
}

A Definition is a Standard Operating Procedure expressed as data.

The prose SOPs it replaces — DefaultPDDSOP and the /run coordinator contract — stated their rules in a Go string constant, which made every rule advisory. The session corpus is a catalog of those rules being declined: research delegated to subagents 4 times across 69 planning sessions, slices implemented inline by coordinators 302 bash calls to 8 worker spawns, and a Verifier whose verdict was PASS in 9 of 9 runs because nothing read it.

Here the sequencing is a graph the scheduler walks, the review verdicts are edges, and the artifact rules are validators. What stays in prose is each node's own instruction, which is the part an LLM should be deciding.

func LoadDefinition added in v0.0.82

func LoadDefinition(workDir, name string) (*Definition, error)

LoadDefinition returns the declarative SOP named `name` ("plan", "run" or "pr-autofix").

Resolution mirrors LoadPDD: project .pi-go/sops/<name>.sop.yaml → global ~/.pi-go/sops/<name>.sop.yaml → embedded default. An override that fails to parse or lint is reported rather than silently ignored — a SOP that does not compile is a SOP that would schedule nothing.

func LoadEmbeddedDefinition added in v0.0.82

func LoadEmbeddedDefinition(name string) (*Definition, error)

LoadEmbeddedDefinition returns the SOP built into the binary, ignoring project and global overrides.

The graph is compiled to be shown and executed, and an override describes a pipeline that the engine is not running yet — drawing it would be drawing a lie. Overrides are honored again once the compiled graph is the only executor; that is a one-line change at the call site, back to LoadDefinition.

func ParseDefinition added in v0.0.82

func ParseDefinition(data []byte) (*Definition, error)

ParseDefinition decodes a SOP definition. It rejects unknown fields: a typo in a stage key would otherwise silently disable the behavior it names.

func (*Definition) AllStages added in v0.0.82

func (d *Definition) AllStages() []Stage

AllStages returns preflight stages followed by the main stages.

func (*Definition) Stage added in v0.0.82

func (d *Definition) Stage(id string) (Stage, bool)

Stage returns the stage with the given id.

type DescribeFactory added in v0.0.82

type DescribeFactory struct{}

DescribeFactory builds a graph whose nodes carry each stage's identity and configuration but do no work.

It exists so a SOP can be compiled, linted and inspected without a provider, a worktree or a running agent — which is what makes the definitions testable and what lets `pi` report the shape of a SOP before executing one. Phase 3 supplies the factory that runs real agents; the graph it produces is the same graph.

func (DescribeFactory) AgentNode added in v0.0.82

func (DescribeFactory) FunctionNode added in v0.0.82

func (DescribeFactory) FunctionNode(s Stage, cfg workflow.NodeConfig) (workflow.Node, error)

func (DescribeFactory) ReviewNode added in v0.0.82

func (DescribeFactory) ReviewNode(s Stage, r Review, cfg workflow.NodeConfig) (workflow.Node, error)

type Duration added in v0.0.82

type Duration time.Duration

Duration is a YAML-friendly time.Duration accepting "20m", "5s", "1h30m".

func (Duration) Duration added in v0.0.82

func (d Duration) Duration() time.Duration

Duration returns the value as a time.Duration.

func (Duration) MarshalYAML added in v0.0.82

func (d Duration) MarshalYAML() (any, error)

MarshalYAML renders the duration back as a string.

func (*Duration) UnmarshalYAML added in v0.0.82

func (d *Duration) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML parses a duration string.

type FanOut added in v0.0.82

type FanOut struct {
	Over           string `yaml:"over"`
	Agent          string `yaml:"agent"`
	GroupBy        string `yaml:"group_by"`
	MaxConcurrency int    `yaml:"max_concurrency"`
	// Isolation is "sub_branch" or "none". Sub-branch keeps parallel workers
	// from seeing each other's event history.
	Isolation    string `yaml:"isolation"`
	OutputSchema string `yaml:"output_schema"`
}

FanOut declares that a stage runs once per item of a collection.

type GraphEdge added in v0.0.82

type GraphEdge struct {
	From string
	To   string
	// Route is the value that must be produced for this edge to be taken —
	// "PASS", "FAIL", RecheckSignal — and empty for an unconditional edge or
	// the default forward edge of a stage that can fail over.
	Route string
}

GraphEdge is one compiled edge flattened to plain strings.

It exists so a UI can draw the graph without importing the workflow package or type-switching on its Route interface: the renderer needs three strings, not three node objects.

type Manifest added in v0.0.82

type Manifest struct {
	SOPVersion  int                `json:"sopVersion"`
	Spec        string             `json:"spec"`
	Contract    string             `json:"contract"`
	ValidatedAt time.Time          `json:"validatedAt"`
	Artifacts   []ArtifactRecord   `json:"artifacts"`
	Rules       []string           `json:"rules"`
	Findings    []validate.Finding `json:"findings,omitempty"`
	Valid       bool               `json:"valid"`
}

Manifest records what was checked, by which contract, and with what result. /run reads it instead of re-deriving whether a spec is sound, and a spec whose manifest is absent or stale is revalidated rather than trusted.

func BuildManifest added in v0.0.82

func BuildManifest(spec *specdoc.Spec, repoRoot string, contract validate.Contract, now time.Time) *Manifest

BuildManifest validates spec against contract and returns the record.

func ReadManifest added in v0.0.82

func ReadManifest(specDir string) (*Manifest, error)

ReadManifest loads the manifest from a spec directory. A missing manifest is reported as an error so the caller can choose to revalidate rather than silently treat an unvalidated spec as valid.

func (*Manifest) Compatible added in v0.0.82

func (m *Manifest) Compatible() bool

Compatible reports whether a manifest was written by a contract version this build can rely on. A newer manifest is not compatible: it may assert rules this build does not implement.

type NodeFactory added in v0.0.82

type NodeFactory interface {
	// AgentNode builds a node whose body is an LLM turn.
	AgentNode(stage Stage, cfg workflow.NodeConfig) (workflow.Node, error)
	// FunctionNode builds a deterministic node: validators, gates, git.
	FunctionNode(stage Stage, cfg workflow.NodeConfig) (workflow.Node, error)
	// ReviewNode builds a checkpoint — a human approval or an agent verdict.
	ReviewNode(stage Stage, review Review, cfg workflow.NodeConfig) (workflow.Node, error)
}

NodeFactory builds the executable body for one stage.

The compiler owns the graph — what runs, in what order, how often it retries, and what must be true before an edge is taken. The factory owns what a stage actually does. Splitting them is the point: the scheduling that used to live in a prompt ("Follow these phases in order", "on FAIL dispatch fix workers") becomes edges the scheduler walks, while the part an LLM should decide stays in the node body.

type Produces added in v0.0.82

type Produces struct {
	Path     string   `yaml:"path"`
	Validate []string `yaml:"validate"`
}

Produces declares an artifact a stage must write, and the rules it must satisfy. A failing rule keeps the graph on this stage.

type Retry added in v0.0.82

type Retry struct {
	MaxAttempts  int      `yaml:"max_attempts"`
	InitialDelay Duration `yaml:"initial_delay"`
	MaxDelay     Duration `yaml:"max_delay"`
	Backoff      float64  `yaml:"backoff"`
	Jitter       float64  `yaml:"jitter"`
}

Retry is the per-stage retry policy. It maps onto workflow.RetryConfig.

type Review added in v0.0.82

type Review struct {
	Kind          string `yaml:"kind"` // "human" | "agent"
	Prompt        string `yaml:"prompt"`
	Agent         string `yaml:"agent"`
	VerdictSchema string `yaml:"verdict_schema"`
}

Review is a checkpoint between stages: a human approval or an agent verdict.

type SliceResult added in v0.0.82

type SliceResult struct {
	Slice        int      `json:"slice"`
	Title        string   `json:"title,omitempty"`
	Status       string   `json:"status"` // done | blocked | partial
	FilesChanged []string `json:"files_changed,omitempty"`
	VerifyCmd    string   `json:"verify_cmd,omitempty"`
	VerifyPassed bool     `json:"verify_passed"`
	Blockers     []string `json:"blockers,omitempty"`
	Notes        string   `json:"notes,omitempty"`
}

SliceResult is a worker's structured report on one slice.

VerifyPassed is set by whoever ran the verify command, not by the worker claiming it. That distinction is the whole point: plan.md checkboxes in the corpus read 0/50, 0/41 and 6/41 because ticking one was an instruction rather than a consequence.

func (SliceResult) Done added in v0.0.82

func (r SliceResult) Done() bool

Done reports whether the slice may be ticked: it must claim completion and its verify command must have actually passed.

type Stage added in v0.0.82

type Stage struct {
	ID          string `yaml:"id"`
	Description string `yaml:"description"`

	// Kind is "agent" (an LLM does the work) or "function" (deterministic Go:
	// validators, gates, git). Empty means "agent" when Agent is set and
	// "function" otherwise.
	Kind  string `yaml:"kind"`
	Agent string `yaml:"agent"`

	Inputs   []string   `yaml:"inputs"`
	Produces []Produces `yaml:"produces"`

	// Validate holds stage-level rules that are not tied to one artifact —
	// preflight checks, for instance.
	Validate []string `yaml:"validate"`

	FanOut *FanOut `yaml:"fan_out"`
	Join   string  `yaml:"join"`

	Review *Review `yaml:"review"`

	// Routes maps an output value to the stage it advances to. This is what
	// turns a verdict into control flow instead of a sentence in a prompt.
	Routes   map[string]string `yaml:"routes"`
	LoopBack string            `yaml:"loop_back"`
	MaxCycle int               `yaml:"max_cycles"`

	// OnFail is "abort", "retry" or the id of a stage to jump to.
	OnFail string `yaml:"on_fail"`

	Timeout Duration `yaml:"timeout"`
	Retry   *Retry   `yaml:"retry"`

	// Run is the shell command that *is* a function stage's body. Gate runs
	// after a body; Run is the body, which is what lets a SOP express a step
	// like "poll the PR's checks" as data rather than as Go. Exit status is
	// the stage's route: 0 is PASS, non-zero is FAIL.
	Run string `yaml:"run"`

	// Gate is a shell command the engine runs after the stage body. Running it
	// here rather than asking the LLM to is what makes a "verified" slice
	// verified.
	Gate         string `yaml:"gate"`
	GatesFrom    string `yaml:"gates_from"`
	OutputSchema string `yaml:"output_schema"`
	Next         string `yaml:"next"`
}

Stage is one node, or one fan-out group, in the SOP graph.

func (Stage) AgentName added in v0.0.82

func (s Stage) AgentName() string

AgentName returns the agent this stage (or its fan-out) dispatches to.

func (Stage) EffectiveKind added in v0.0.82

func (s Stage) EffectiveKind() string

EffectiveKind resolves a stage's kind, defaulting by whether an agent is set.

type Unmet added in v0.0.82

type Unmet struct {
	Criterion string `json:"criterion"`
	File      string `json:"file,omitempty"`
	Line      int    `json:"line,omitempty"`
	Why       string `json:"why,omitempty"`
}

Unmet is one Done Criterion the Verifier judged not met.

type Verdict added in v0.0.82

type Verdict struct {
	Result string  `json:"verdict"` // VerdictPass | VerdictFail
	Unmet  []Unmet `json:"unmet,omitempty"`
	// Stated is false when no verdict line was found at all. An absent verdict
	// is not a pass: it means the Verifier never ran, or never finished.
	Stated bool `json:"stated"`
}

Verdict is a review stage's structured result.

The prose contract asked the Verifier to "End your reply with exactly one line: VERDICT: PASS or VERDICT: FAIL", and nothing read the answer back into control flow. Across the coordinator sessions in the corpus the verdict was PASS 9 times out of 9 — not because the work was sound, but because a verdict nobody routes on cannot fail.

Parsing it into a value is the first half of the fix; routing an edge on it is the second.

func ParseVerdict added in v0.0.82

func ParseVerdict(text string) Verdict

ParseVerdict extracts a verdict from a review agent's reply.

The last VERDICT line wins: a Verifier that reasons aloud may echo the word while explaining, and its conclusion is what counts.

func (Verdict) Passed added in v0.0.82

func (v Verdict) Passed() bool

Passed reports whether the review may advance. An unstated verdict never passes.

func (Verdict) Reason added in v0.0.82

func (v Verdict) Reason() string

Reason explains a non-passing verdict for the retry briefing.

type Workspace added in v0.0.82

type Workspace struct {
	// Worktree is "per-run" or "none". Per-run means the graph owns one
	// worktree; slices get branches inside it rather than nested worktrees.
	Worktree string `yaml:"worktree"`
	Branch   string `yaml:"branch"`
	MergeOn  string `yaml:"merge_on"` // "success" | "never"
	// Cleanup is "always" or "on_success". "always" is a terminal node
	// reached from every exit path — the reason orphaned worktrees stop
	// accumulating.
	Cleanup string `yaml:"cleanup"`
}

Workspace declares where a run's work lands and who cleans it up.

Directories

Path Synopsis
Package exec supplies the executable NodeFactory the SOP compiler has been waiting for.
Package exec supplies the executable NodeFactory the SOP compiler has been waiting for.
Package specdoc parses the Markdown artifacts a /plan session produces.
Package specdoc parses the Markdown artifacts a /plan session produces.
Package validate checks the artifacts a /plan session produces against a machine-readable contract.
Package validate checks the artifacts a /plan session produces against a machine-readable contract.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL