Documentation
¶
Overview ¶
Package corpus implements the internal benchmark corpus: a curated, capability-tagged set of closed beads worth tracking over time.
The corpus is intentionally curation-driven (no auto-promotion). Three files describe it:
- <root>/corpus.yaml — append-only top-level index, one entry per promoted bead. Required fields: bead_id, promoted, promoted_by, and exactly one of {capability, failure_mode}.
- <root>/corpus/<bead-id>.yaml — per-bead detail (project_root, base and known-good revisions, difficulty, prompt_kind, notes).
- <root>/corpus/capabilities.yaml — controlled vocabulary of capability + failure_mode tags. Every tag referenced by the index must appear here.
Validate loads all three files and cross-checks them; the returned errors point at the file + entry that is malformed.
Index ¶
- Variables
- func CapabilitiesPath(root string) string
- func DetailDir(root string) string
- func IndexPath(root string) string
- func Promote(root string, req PromoteRequest) error
- func Validate(root string) error
- func ValidateLoaded(l *Loaded) error
- type Capabilities
- type Detail
- type Index
- type IndexEntry
- type Loaded
- type PromoteRequest
- type Tag
Constants ¶
This section is empty.
Variables ¶
var ValidDifficulties = []string{"easy", "medium", "hard"}
ValidDifficulties enumerates accepted difficulty buckets.
var ValidPromptKinds = []string{
"implement-with-spec",
"port-by-analogy",
"debug-and-fix",
"review",
}
ValidPromptKinds enumerates accepted prompt kinds.
Functions ¶
func CapabilitiesPath ¶
CapabilitiesPath returns the conventional capabilities vocabulary path.
func Promote ¶
func Promote(root string, req PromoteRequest) error
Promote appends the request to corpus.yaml and writes the per-bead detail file. Both writes are atomic (write temp + rename). If the post-write Validate() fails, Promote rolls both files back to their pre-call state and returns the validation error.
Promote refuses if the bead is already in corpus.yaml — the caller should also gate on "open in beads.jsonl" / "no closing commit" before invoking.
func ValidateLoaded ¶
ValidateLoaded cross-validates an already-loaded corpus. The error returned is a single error joining every problem found, so callers see all failures at once.
Types ¶
type Capabilities ¶
Capabilities is the YAML envelope for capabilities.yaml.
type Detail ¶
type Detail struct {
BeadID string `yaml:"bead_id"`
ProjectRoot string `yaml:"project_root"`
BaseRev string `yaml:"base_rev"`
KnownGoodRev string `yaml:"known_good_rev"`
Captured string `yaml:"captured"`
Capability string `yaml:"capability,omitempty"`
FailureMode string `yaml:"failure_mode,omitempty"`
Difficulty string `yaml:"difficulty"`
PromptKind string `yaml:"prompt_kind"`
Notes string `yaml:"notes"`
}
Detail is the per-bead detail YAML stored at corpus/<bead-id>.yaml.
type Index ¶
type Index struct {
Version int `yaml:"version"`
Beads []IndexEntry `yaml:"beads"`
}
Index is the YAML envelope for corpus.yaml.
type IndexEntry ¶
type IndexEntry struct {
BeadID string `yaml:"id"`
Capability string `yaml:"capability,omitempty"`
FailureMode string `yaml:"failure_mode,omitempty"`
Promoted string `yaml:"promoted"`
PromotedBy string `yaml:"promoted_by"`
}
IndexEntry is one line of corpus.yaml (top-level index).
type Loaded ¶
type Loaded struct {
Root string
Index Index
Capabilities Capabilities
Details map[string]Detail // keyed by bead_id
DetailFiles map[string]string // bead_id → file path on disk
}
Loaded is the result of Load — the three files plus their resolved root.
func Load ¶
Load reads and parses all three files. It does NOT cross-validate; call Validate (or call ValidateLoaded) for that. Missing files return an error wrapping os.ErrNotExist so callers can distinguish "no corpus yet" from a malformed corpus.
func (*Loaded) SortedBeadIDs ¶
SortedBeadIDs returns the bead ids declared in the index, sorted.
type PromoteRequest ¶
type PromoteRequest struct {
BeadID string
ProjectRoot string
BaseRev string
KnownGoodRev string
Captured string // YYYY-MM-DD
Promoted string // YYYY-MM-DD; defaults to Captured
PromotedBy string
Capability string
FailureMode string
Difficulty string
PromptKind string
Notes string
}
PromoteRequest captures the fields needed to add one bead to the corpus. Exactly one of Capability or FailureMode must be set.
Source Files