story.delivery/2
Deliver a planning-store story: implement it, verify the current implementation revision with its tests and the repository's gate, open a pull request for it, read its continuous integration, and merge it under authority. Accepted once the pull request is merged, or abandoned on an explicit decision. Every claim is about the implementation at its current revision, so a new commit returns all of them to unknown. A case fixes whether the tests must fail before the implementation is edited and whether the gate runs once, after the handover, or at every revision; the pull request opens only on a complete change, with test paths and implementation paths both changed and the tests and the gate green at one revision.
- Id:
story.delivery - Revision: 2
- Source:
protocols/story-delivery/2.yaml
Dependency graph
Which actions may produce which evidence, which claims that evidence establishes, and which outcomes and obligations rest on those claims. Hover or focus a node to trace what it rests on.
Protocol · revision 2
story.delivery/2Deliver a planning-store story: implement it, verify the current implementation revision with its tests and the repository's gate, open a pull request for it, read its continuous integration, and merge it under authority. Accepted once the pull request is merged, or abandoned on an explicit decision. Every claim is about the implementation at its current revision, so a new commit returns all of them to unknown. A case fixes whether the tests must fail before the implementation is edited and whether the gate runs once, after the handover, or at every revision; the pull request opens only on a complete change, with test paths and implementation paths both changed and the tests and the gate green at one revision.
- Actions10
- Evidence kinds9
- Claims9
- Outcomes2
- Obligations4
- Claim supports claim
- Precondition, traced on hover
- Needs authority
Hover or focus a node to trace what it rests on and what rests on it. Press Enter to pin it, Escape to clear.
Case inputs
gate_onafter_handovereach_revisionwhen the repository's gate runs; after the handover, it runs only on a revision whose tests pass and whose change is handed over, so once, on the revision that can be handed over, and at every revision it runs whenever askedtests_firstoptionalrequiredwhether the story's tests must fail before the implementation is edited; under required, the implementation is edited only while the tests, once written, fail at the current revision, or while they pass and the gate or continuous integration fails there
Protocol as text
| Name | Description | Rule | Leads to |
|---|---|---|---|
change.handover | hand the change over, changing no file, once it is complete (the story's tests written and the implementation done) and no further edit is needed; takt records the choice, and the pull request is opened for this revision and its continuous integration read once | claim is unknown: change.handed_over effect read | produces handover |
change.read | read whether merging the implementation revision into the base branch's tip would change its tree outside .engineering/, and which paths it changes; taken once the change is handed over | claim change.handed_over effect read | produces change_record; produces paths_changed |
ci.read | read the continuous integration result for the pull request's head; needs the pull request open for the implementation revision | claim pr.opened effect read | produces ci_result |
gate.run | run the repository's gate against an implementation revision; when the case runs the gate after the handover, needs the tests passing and the change handed over at the revision | any of all of claim change.handed_over claim tests.pass input gate_on in each_revision effect read | produces gate_result |
implementation.edit | change the implementation in the repository's working revision; when the case requires its tests first, needs the story's tests written and failing at the current revision, or written, seen failing in a run at the revision of their latest write and observed after it, and passing at the current one with the gate or continuous integration failed there, so a failure no test reads (formatting, lint, another platform) can be fixed | any of all of any of claim is false: ci.green claim is false: gate.green claim tests.pass evidence = fail: test_result since tests_change about implementation claim tests.shown_red input tests_first in optional effect write | — |
pr.open | push the implementation revision, with the commits that record its approval above it when there are any, and open its pull request through the run's forge; needs the tests and the gate green, the change handed over at the revision, a merge of it into the base branch's tip that would change the tip outside .engineering/, so nothing is opened at the seed or for content the base already has, and the change complete, so it opens once, on a revision with both test paths and implementation paths changed | all of claim change.complete claim change.handed_over claim change.made claim gate.green claim tests.pass effect write | produces pull_request |
repository.inspect | read the repository | effect read | — |
repository.merge | merge the pull request into the repository's mainline; needs continuous integration green, the pull request open and authority to merge, never only a connection to the repository host | all of claim ci.green claim pr.opened needs repository.merge effect write | produces merge_observation |
tests.run | run the tests against an implementation revision | effect read | produces test_result |
tests.write | change the tests in the repository's working revision | effect write | produces tests_change |
More columns: swipe horizontally, or focus the table and use the arrow keys.
| Name | Description | Rule | Leads to |
|---|---|---|---|
change_record | whether merging an implementation revision into the base branch's tip would change that tip's tree outside .engineering/; its result is ahead or none | — | establishes change.made (ahead about implementation) |
ci_result | the result of continuous integration on an implementation revision; its result is pass or fail | — | establishes ci.green (pass about implementation) |
gate_result | the result of the repository's gate against an implementation revision; its result is pass or fail | — | establishes gate.green (pass about implementation) |
handover | the harness chose to hand the change over at this implementation revision, with no file changed: takt records the choice from the step, as it records a request for an approval. The record attests a choice, not that the change is correct: the tests, the gate and continuous integration stay validator evidence; it has no result | — | establishes change.handed_over (about implementation) |
merge_observation | the observation that the pull request whose head is an implementation revision, or that revision with only the commits that record its approval above it, was merged; its result is merged | — | establishes pr.merged (merged about implementation) |
paths_changed | which paths an implementation revision changes since the base branch's tip: test paths, implementation paths, both or neither; its result is tests_only, implementation_only, both or none | — | establishes change.complete (both about implementation) |
pull_request | a pull request whose head is an implementation revision, or that revision with only the commits that record its approval above it; its result is open | — | establishes pr.opened (open about implementation) |
test_result | the result of running tests against an implementation revision; its result is pass or fail | — | establishes tests.pass (pass about implementation) |
tests_change | the record that the story's tests were written, moving the implementation to a new revision; it has no result | — | establishes tests.shown_red (not first none about implementation) |
More columns: swipe horizontally, or focus the table and use the arrow keys.
| Name | Description | Rule | Leads to |
|---|---|---|---|
change.complete | the current implementation revision changes both test paths and implementation paths since the base, and its tests pass and its gate is green at that same revision | all of claim gate.green claim tests.pass evidence = both: paths_changed | gates pr.open |
change.handed_over | the harness handed the change over at the current implementation revision, saying it is complete; a new commit returns it to unknown | any evidence: handover | gates change.handover (unknown); gates change.read; gates gate.run; gates pr.open |
change.made | merging the current implementation revision into the base branch's tip would change its tree outside .engineering/: there is a change to publish | evidence = ahead: change_record | gates pr.open |
ci.green | continuous integration passes for the current implementation revision | evidence = pass: ci_result | requires ci.required; gates implementation.edit (false); gates repository.merge |
gate.green | the repository's gate is green for the current implementation revision | evidence = pass: gate_result | supports change.complete; requires gate.required; gates implementation.edit (false); gates pr.open |
pr.merged | the pull request for the current implementation revision is merged | evidence = merged: merge_observation | requires accepted; requires merge.required |
pr.opened | a pull request is open for the current implementation revision | evidence = open: pull_request | gates ci.read; gates repository.merge |
tests.pass | the tests pass for the current implementation revision | evidence = pass: test_result | supports change.complete; supports tests.shown_red (false); requires tests.required; gates gate.run; gates implementation.edit; gates pr.open |
tests.shown_red | the story's tests were written, and they fail at the current implementation revision; a run about an earlier revision, and a run before the tests were written, say nothing, and an edit that moves the implementation to a new revision returns the claim to unknown until the tests are run there. The order form over tests_change with a result no such record has reads whether any tests_change was recorded, at any revision | all of claim is false: tests.pass not first evidence = none: tests_change about implementation | gates implementation.edit |
More columns: swipe horizontally, or focus the table and use the arrow keys.
| Name | Description | Rule | Leads to |
|---|---|---|---|
abandoned | the story closed because it was explicitly abandoned | — | — |
accepted | the story closed with its pull request merged | claim pr.merged | — |
More columns: swipe horizontally, or focus the table and use the arrow keys.
| Name | Description | Rule | Leads to |
|---|---|---|---|
ci.required | continuous integration passes for the current implementation revision | claim ci.green | — |
gate.required | the repository's gate is green for the current implementation revision | claim gate.green | — |
merge.required | the pull request for the current implementation revision is merged | claim pr.merged | — |
tests.required | the tests pass for the current implementation revision | claim tests.pass | — |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Source: protocols/story-delivery/2.yaml
Actions
What can be done in a case: what it needs first, which authority it requires, the class of effect it has and the evidence it may produce.
| Action | Description | Precondition | Requires capability | Effect | May produce |
|---|---|---|---|---|---|
change.handover | hand the change over, changing no file, once it is complete (the story's tests written and the implementation done) and no further edit is needed; takt records the choice, and the pull request is opened for this revision and its continuous integration read once | change.handed_over is UNKNOWN | no authority | read | handover |
change.read | read whether merging the implementation revision into the base branch's tip would change its tree outside .engineering/, and which paths it changes; taken once the change is handed over | change.handed_over is TRUE | no authority | read | change_record, paths_changed |
ci.read | read the continuous integration result for the pull request's head; needs the pull request open for the implementation revision | pr.opened is TRUE | no authority | read | ci_result |
gate.run | run the repository's gate against an implementation revision; when the case runs the gate after the handover, needs the tests passing and the change handed over at the revision | any of (all of (change.handed_over is TRUE; tests.pass is TRUE); input gate_on is one of each_revision) | no authority | read | gate_result |
implementation.edit | change the implementation in the repository's working revision; when the case requires its tests first, needs the story's tests written and failing at the current revision, or written, seen failing in a run at the revision of their latest write and observed after it, and passing at the current one with the gate or continuous integration failed there, so a failure no test reads (formatting, lint, another platform) can be fixed | any of (all of (any of (ci.green is FALSE; gate.green is FALSE); tests.pass is TRUE; a test_result with result fail since the latest tests_change, at its revision, both about implementation); tests.shown_red is TRUE; input tests_first is one of optional) | no authority | write | no evidence |
pr.open | push the implementation revision, with the commits that record its approval above it when there are any, and open its pull request through the run's forge; needs the tests and the gate green, the change handed over at the revision, a merge of it into the base branch's tip that would change the tip outside .engineering/, so nothing is opened at the seed or for content the base already has, and the change complete, so it opens once, on a revision with both test paths and implementation paths changed | all of (change.complete is TRUE; change.handed_over is TRUE; change.made is TRUE; gate.green is TRUE; tests.pass is TRUE) | no authority | write | pull_request |
repository.inspect | read the repository | none | no authority | read | no evidence |
repository.merge | merge the pull request into the repository's mainline; needs continuous integration green, the pull request open and authority to merge, never only a connection to the repository host | all of (ci.green is TRUE; pr.opened is TRUE) | repository.merge | write | merge_observation |
tests.run | run the tests against an implementation revision | none | no authority | read | test_result |
tests.write | change the tests in the repository's working revision | none | no authority | write | tests_change |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Evidence kinds
The kinds of evidence this protocol admits.
| Evidence kind | Description | Produced by | Used by claims |
|---|---|---|---|
change_record | whether merging an implementation revision into the base branch's tip would change that tip's tree outside .engineering/; its result is ahead or none | change.read | change.made |
ci_result | the result of continuous integration on an implementation revision; its result is pass or fail | ci.read | ci.green |
gate_result | the result of the repository's gate against an implementation revision; its result is pass or fail | gate.run | gate.green |
handover | the harness chose to hand the change over at this implementation revision, with no file changed: takt records the choice from the step, as it records a request for an approval. The record attests a choice, not that the change is correct: the tests, the gate and continuous integration stay validator evidence; it has no result | change.handover | change.handed_over |
merge_observation | the observation that the pull request whose head is an implementation revision, or that revision with only the commits that record its approval above it, was merged; its result is merged | repository.merge | pr.merged |
paths_changed | which paths an implementation revision changes since the base branch's tip: test paths, implementation paths, both or neither; its result is tests_only, implementation_only, both or none | change.read | change.complete |
pull_request | a pull request whose head is an implementation revision, or that revision with only the commits that record its approval above it; its result is open | pr.open | pr.opened |
test_result | the result of running tests against an implementation revision; its result is pass or fail | tests.run | tests.pass |
tests_change | the record that the story's tests were written, moving the implementation to a new revision; it has no result | tests.write | no claim |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Claims
Each claim is TRUE, FALSE or UNKNOWN, established from evidence by its predicate. Missing or stale evidence leaves a claim UNKNOWN, never FALSE.
| Claim | Description | True when |
|---|---|---|
change.complete | the current implementation revision changes both test paths and implementation paths since the base, and its tests pass and its gate is green at that same revision | all of (gate.green is TRUE; tests.pass is TRUE; evidence paths_changed with result both about implementation) |
change.handed_over | the harness handed the change over at the current implementation revision, saying it is complete; a new commit returns it to unknown | evidence handover about implementation |
change.made | merging the current implementation revision into the base branch's tip would change its tree outside .engineering/: there is a change to publish | evidence change_record with result ahead about implementation |
ci.green | continuous integration passes for the current implementation revision | evidence ci_result with result pass about implementation |
gate.green | the repository's gate is green for the current implementation revision | evidence gate_result with result pass about implementation |
pr.merged | the pull request for the current implementation revision is merged | evidence merge_observation with result merged about implementation |
pr.opened | a pull request is open for the current implementation revision | evidence pull_request with result open about implementation |
tests.pass | the tests pass for the current implementation revision | evidence test_result with result pass about implementation |
tests.shown_red | the story's tests were written, and they fail at the current implementation revision; a run about an earlier revision, and a run before the tests were written, say nothing, and an edit that moves the implementation to a new revision returns the claim to unknown until the tests are run there. The order form over tests_change with a result no such record has reads whether any tests_change was recorded, at any revision | all of (tests.pass is FALSE; not (the first tests_change about implementation is none)) |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Obligations
What must be done before a case can be complete, and what discharges it. An obligation stays open until its predicate is TRUE; its predicate being UNKNOWN does not discharge it.
| Obligation | Description | Discharged when |
|---|---|---|
ci.required | continuous integration passes for the current implementation revision | ci.green is TRUE |
gate.required | the repository's gate is green for the current implementation revision | gate.green is TRUE |
merge.required | the pull request for the current implementation revision is merged | pr.merged is TRUE |
tests.required | the tests pass for the current implementation revision | tests.pass is TRUE |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Outcomes
The legitimate terminal interpretations of a case, and what each requires.
| Outcome | Description | Requires |
|---|---|---|
abandoned | the story closed because it was explicitly abandoned | decision explicitly_abandoned |
accepted | the story closed with its pull request merged | pr.merged is TRUE |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Artifacts
The things whose revisions evidence is bound to.
| Artifact | Description |
|---|---|
implementation | a revision of the code that realizes the plan |
intent | what the story is meant to achieve |
plan | the intended steps toward the intent |
More columns: swipe horizontally, or focus the table and use the arrow keys.
Case inputs
What a case fixes when it opens: each input takes one of the values listed, and is never UNKNOWN.
| Input | Description | Values |
|---|---|---|
gate_on | when the repository's gate runs; after the handover, it runs only on a revision whose tests pass and whose change is handed over, so once, on the revision that can be handed over, and at every revision it runs whenever asked | after_handover, each_revision |
tests_first | whether the story's tests must fail before the implementation is edited; under required, the implementation is edited only while the tests, once written, fail at the current revision, or while they pass and the gate or continuous integration fails there | optional, required |
More columns: swipe horizontally, or focus the table and use the arrow keys.