agent-result-persist-interface
The contract for the sdlc-agent-result-persist CLI — its modes, its flags, the paths it composes, the line grammar of the round log and the agents log it writes, the per-round records and review files it stores, and the derivation modes — next, dispose and summary — that derive a round's arm and outstanding work, its dispositions, severities and verdicts, and its review body. Preloaded into sdlc:theorem-based-pr-reviewer, sdlc:theorem-generator, sdlc:theorem-disprover, sdlc:counterexample-verifier, sdlc:pr-finalizer, and sdlc:pr-merge-readiness via their skills frontmatter; not invoked from the user's slash menu.
- License 许可
- GPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- agent-result-persist-interface
- description
- The contract for the sdlc-agent-result-persist CLI — its modes, its flags, the paths it composes, the line grammar of the round log and the agents log it writes, the per-round records and review files it stores, and the derivation modes — next, dispose and summary — that derive a round's arm and outstanding work, its dispositions, severities and verdicts, and its review body. Preloaded into sdlc:theorem-based-pr-reviewer, sdlc:theorem-generator, sdlc:theorem-disprover, sdlc:counterexample-verifier, sdlc:pr-finalizer, and sdlc:pr-merge-readiness via their skills frontmatter; not invoked from the user's slash menu.
- user-invocable
- false
03 SKILL.md 正文
Agent Result Persist Interface
sdlc-agent-result-persist keeps one review round's evidence outside
every worktree: a round log of one-line records, one result file
per child holding that child's full report, the round's records file
holding its theorem records, and the round's review file holding the
argued review it composed. Any instance of
sdlc:theorem-based-pr-reviewer learns what is left to do from the
script's derivation modes, which read the log and the result files and
nothing it heard back; the next round
reads its predecessor's theorem records out of the records file, and the
end of an orchestrate loop assembles the run's detail out of the review
files. Beside the rounds, the PR's agents log records every agent
spawned for the PR, so the cleanup after the PR can find each one's
worktree by its agent id.
That is the whole design. A child that ran, finished and reported can
still skip its own last call, and a <task-notification> can go
undelivered; both failures look identical from the caller's side, and
neither is recoverable from the caller's memory. So the child writes
its own entry and its own exit, and the caller's view of a child is
telemetry rather than truth.
sdlc:theorem-based-pr-reviewer anchors the round, records each spawn,
reads the log back, records a child it writes off, and at the end of the
round stores its records file and its review file. The theorem
generator, sdlc:theorem-disprover and sdlc:counterexample-verifier
each write their own enter and leave. Every log record is a
single atomic append, so no two writers can be ordered wrongly and no
call has to know what the log already holds. The records file and the
review file are not records: each is written whole and replaces
whatever the round held before, so a resumed instance that re-derives
the round stores its own version over its predecessor's rather than
adding to it. The carry form below builds the records from the round
below --round, never from the round's own, so the resumed instance's
records are rebuilt from the same input its predecessor's were.
Invocation
sdlc-agent-result-persist --mode <mode> \
--pr <host>/<owner>/<repo>#<n> [--round <n>] \
[mode-specific flags]
sdlc-agent-result-persist --mode list [<repository>]
sdlc-agent-result-persist --mode repos
Spell the command as a bare name, never by path: the rule that lets a
child run it unattended — Bash(sdlc-agent-result-persist:*) — is
keyed on that spelling, and it lives in the caller's own settings
because this plugin ships no permission rules.
The payload: --from <path>, or stdin
leave, records and review each store a payload — a report, a
round's records, a round's review. The payload is read from the file
--from <path> names, or from stdin when no --from is passed.
With both present, --from wins and stdin is not read. next and
dispose read the round's new records from --from, per "The
derivation modes" below; every other mode refuses it.
Pass the payload with --from, naming a file you wrote with the Write
tool. The harness's worktree-isolation guard grades a heredoc on the
text it carries, and refuses the call when that text names git
anywhere — so a report that quotes a git log line or a
path under .git/ cannot travel in a heredoc, and quoting it changes
nothing. The guard does not read a Write tool's content, and it never
sees the file's bytes on the persist call.
A child stages its leave payload in the session scratchpad the
harness names in its environment, at
<session-scratchpad>/pr<pr>-r<round>-<stage>-<theorem>-<agent>-report.md,
filling in the --pr, --round, --stage, --theorem and --agent
values of its own leave call, pr<pr> spelled as the state directory
spells it — the number after the # of --pr. Every child in a
fan-out shares that one scratchpad, so a name missing the stage, the
theorem or the agent would let two concurrent children stage over each
other's reports; theorem ids restart at T1 on every PR, so a name
missing the PR would let two PRs' fan-outs in one session do the same;
and the persist script never
removes the file, so a name missing the round would leave an earlier
round of the same PR in the same session holding the path a later
round's child stages at.
If Write refuses because a file already exists at that path, Read it, then Write again.
- A
--frompath that is not an existing file is refused, non-zero, with a message naming the path, before anything is written. - A
--fromfile that exists but cannot be read is refused, non-zero, with a message naming that file. - An empty payload is refused either way, except by
records --carry, whose payload is only the round's new records, and bynextanddispose, which read the same. With no--from, empty stdin gets--mode <mode> takes the <noun> on stdin, and nothing arrived; an empty--fromfile gets a message naming that file. - The file is read, never moved or removed: it stays where its writer put it.
The identifying flags
These two go on every call, and "The paths" below says what they
compose, except where a mode acts above the level a flag names and
refuses it: delete removes the whole PR's directory, print-root
names it, agent and print-agents write and read the PR's agents
log beside its rounds, and rounds lists the rounds themselves, so each
refuses --round, list reads across
every PR of a repository, so it refuses --pr and --round alike and takes the
repository instead, and
repos reads across every repository, so it refuses both and takes no
repository. print-records selects the round itself, so --round is
optional there and bounds that selection rather than naming a round.
--pr <host>/<owner>/<repo>#<n>— the PR, by the canonical reference/github-prs:pr-view <PR> --refprints: its repository, host included, since one machine holds state for repositories on several hosts and the same owner/repo on two of them is two repositories, then#and its number. Pass the reference you were given; never resolve the repository yourself. A bare number, or a reference without a host, is a usage error. Each of host, owner and repo may hold only letters, digits,.,_and-, and none may be.or...--round <n>— a number. Rounds count review passes from 1, and--round 0is valid: the pre-loop seed, settled by the orchestrator before any implementer ran.
list's repository is an optional operand, never a flag:
<host>/<owner>/<repo>, https://<host>/<owner>/<repo>, or a shorter
<owner>/<repo> or <repo>. Omitted, it is the current repository —
the one the checkout's remote names — and a shorter form takes the
segments it omits from the current repository. The script resolves the
current repository itself; pass the operand as you were given it, or
none.
One round is one log. There is no per-fan-out file and no --agent
in the path: the stage column below says which fan-out a record
belongs to, so two files can never disagree about the round and a
reader answers every stage's question from one --mode print.
A round has a type, the class of file it reviews:
code-and-instruction-markdown or documentation, the reviewer's
--mode. Rounds of both types share one sequence per PR, so a
documentation round takes the number after the last code round, and
the paths do not change with the type. The anchor call is where the
type is written, as --round-type <type>, and every read bounded by a
round takes that round's type from there: a round whose log carries no
anchor naming
a type — round 0, which holds the seed and its generator's spawn
record and no anchor, or a round anchored before
rounds had a type — is a code-and-instruction-markdown round. A round
carries only the records of its own type, so the first documentation
round carries nothing; theorem ids run in one sequence across both
types, so its first new id is still one above the highest id any round
below it holds.
The paths
The script composes every path below and no caller ever reads or writes one by path — there is no path string to mistype, and none to carry across a turn boundary. A reader learns a result file's path by reading it out of the log it just printed, and reaches the records and review files through the print modes named for them rather than by path at all.
A caller does spell the PR's state root
${XDG_STATE_HOME:-$HOME/.local/state}/sdlc/<host>/<owner>/<repo>/pr<pr>/ in
prose that points a human at the directory: the review body
--mode summary renders names it once and hangs a round-relative path
off each theorem and finding line, and every file that tells a reader
where a round's detail is spells the same root. That is a signpost, not
a route: nothing composes it to open a file with.
The round gets a directory of its own, and the identifying flags
are the whole of what composes it — no session is part of the path.
Each is a fact about the PR under review, which is what makes a round
survive the session that opened it: a reviewer resumed in a session
that never saw the first one holds both already, composes the same
path, and reads the same log. The script uses the state variable when
set and non-empty and $HOME/.local/state otherwise. This directory is where
the whole of a round's output lives: the theorem
records that the next round carries forward, and the argued review it
composed, are files here rather than text on the PR.
${XDG_STATE_HOME:-$HOME/.local/state}/sdlc/<host>/<owner>/<repo>/pr<pr>/round<round>/log
<the same directory>/<theorem>-<agent>
<the same directory>/records
<the same directory>/review
${XDG_STATE_HOME:-$HOME/.local/state}/sdlc/<host>/<owner>/<repo>/pr<pr>/agents
~/.claude/projects/<project>/<session>/subagents/agent-<agent-id>.jsonl
log is the round log, <theorem>-<agent> a child's result file,
records the round's theorem records, and review the round's argued
review; agents is the PR's agents log, beside its rounds rather than
in one, since an agent spawned for the PR belongs to no round and a
voided round's rename must not carry it away. The .jsonl under
~/.claude/projects/ is the harness's own transcript of a child, which
--mode enter records. The records and
the review are written at the end of the round, and a voided round's
rename carries both with it exactly as it carries the log and the
result files.
<project> is the primary clone's path with every character
outside [A-Za-z0-9-] replaced by a dash — measured on a / and on a
. alike. Every child runs in a worktree, so its own cwd is the wrong
basis: the primary root is git rev-parse --git-common-dir passed
through dirname. <session> is CLAUDE_CODE_SESSION_ID and
<agent-id> is the child's own worktree name with agent- stripped.
The harness's per-session scratchpad holds an .output symlink to that
transcript; the record carries the target, which outlives the symlink.
With any of those unavailable the record still lands, carrying - in
the transcript column. A missing path is worth less than a missing
record.
The repository's directory, sdlc/<host>/<owner>/<repo>/, carries a
repo.yml naming the repository it holds, which the script writes when
it creates the directory:
schema-version: 1
host: github.com
owner: <owner>
repo: <repo>
The file is what identifies the directory; no reader derives the
repository from the path's depth or segment names, and where the file
and the path disagree the file wins. State written before the host was
part of the path sits at sdlc/<owner>/<repo>/. Every run, of every
mode but repos, first moves that directory to sdlc/<host>/<owner>/<repo>/,
host from --pr or from list's repository, and writes its
repo.yml; no mode reads the old path afterwards. A run that finds
state at both paths refuses, non-zero, naming both, and moves nothing.
Nothing here is deleted but by --mode delete, and that mode is
called only by sdlc-orchestrate-cleanup, which the human invokes and
which /sdlc:orchestrate runs for a PR after that PR has merged. A
round's files are the evidence a stalled or voided round is diagnosed
from, so no mode that runs during a review removes one, and none ever
expires: a PR's directory stays until /sdlc:orchestrate cleans up
after the PR's merge — a merged PR's evidence is no longer needed to
diagnose a round — or the human decides its evidence is no longer
wanted.
The modes
One word, one meaning: every mode is named for what it writes — the
record, or the file — the print modes for the ones that read one
round, print-root for the PR directory it names, print-agents for
the agent ids it reads across the PR's logs, rounds for the rounds it
lists, list and delete
for what they do across a repo's PR directories, repos for what
it lists across the state root, wait for what it does, and next,
dispose and summary, under "The derivation modes", for what they
derive.
-
anchor— writes theanchorline carrying--head-sha <sha>and--round-type <type>, both required. One call per round, and idempotent, which is what lets the reviewer make it without knowing whether a child has already written:- No
anchorin the log — the line is appended, creating the log when it is absent. A child that started first has already created it with its ownenter, so the anchor is not necessarily the first line and no reader may assume it is. - An
anchornaming the same head SHA and type — this same round's, so the call writes nothing and exits zero. - An
anchornaming the same head SHA and another type — the round is the other loop's, and nothing moved under it, so the call is refused, non-zero, naming both types, and writes nothing. - An
anchornaming a different head SHA — the records describe a tree that no longer exists, so the round's whole directory is renamed toround<round>.voided-<instant>— kept as the evidence of what the voided round did — and a freshround<round>/holding only the new anchor takes its place. Nothing is deleted. The result files move with the log because a reader takes a report's existence as a settled theorem, and one left under its own name would settle the fresh round's theorem from the voided tree.
- No
-
spawn— appends onespawnrecord for--theoremin--stage, carrying--agent,--modeland--effort. The caller's, once per child it spawns, and the orchestrator's once, at--round 0, for the seed generator it spawned before the PR existed. Model and effort are on this record because the caller chose them and a child can read neither; pass the tokendefaultwhere the spawn named none and the definition's own frontmatter decided. -
enter— appends oneenterrecord for--theoremin--stage. A child's first act, before it does any work. The script derives the agent id from the child's own worktree and composes the transcript path, so nothing is passed in. -
leave— writes the child's report, read as its payload, to that child's result file, then appends oneleaverecord naming the file. A child's final act.--agentis half the file's name. The report is stored byte for byte: no size limit, no encoding, no quoting. Empty input is refused — aleaveexists to carry a report. The report is written before the record that names it, so a run that dies between the two leaves the report readable rather than a record pointing at nothing. Once both have landed, the call prints the result file's path on stdout, and that line is what a child's hand-back opens with, per "A child's hand-back" below; a refusedleaveprints nothing there.The payload lands first in
<result-file>.partial-<pid>and is renamed into place only once it is whole, because a result file's mere existence settles its theorem: a report streamed straight to its own name would settle the theorem from a fragment the moment the first byte landed, and a child killed mid-write would leave that fragment there for good. The rename is what makes the file appear complete or not at all, and the-<pid>suffix is what keeps two writers from staging over each other. A refused report — empty, a--fromfile that could not be read, a result-file path carrying whitespace, aTHEOREM:mismatch or an id refusal below — leaves nothing behind: the staging file is removed before the call exits non-zero, and noleaverecord is appended.With
--stage disproveor--stage verify, the report must answer the theorem it is filed under. The first line of the report that startsTHEOREM:names that theorem, and the call is refused, non-zero, when no such line names one or when it names a theorem other than--theorem; the message names the--theoremvalue and, on a mismatch, the one the report named. A result file is named for--theorem, and its existence settles that theorem, so a report handed over from another child would otherwise settle a theorem it never answered.With
--stage generatethe report is the theorem list, filed under--theorem list, and its new ids must continue the PR's sequence: one above the highest id the records of any round below--roundhold, of either type, orT1when none holds any — round 0 included. Its ids are the lines holding nothing butT<n>, above anyRETIREMENTSline, in order, and each is held to the rule the carry form holds a new record to: a new id a carried record — oneprint-records --round <round>would print — already holds, or one that is not the next id in sequence, is refused, non-zero, with a message naming that id and the expected next one. The call is refused asprint-recordswould be, too, when a round above--roundholds records. -
return— appends onereturnrecord for--theoremin--stage, carrying--agent-idand the optional--tokens,--toolsand--ms. The caller's, from a final<task-notification>it received. It is best-effort telemetry and never evidence, and a stage never waits on one. An omitted number leaves its column empty rather than dropping the column. -
stopped— appends onestoppedrecord for--theoremin--stage, carrying--agent-id, the id of the child it writes off, as that child'senterrecord names it — or-, as--mode nextprints it, for a child written off before it wrote itsenter. The caller's, when it writes a child off. It writes one whether or not itTaskStopped that child — a predecessor instance's child is never its to stop, and the record is what says the child was written off either way.--agent-idis required: without it the call exits non-zero and appends nothing, since a record naming only the theorem would write off whichever child the theorem had when it landed, a replacement included. -
print— writes the round log to stdout, followed by oneresultline per result file present and then oneround-typeline naming the round's type. A.partial-<pid>staging from aleavestill in flight is skipped, so a report reaches a reader whole or not at all, and so are the round'srecordsandreviewfiles, which are the round's own output rather than any child's report. Exits non-zero when the log does not exist, which means neither the round'sanchorcall nor any child'senterhas run — the fresh-round case the reviewer branches on before spawning anything. -
print-in-flight— writes to stdout one line per theorem with a child in flight in--stage,<theorem> <agent-id> <instant>: the child's agent id and the instant of itsenter, which is what its deadline runs from.--stageand--agentare required,--agentnaming the definition whose result file settles the theorem —theorem-generator,theorem-disproverorcounterexample-verifier. "What the reader derives" below states what in flight means. Exits non-zero when the log does not exist, asprintdoes. -
wait— blocks until a child in--stagesettles or runs out of time, then exits zero.--stageand--deadline-minutesare required. It waits on each theorem with a child in flight in the stage, and on each with a child yet to enter there, as "What the reader derives" below defines both. It exits on whichever comes first, printing one line,\tstanding for a tab:leave\t<theorem>\t<agent-id>— aleaverecord in the stage landed after the call started;deadline\t<theorem>\t<agent-id>—--deadline-minuteshave passed since theenterof the earliest child it waits on, or since the lastspawnof a child yet to enter, whose agent id is-;none— no child is left to wait on, at once when there was none from the start, a round with no log included.
It reads the log every two seconds, and writes and creates nothing.
-
records— writes the round's theorem records to the round'srecordsfile. Without--carryit stores its payload whole: the orchestrator's once, at--round 0, for the ruled seed, and the reviewer's on a round with nothing to carry. With--carry, below, it builds the file from the carried round: the reviewer's on every other round that reaches disposition, an empty-delta round included. In the plain form empty input is refused, and in both the bytes land in a staging name and are renamed into place only once whole, for the reasonleavegives: a reader takes the file's existence as the round's records, and half a file would carry half a round's theorems into the next round with nothing saying so.A records file is a sequence of records in id order, separated by one blank line. Each opens with its id,
T<n>, on a line of its own, followed by onekey: valueline per field:claim,issues,settle-mode,pointers, then, when present,state,state-detail,settled-at,severity-override, in that order. Ids are never reused.With
--carrythe script builds the file itself rather than taking one whole, and makes no decision while doing so — what each record's new state is arrives as an edit:- It reads the records of the highest-numbered round below
--roundthat holds a records file and is of the type--round's own anchor names, skipping the.voided-<instant>directories asprint-recordsdoes. A records file at--rounditself is not read:--roundmay be the latest round holding records, and the carry then rebuilds that round's file from the round below, so a resumed reviewer stores its round's records again and gets the same file from the same edits. It refuses when any round above--roundholds a records file, of either type. - It applies the edits file
--edits <path>, one edit per line:<id>, a tab,<field>, a tab,<value>.<value>is the rest of the line and may be empty; an empty line is skipped.<field>is one ofstate,state-detail,settled-atandseverity-override. An edit to a field the record has replaces its line in place; an edit to a field it lacks adds the line after the record's other fields, the added lines in that same order. Onlystateis validated — it isdisproved,unsettledorretired— and the other three are stored verbatim.--editsis optional: a round that changes no carried record passes none. - It appends the new records read as its payload, in the record
shape above. Their ids, in payload order, are exactly
T<m+1>,T<m+2>, … whereT<m>is the highest id the records of any round below--roundhold, of either type. The payload may be empty here, so an empty-delta round and a round that only retires are both written. - It writes the result in id order, staged and renamed into place as the plain form is.
No carried record gains or changes a field that no edit names. Every round from 1 on stamps a
stateon every record, so the result must hold one on each.Each of these is refused, non-zero, writing nothing and creating no round directory, with a message naming the offending line or id:
- an edit line that is not three tab-separated parts;
- an edit naming an id no carried record has;
- an edit to a field outside the four;
- a
statevalue outside the three; - a second edit to the same field of the same record;
- a new record whose id a carried record already holds, or that is not
the next id in the
T<m+1>,T<m+2>, … sequence; - a result that leaves any record without
state— a round-0 seed record carried into round 1 unstamped is the case this catches — naming each such id; --carrywhen no round below--roundof its type holds a records file, naming the type, or when a round above it does, naming that round;--editswithout--carryin any mode butnextanddispose, and--carryin any mode butrecords.
- It reads the records of the highest-numbered round below
-
review— writes the round's argued review, read as its payload, to the round'sreviewfile, on the same terms asrecords. -
print-records— writes to stdout the records of the highest-numbered round that holds a records file, ignoring the.voided-<instant>directories, whose records describe a tree that no longer exists. The round to carry forward is the most recent one there is, not one a caller names. A--round <n>bounds the selection to the rounds below<n>of the type round<n>'s anchor names, and<n>need not hold records itself: a round under way passes its own number, so it reads the round it carries from even when an earlier instance of it already stored this round's records. With--round <n>it exits non-zero, printing no records, when any round above<n>holds a records file — the condition--carryrefuses on, decided by the same code — so a stale--roundfails at this read rather than at the carry that follows it. Without--round,--round-type <type>narrows the selection to the rounds of that type; beside--roundit is refused, since that round's anchor already names the type. Its first line isround <n>, naming the round it selected, so a reader that needs the rest of that round's state — itsanchorline's head SHA, its review file — has the number to ask for it with; the records follow from the second line on. Exits non-zero when no round it considers holds a records file — a PR whose round 1 has no round-0 seed to read, or a first documentation round — naming the type it selected by. -
print-round-records— writes the named round's records file to stdout, byte for byte, with noround <n>line in front: the caller named the round. It is the read for a caller that walks every round rather than carrying the most recent one forward, and it creates nothing. Exits non-zero when that round holds no records file. -
print-review— writes the named round's review file to stdout. Exits non-zero when that round holds none. -
print-root— writes the PR's state root to stdout as two lines, each with its trailing/: first expanded, then as the signpost "The paths" describes, with<host>,<owner>,<repo>and<pr>filled in and the state variable and its fallback left unexpanded. It is composed here so a caller that names a file to a human relative to the root spells no root of its own; it opens nothing. It takes no--roundand refuses one, creates nothing, and exits zero whether or not the directory exists. -
agent— appends oneagentrecord to the PR's agents log, carrying--agent, the definition spawned, and--agent-id, the id theAgenttool's result names for the spawn — the<agent-id>of the harness's.claude/worktrees/agent-<agent-id>worktree and itsworktree-agent-<agent-id>branch. The spawner's, once per agent it spawns for the PR, whether or not that agent runs in a worktree of its own. It takes no--roundand refuses one; both--agentand--agent-idare required. -
print-agents— writes to stdout every agent id the PR's state names, one per line, sorted and each once: everyagentrecord's, and everyenterrecord's in every round log, the.voided-<instant>rounds included, since a voided round's children left worktrees too. It takes no--roundand refuses one, creates nothing, and prints nothing for a PR with no state. -
rounds— writes to stdout one round number per line, ascending, for each round from 1 whose log exists. Round 0, the seed, is not printed, nor is a.voided-<instant>round. The numbers need not start at 1 or run unbroken, so a caller visiting every round visits what this prints rather than counting up from 1. It takes no--roundand refuses one, creates nothing, and prints nothing and exits zero for a PR with no log. -
list— writes to stdout one PR per line, as the<host>/<owner>/<repo>#<n>reference--prtakes, in ascending order of<n>, one perpr<n>/directory under the repository's<host>/<owner>/<repo>/state directory, and nothing else on the line; an entry whose name is notprfollowed by digits, or that is not a directory, is skipped. The repository is the operand "The identifying flags" describes. It takes no--prand no--round, and refuses either, and refuses a second operand. A repository no review has run against has no directory, so the output is empty and the exit zero; the mode creates nothing. -
delete— removespr<n>/recursively, every round under it, every voided round and the agents log with them. It takes no--roundand refuses one, and it refuses a missing--prwith the usual--pr is requiredmessage. A directory already absent is the state the call asks for, so it exits zero and prints nothing. -
repos— writes to stdout one line per repository directory the state root holds,<kind> <repository> <directory>, the directory relative tosdlc/. Every directory holding arepo.ymlis read from that file:repowhen the file names the directory's own path,mismatchwhen it names another, the repository being the file's<host>/<owner>/<repo>either way. A directory two levels down that has norepo.ymlin it or one level down, and holdspr<n>/directories directly, is old-layout state:old <owner>/<repo> <owner>/<repo>, its host unknown. It takes no repository and no flag but--mode, refuses each with exit 2 before it lists anything, moves nothing, and prints nothing for a state root that does not exist.deleteis the only mode that deletes stored state. The one thing any other mode removes is its own staging file, whenleave,recordsorreviewrefuses its payload as empty or as a--fromfile that could not be read, orleaverefuses a report whoseTHEOREM:line does not name--theoremor a theorem list whose ids do not continue the carried records;anchorrenames a voided round rather than removing it.
The script stamps every record's time itself: the writer owns when the record was made.
A refusal and a malformed call both exit non-zero, so the status says only that the call did nothing. The message says which.
The derivation modes
next, dispose and summary each read one round, named by --pr
and --round, store no record and no file, and create no directory.
In the line shapes below \t is the one tab that separates two fields,
and in a field - stands for no value.
The round's theorems. next and dispose read the round's records
from three inputs:
- the carried records — those
print-records --round <round>would print, refused as that read refuses, and none when no round below holds records; --edits <path>— this round's adjustments to the carried records, a retirement or aseverity-override, one per line in the carry form's edit grammar;--from <path>— this round's new records, generated and minted, in the record shape, before anystateis stamped.
Each file is optional and may be empty, and each is refused on the
carry form's terms, with its messages. The live list is the
theorems that get a disprover this round: every record this round's
edits do not retire that holds no state, or disproved or
unsettled. --full makes it every record whose state-detail is not
human-refuted, retired ones included, except those this round's edits
retire.
A report's grammar. A disprover's or verifier's result file is
classified on the template its sender's file gives under "Output" —
theorem-disprover.md and counterexample-verifier.md. Exactly one
VERDICT: line is required, and then:
| Verdict | Well formed when it carries |
|---|---|
SURVIVED |
a non-empty CHECKED: |
UNSETTLED |
a non-empty REASON: and a non-empty CHECKED: |
DISPROVED |
a non-empty COUNTEREXAMPLE:, an EVIDENCE: line followed by a > quote, a non-empty CONSEQUENCE:, and a CONSEQUENCE-CLASS: line |
REFUTED |
a non-empty REASON: |
STANDS |
a non-empty CONSEQUENCE:, and a CONSEQUENCE-CLASS: holding one of the four tokens |
Any other report is malformed. A DISPROVED report whose class line
holds no token is well formed with its class underivable. The grammar
does not check that a quote is verbatim; the verifier does.
-
next— prints the arm the round is in, alone on the first line, then one line per theorem with work left in each stage up to that arm's:<stage>\t<theorem-id>\t<outstanding|in-flight|spawned|overdue|returned-unsaved>\t<agent-id>\t<enter-time>The last two fields are empty for
outstanding; for a child yet to enter they are-and its theorem's lastspawntime. It takes--head-sha <sha>,--deadline-minutes <n>,--edits,--fromand--full, all optional.Token The log shows no-logno round log; nothing else is read or printed moved-headan anchornaming a head other than--head-sha, only when--head-shais given; nothing else is printedgeneratelistnot settled in thegeneratestagedisprovea live theorem neither settled nor in flight in the disprovestage, or one in flight thereverifyno live theorem outstanding in the disprovestage, and a well-formedDISPROVEDreport whose verifier is unsettleddisposeno theorem outstanding in the verifystageA stage's members are
listforgenerate, the live list fordisprove, and forverifythe live theorems whose disprover report is a well-formedDISPROVEDone; a malformed one earns no verifier. Outstanding and in flight are as "What the reader derives" below defines them. An outstanding theorem is printedoutstanding, and a theorem with a child in flight is printed with its child's state and never asoutstanding, member or not:returned-unsaved— areturnrecord in the stage names the child, which finished without saving and never will, so this is work at once, whatever the deadline;overdue— the child, with noreturn, has anenterat least--deadline-minutesbefore the clock at the time of the call. Without--deadline-minutesnothing is overdue;in-flight— any other child in flight.
A theorem with no child in flight that the stage has not settled, and a child yet to enter there, as "What the reader derives" below defines one, is printed with that child's state, never as
outstanding:overdue— its lastspawnis at least--deadline-minutesbefore the clock at the time of the call;spawned— otherwise.
-
dispose— prints one row per live theorem, in id order, then one verdict line per member of--issues, in the order given, and per other issue the records tag, in first-tagged order, then the overall verdict:<theorem-id>\t<disposition>\t<class>\t<severity>\t<state>\t<state-detail> verdict\t<issue-number>\t<verdict> verdict\toverall\t<verdict><issue-number>is the issue without its#.--issues <issues>, required, is the issue set under review, its members separated by spaces or commas, eachNor#N. It also takes--edits,--from,--fulland--loop-exited, all optional.--loop-exitedsays the resume-pass loop has exited for the round. Without it, a live theorem with no result file for its stage gets no row: the mode prints nothing on stdout, names each such theorem and its stage on stderr, and exits 3. With it, such a theorem takes its stage's no-verdict row.Disprover Verifier <disposition>SURVIVEDnot spawned verified-survivedDISPROVEDREFUTEDverified-refutedDISPROVEDSTANDSfinding, class from the verifierDISPROVEDmalformed finding-verifier-malformed, class from the disprover's proposalDISPROVEDno result file, with --loop-exiteddisproved-unverified— no finding, no severityUNSETTLEDnot spawned unsettled-disprover-unsettled, no severitymalformed not spawned unsettled-disprover-malformed, no severityno result file, with --loop-exitednot spawned unsettled-no-verdict, no severity"Could not be settled" and "unsettled" name the
unsettled-rows.<class>and<severity>are-on every row but a finding's. The state each row stamps:Rows <state><state-detail>the two verified-rowsretired, itssettled-atthis round's head SHAsurvivedordisproved-but-refutedthe two findingrowsdisprovedfinding <n>, <severity>, with, class-underivableafter it on such a findingdisproved-unverifieddisprovedunverifiedthe unsettled-rowsunsettled-, the field emptiedFindings are numbered from 1 by severity, highest first, then by id. A theorem that got no disprover this round has no row and keeps the state and head SHA it had; a round whose log holds no
spawnand noenterrecord — the empty-delta round — gives no theorem a row.The severity is the class table's, or High where the class is underivable, and a
severity-overrideon the record, case-insensitively one of the four severities, replaces it. Nothing else adjusts it. An override that is none of the four is refused, exit 2, on a theorem whose finding it would grade.Consequence class Severity breaks-productionCritical behavior-broken-or-criterion-unmetHigh defect-no-shipped-breakageMedium optional-polishLow The class is underivable —
class-underivablein<class>— when the verifier's report is malformed and the disprover's proposal is not a token either.The verdicts are derived per issue, over the findings and unsettled theorems tagged to it, and overall over all of them: any unsettled theorem →
BLOCKED, whatever the findings; else any Critical, High or Medium finding →NEEDS_CHANGES; else, with only Low findings or none,APPROVED. A theorem with a row contributes by its row; any other by the state it carries —unsettledas an unsettled theorem, anddisprovedwith afinding <n>, <severity>state-detail as a finding at that severity, or at its override. -
summary— renders the review body to post from the round'srecordsandreviewfiles, and prints it as Markdown and nothing else. It takes no flag but the two identifying ones, and exits non-zero, printing nothing, when the round lacks either file or the review lacks a section it copies. The body is an index into the round's state directory, never a copy of the argued review. In order:- the stamp
<!-- sdlc:review-round <n> -->,<n>being--round, which marks the posted review as this round's; - the review's
## Verdictssection, copied through unchanged; - its
## Review methodsection, copied through unchanged; ## Theorems, naming the state root once as${XDG_STATE_HOME:-$HOME/.local/state}/sdlc/<host>/<owner>/<repo>/pr<N>/, then one line per recorded theorem in id order —- <id> — <state>, <state-detail> — <what changed> — <paths>— where what changed isnewfor a record the carried records lack,unchangedwhen its state, state-detail andsettled-atare as they held them, and otherwisewas <state>, <state-detail>as they held it,unattackedstanding for no state;## Findings, one line per finding in number order —- <n> — <severity> — from <id>, <issues> — <paths>— ornone;- its
## Overall verdictsection, copied through unchanged; - its
## Closing-line correctionssection, copied through unchanged.
A review section runs from its
## <name>heading to the next level-two heading outside a code fence., <state-detail>is left out where a theorem has none. Every<paths>is the backquoted paths, relative to that root, of each file holding the line's detail: a finding's argued text is in its round'sreviewfile, and a child's report inround<n>/<theorem>-<agent>, this round's when it has one, else the highest round below holding one — so a carried-forward retired theorem points at the older round its detail is in. A theorem with no report anywhere points at this round'srecords. No argued text, no quoted counterexample and no record field but a theorem's state and state-detail and a finding'sissuesappear in the output. - the stamp
The line grammar
One record per line, whitespace-separated columns, appended, and no line is ever revised in place:
anchor <instant> <head-sha> <round-type>
spawn <theorem> <stage> <instant> <agent> <model> <effort>
enter <theorem> <stage> <instant> <agent-id> <transcript-path>
leave <theorem> <stage> <instant> <agent-id> <result-file>
return <theorem> <stage> <instant> <agent-id> tokens=<n> tools=<n> ms=<n>
stopped <theorem> <stage> <instant> <agent-id>
--mode print adds one line per result file it finds, synthesized from
the directory at read time and stored nowhere, and then the round's
type as "The identifying flags" above settles it, so no reader applies the
rule for an anchor naming none itself:
result <theorem> <agent> <result-file>
round-type <round-type>
Every instant is date -u +%Y-%m-%dT%H:%M:%SZ. <stage> is
generate, disprove or verify, and <round-type>
code-and-instruction-markdown or documentation. The script rejects
any column value carrying whitespace, which would shift its own line's
columns.
A result line carries the agent rather than the stage because that is
what the file's own name holds, and the name is split back apart at its
first dash — so a theorem id carries no dash and the script refuses one
that does. Which stage a result belongs to follows from the agent that
wrote it.
The generation stage answers no single theorem, so its theorem column
is the literal list — the thing it produces. Every other stage's is a
theorem id.
The agents log holds one record kind, on the same terms — one line per record, appended, never revised, every column a single token:
agent <instant> <agent> <agent-id>
Two lifecycles share the log, and the split is what keeps the
vocabulary from drifting the next time a kind is added. spawn,
return and stopped are the caller's view of a child — it asked for
one, it heard back about one, it wrote one off. enter and leave are
the child's own — it began, and it finished. A caller therefore never
writes an enter or a leave, and a child never writes any of the
other three.
A spawn record is written per child rather than per theorem, so a
theorem re-spawned in a later wave carries one for each attempt. That
is what makes a child that never started distinguishable from one that
started and vanished. The derivations below read spawn as a set of
theorem ids, so the repeats change nothing they answer.
The anchor line's <head-sha> is the head commit the round's
theorems were generated against, and it is what a resume compares
against origin/<branch> before trusting a single record: a scheduled
sweep force-rebases open PR branches and can fire mid-round, and
verdicts from two trees must never be mixed.
What the reader derives
Everything that changes as the round runs is derived on each read,
never stored. A stored list is a line that must be revised to stay
true; a derived one cannot go stale. The script is the reader: next
and dispose, under "The derivation modes", apply the rules below, and
a caller asks them rather than deriving anything off the log itself.
A theorem is settled in a stage when its child wrote leave, or when
its result file exists — never when the caller heard back: a return
record settles nothing, and a hand-back is never read. The two are
almost always the same fact, and the second is what covers a child that
wrote its report and died before the record landed.
The result file is the one under the stage's agent, theorem-generator,
theorem-disprover or counterexample-verifier, whatever effort a
spawn record gave it.
A stage's outstanding theorems are its members, over the live list rather than over the theorems the log was told about, less the settled ones, the in-flight ones and those with a child yet to enter, which is what puts a theorem no instance ever spawned back in play.
A theorem has a child yet to enter in a stage exactly when its last
spawn there is followed by neither an enter nor a stopped there.
--mode next and --mode wait apply that one rule, deciding it by the
order of the records, never by comparing counts of spawn and enter
records. A stopped naming an earlier child — one an enter of the
theorem in the stage named before it — writes off that child alone, so
landing after a later spawn it leaves the replacement yet to enter.
Any other stopped, - included, writes off the child the last
spawn started, before its enter, so the theorem is outstanding
again until a later spawn — unless an earlier child of the theorem is
still in flight in the stage, which leaves it in flight.
The verdict itself is in the result file, which the leave line names
and the result line names again, and is never inferred from the log.
Whether an outstanding theorem has a child in flight is a second
question, and it is keyed on the child rather than on the theorem. A
theorem is in flight when its last enter in that stage carries an
agent id that no leave and no stopped of that theorem carries, and
no result file for it under --agent exists. --mode print-in-flight,
--mode next and --mode wait apply that derivation. A stopped is
matched to an enter by agent id, never by where it lands, so an
original child's stopped that lands after its replacement's enter
writes off the original alone and leaves the replacement in flight.
That is the question a deadline arm asks — an outstanding theorem with no child in flight has nothing to be overdue — and the one the next wave asks before spawning.
stopped kills the child, not the theorem: it subtracts from
in-flight and not from outstanding. A derivation that left the child in
flight would report the theorem overdue on every later read and take
the deadline arm against a child already written off; one that
subtracted the theorem from the outstanding set would report an
unanswered theorem as settled. The enter record, not this one, is
what names the stopped child's worktree for cleanup.
A duplicate leave is a diagnostic, not a conflict, and the later
one wins. A child written off as lost can report anyway, leaving one
theorem with two leave records. There being one definition per
stage, the replacement carries the same --agent name as the child it
replaced, so the two share a result-file name and there is one file,
the later child's, since its rename overwrote the earlier report. So
the theorem's verdict is the later child's by construction: it is the
verdict in the one file there is to read, and no reader has a tie to
break. Both records stay in the log, because the pair is evidence that
a child believed dead was alive, and the reader reports it as such. No
line is revised, so concurrent appends cannot collide.
A child's hand-back
A child's leave record and result file land before the child
returns, so by the time its final <task-notification> — the one
saying it finished — reaches the caller a missing leave is final
rather than a race. A notification saying the child may still be
running is interim: a child that ends its turn with background work of
its own running wakes when that work exits and carries on, so its
leave can still land. A child therefore makes
its leave call before it composes its hand-back, and composes one only
from what that call did:
-
The call succeeded — the hand-back's first line is the result-file path the call printed, and the report the file holds follows it.
-
The call failed — the hand-back is a failure report carrying no verdict and no theorem, so nothing the caller reads from it can stand in for the result file that was never written:
LEAVE FAILED COMMAND: <the leave command, as run> OUTPUT: <everything it printed, verbatim>
04 同仓库更多 Skills
mask-inappropriate-language
Replace inappropriate language (profanity, slurs, strong insults) in provided text or a file with asterisks, character-for-character, preserving everything else.
theorem-agents-interface
The interface between the sdlc reviewer and the theorem agents it spawns — what each double-dash brief parameter means, and what each consequence class means. Preloaded into every theorem agent (sdlc:theorem-generator, the disprover, and the verifier) via its skills frontmatter, and read by name by the sdlc:theorem-based-pr-reviewer agent for what its briefs' parameters mean; not invoked from the user's slash menu.
sdlc-config-user
Interactively create or merge-update the repo user sdlc config, `<repo-root>/.sdlc/user-config.yml` (tier 3 — this user, this repo, never committed), and add it to the repo's tracked `.gitignore`.
sdlc-config-repo
Interactively create or merge-update the shared repo sdlc config, `<repo-root>/.sdlc/repo-config.yml` (tier 2 — tracked, every user of this repo).
sdlc-config-global
Interactively create or merge-update the global user sdlc config, `$XDG_CONFIG_HOME/sdlc/user-config.yml` (tier 1 — this user, every repo on this machine).
pr-read-cli-interface
The contract for sdlc's PR-read CLIs — sdlc-pr-round, sdlc-pr-adjustments, sdlc-fixer-brief and sdlc-records-chain — their arguments, exit codes and output grammar. Preloaded into sdlc:theorem-based-pr-reviewer, sdlc:issue-fixer, sdlc:docs-writer and sdlc:pr-finalizer via their skills frontmatter; not invoked from the user's slash menu.