README
¶
open-seed-engine
The protocol engine for open-seed: the
pinned seed CLI binary that the template's bootstrap shim downloads, hash-verifies,
and execs.
Per open-seed design decision 7.5, this repo carries the protocol-critical core —
the task port, claim/lease/fence protocol, validators, receipt verify, fan-out
sync, init — as one static, cross-compiled Go binary. The contract (schemas,
transition table, guardrails) stays as files in the open-seed template; this engine
is a replaceable implementation of that spec, and a repo without it installed must
remain workable.
Status
Phase 0 of the build plan:
the release pipeline is proven end-to-end with a stub binary (seed version only).
Port verbs arrive in Phase 1.
Install
Pinned binaries (what the shim uses) come from
GitHub Releases: each
release carries a checksums.txt and GitHub build-provenance attestations
(verify with gh attestation verify <artifact> -R shaunlmason/open-seed-engine).
From source:
go install github.com/shaunlmason/open-seed-engine/cmd/seed@latest
Exit codes
0 success · 2 claim contention · 3 invalid transition · 6 fenced out
(stale claim token) · 10 protocol-version mismatch — reserved by the port
contract (Phase 1+). CLI usage errors exit 64 (EX_USAGE) so they can never be
mistaken for a port result.
Releasing
Releases are driven by the VERSION file: bump it (e.g. to v0.2.0) and push to
main. The release workflow mints the tag at HEAD in-runner — so the tag and
the released commit can never disagree, and no contributor needs tag-push
rights — then runs goreleaser across linux/darwin/windows × amd64/arm64,
publishes archives + checksums.txt, and attests provenance.
(workflow_dispatch with a tag input does the same manually.)
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
seed
command
Command seed is the open-seed protocol engine: the pinned binary that the template's bootstrap shim (scripts/seed) downloads, verifies, and execs.
|
Command seed is the open-seed protocol engine: the pinned binary that the template's bootstrap shim (scripts/seed) downloads, verifies, and execs. |
|
internal
|
|
|
card
Package card parses and serializes task cards: markdown files with YAML frontmatter, living at tasks/<id>.md on the seed-state ref.
|
Package card parses and serializes task cards: markdown files with YAML frontmatter, living at tasks/<id>.md on the seed-state ref. |
|
config
Package config loads .seed/config.toml — the checked-in, human-owned coordination config (control surface, D4.1).
|
Package config loads .seed/config.toml — the checked-in, human-owned coordination config (control surface, D4.1). |
|
gitx
Package gitx drives the system git binary.
|
Package gitx drives the system git binary. |
|
plan
Package plan parses and lints plan files (open-seed D3): thin, mandatory, gated, pinned.
|
Package plan parses and lints plan files (open-seed D3): thin, mandatory, gated, pinned. |
|
port
Package port evaluates port verbs against the loaded spec tables.
|
Package port evaluates port verbs against the loaded spec tables. |
|
prclass
Package prclass classifies PRs by head branch (open-seed D3 purity rule): plan PRs (seed/<id>-plan) touch exactly one plan file; task PRs (seed/<id>) may not touch plans/** at all — not even another task's plan, which would launder plan tampering through an unrelated review.
|
Package prclass classifies PRs by head branch (open-seed D3 purity rule): plan PRs (seed/<id>-plan) touch exactly one plan file; task PRs (seed/<id>) may not touch plans/** at all — not even another task's plan, which would launder plan tampering through an unrelated review. |
|
receipt
Package receipt implements the evidence chain (open-seed D4.5): a receipt records the merge-base plan pin and the diff it authorized.
|
Package receipt implements the evidence chain (open-seed D4.5): a receipt records the merge-base plan pin and the diff it authorized. |
|
spec
Package spec loads and validates the port contract from a repository's .seed/port-schema/ directory.
|
Package spec loads and validates the port contract from a repository's .seed/port-schema/ directory. |
|
stateref
Package stateref implements the seed-state ref lifecycle (§7.2): the dedicated branch carrying machine-written coordination state, written only by this shim, one commit per verb, never checked out.
|
Package stateref implements the seed-state ref lifecycle (§7.2): the dedicated branch carrying machine-written coordination state, written only by this shim, one commit per verb, never checked out. |
|
task
Package task orchestrates port verbs over the filecards backend: it loads fresh state from the seed-state ref, asks the table-driven evaluator (internal/port) whether the operation is legal, applies the spec-declared effects, and commits card mutation + run-log event atomically — one commit per verb (§7.2).
|
Package task orchestrates port verbs over the filecards backend: it loads fresh state from the seed-state ref, asks the table-driven evaluator (internal/port) whether the operation is legal, applies the spec-declared effects, and commits card mutation + run-log event atomically — one commit per verb (§7.2). |
|
validate
Package validate lints the orchestration artifacts (open-seed R9: a shipped convention and its validator are one deliverable): guardrails (auto-merge intersection rule), team files (tier ceiling, unique priorities, non-overlapping scopes, human lead), role variants (body-hash identity — variance in binding, never in craft, §6), and plan files.
|
Package validate lints the orchestration artifacts (open-seed R9: a shipped convention and its validator are one deliverable): guardrails (auto-merge intersection rule), team files (tier ceiling, unique priorities, non-overlapping scopes, human lead), role variants (body-hash identity — variance in binding, never in craft, §6), and plan files. |