feat(yield): lab 22 — resumable skill programs (yskill V1 core) - #263
Merged
Conversation
…, guard refusals Yield turns SKILL.md workflows into resumable programs: a Go supervisor (yskill) executes deterministic skill programs that yield typed operations (ask_user, agent_task, run_command) to a coding agent. This slice lays the certified core: - protocol: yield.v1 request/response envelopes, skill source digests, compaction-invariant request digests, JSON-schema result validation - runlog: append-only JSONL per run, monotone sequences, refuses overwrite and broken sequences - guard: every refusal as a typed rejection — stale, duplicate, wrong-run, wrong-request, schema-invalid, digest-mismatch, completion-unproven, run-closed; refusing tests discharge the supervisory obligations from the Locus derivation (controllable, nonblocking; docs land with the engine slice) Disclosure-Reviewed: reviewed — public-safe only; the only private-tree change is the rebuilt locus binary, kept out of this commit
- engine: run creation bound to the skill source digest; subprocess execution against a journal rebuilt from the log; run_command executed by the engine itself so command results are observed fact, not the agent's transcription; evidence-bound termination (complete_unproven closes the run blocked, loudly) - sdk/yield: deterministic re-execution context — recorded responses replay in order, the first unanswered operation emits a yield.v1 envelope and exits; a replayed step that produces a different operation reports divergence and always fails the run (never a silent fork); Require(false) makes completion structurally unreachable - cmd/yskill: init · run · resume (--accept-new-digest) · inspect · replay · test - e2e tests drive real subprocess skills through run→resume→complete, replay determinism, loud divergence (env-branch skill), failed requirement blocking, and digest-mismatch refusal then explicit migration The replay-divergence detector caught its first real bug in-lab: request digests differed across the log's JSON-compaction round-trip; digests are now compaction-invariant with a regression test. Disclosure-Reviewed: reviewed — public-safe only; the only private-tree change is the rebuilt locus binary, kept out of this commit
…models - examples/investigate: the reference skill — code owns the discipline (>=3 hypotheses, cheapest-to-disprove first, <=3 failed attempts, completion requires a causal chain, honest blocked at the frontier); the model owns evidence collection, hypothesis formation, assessment; fixtures make it runnable end-to-end via 'yskill test' - docs/locus-yield.md + docs/locus/: the fidelity-certified lifecycle models and verdicts the architecture was designed against — supervisory-rw controllable (no violations), nonblocking (the --accept-new-digest migrate verb is load-bearing), and the rival-design diagnosability derivation: portable mode provably cannot diagnose off-protocol agent action (OFF_PROTOCOL ~ PENDING_OP witness), a correlated host adapter can — stated as a non-guarantee, and the certified post-V1 slice Disclosure-Reviewed: reviewed — public-safe only; the only private-tree change is the rebuilt locus binary, kept out of this commit
Pitot coding-agent E2EIntelligence Flow is the verification source; Pitot's public README carries the latest
Runtime capabilities
Source commit: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
New lab: Yield — turn
SKILL.mdworkflows into resumable programs. A Go supervisor (yskill) executes deterministic skill programs that yield typed operations (ask_user,agent_task,run_command) to a coding agent, with an append-only run log and replay-based resume. The skill keeps its thinSKILL.md; control flow (order, branching, retries, approval, state, completion) moves into code; reasoning and judgment stay with the model. No daemon, no new agent loop, no host integration.Positioning: entry point for people who already write skills today. Separate project from Boatstack — its control-law lessons come in as engineering (refusals, ledger discipline), not architecture or vocabulary.
Architecture (Locus-certified before implementation)
The run lifecycle was designed against certified models (
labs/22-yield/yield/docs/locus-yield.md, models indocs/locus/):internal/guard/guard_test.go.resume --accept-new-digest(migrate) exists; DIVERGED would otherwise block. The migrate verb is load-bearing.OFF_PROTOCOL≈PENDING_OP); a correlated host adapter can (zero indistinguishable pairs). Stated as an explicit non-guarantee; the adapter is the certified post-V1 slice.Execution model
Deterministic re-execution (no coroutine serialization): every run/resume re-executes the skill program from the top; recorded responses replay in order; the first unanswered operation emits a
yield.v1envelope and the process exits. A replayed step that produces a different operation is a divergence and fails the run loudly — never a silent fork.run_commandis executed by yskill itself, so command results enter the log as observed fact, not the agent's transcription (asserted in the e2e test).agent_taskresults are schema-validated on resume; schema validity is not truth, and that honesty gap is recorded, not papered over.Contents
internal/protocol— yield.v1 envelopes, skill-source digests, compaction-invariant request digests, JSON-schema validationinternal/runlog— append-only JSONL per run, monotone sequencesinternal/guard— typed refusals: stale / duplicate-with-different-content / wrong-run / wrong-request / schema-invalid / digest-mismatch / completion-unproven / run-closedinternal/engine— supervisor: journal rebuild from the log, subprocess execution, command evidence, evidence-bound terminationsdk/yield— skill-program SDK (AskUser,AgentTask,RunCommand,Require,Complete,Blocked/Refused)cmd/yskill—init·run·resume·inspect·replay·testexamples/investigate— reference skill: ≥3 hypotheses, cheapest-to-disprove first, ≤3 failed attempts, completion requires a causal chain; runnable end-to-end viayskill testField note
The divergence detector caught its first real bug during the build: request digests differed across the log's JSON-compaction round-trip. Digests are now canonicalized with a regression test — the core invariant earned its keep before the lab shipped.
Verification
go test ./...green (incl. subprocess e2e: run→resume→complete, replay determinism, loud divergence, failed-requirement blocking, digest migration);go vetclean; module passes underGOWORK=offyskill test examples/investigatereachescompletedagainst scripted fixtures with real probe executionOut of scope (deliberate)
Prose-to-program compilation, hosted runtime, workflow DSL, marketplace, multi-agent orchestration, security sandbox, any canonical IR. Working name
Yield/yskillpending a collision scan before any public projection (labkit projection not wired yet).