@mku1tra/work 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mku1tra/work",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The types of the work, on basis: objective, issue, plan and cl, each with a type note that says what each part of its notes holds.",
   "license": "MIT",
   "repository": {

package/types/cl.md

@@ -6,16 +6,15 @@ The cut's intent, in one line: one sentence of done, said as what is true after
 ---
 ## Check
 
-What it ensures: its promises, each one a future test ([[changelist#Behavior]]). Each promise can fail: a promise nothing could break is no check.
-
-- behavior: given, when, then. It fails before the change and passes after
-- structure: what stays green before and after, by its test files. When the tests themselves are what changes, the code stays as it is, and the mutation score holds
-- a seam it creates: a promise that the seam holds, at its surface
-- a Done item it completes: that item's test, which this cl writes red first ([[kinetic#Policy]], the promise rule)
-- the whole behavior: a cut that asks an outside thing, waits, or says why it did a thing has a promise for each ([[code#Running]]). A promise left out is built by nobody, so the review finds it after the code
-	- the failed ask: what happens when the outside thing fails, or does not answer
-	- the limit: how long a wait may last, and what passing it does
-	- the record: where a reason or a result is kept, and who reads it there
+The cl's promises ([[terms#promise]]): what is true once it lands, each an outcome at the cut's boundary that can fail. Few, each at the altitude of its source. The cases are its tester's, and the build inside the boundary is its builders'.
+
+- a promise: one outcome, said as what holds and for whom. Never how it is built, never an input or a test to write: a line that reads as a test case is a case written too soon ([[terms#case]])
+- its source: what it serves, which sets the kind of its test ([[terms#promise]], its altitude)
+	- an issue's promise it completes: its test, written red first by this cl, at the system altitude ([[kinetic#Policy]], the promise rule)
+	- a seam it creates: the promise that the seam holds, at its surface
+	- its own intent: a unit promise, where its logic is decided
+- by shape ([[terms#shape]]): behavior, each promise false before and true after; structure, each promise true before and after, by the test files that pin it
+- an outside thing: a cut that asks one, or waits on one, promises what holds when it fails, how long a wait may last, and where the reason is kept. These are outcomes the design decides, so they are promises; how the failure is caught is a case
 
 ## Seam
 

package/types/issue.md

@@ -12,17 +12,18 @@ What validation (was it the right thing) is judged against. Every plan, CL and r
 
 ## Done
 
-The state that meets the intent: what verification (was it built right) is judged against. The top of the V for one piece of work: a [[plan]] refines it into cls, every CL points to it by name ("Updates <name>" for a step, "Fixes <name>" on the last), and acceptance checks it on the way up ([Google Issue Tracker](https://developers.google.com/issue-tracker/concepts/issues)).
+The issue's promises ([[terms#promise]]), at the system altitude: the state that meets the intent, what verification (was it built right) is judged against. The top of the V for one piece of work: a [[plan]] refines it into cls, every CL points to it by name ("Updates <name>" for a step, "Fixes <name>" on the last), and acceptance checks it on the way up ([Google Issue Tracker](https://developers.google.com/issue-tracker/concepts/issues)).
 
 - a state, not an activity: "X is true", never "do X"
-- it can fail: a claim nothing could falsify is no check
-- it says where it is checked, set by where the claim lives and how long it must hold
+- it can fail: a promise nothing could falsify is no check
+- an outcome the whole shows, never a part of the build: how the work is cut is the plan's
+- it says where it is checked, set by where the promise lives and how long it must hold
 	- in the code, from then on: the acceptance test, on main. CI keeps it from then on
 		- one CL: that CL's tests, in its cl note
-		- more than one CL: each item's test, carried by the cl that completes it ([[kinetic#Policy]], the promise rule). The [[plan]] names that cl
+		- more than one CL: each promise's test, carried by the cl that completes it ([[kinetic#Policy]], the promise rule). The [[plan]] names that cl
 	- in the running system, once: proven where it runs, read from the running system after deploy (a request, a query, a log line). Main proves the code, not the fleet. Skipped only for code that runs nowhere
-	- in the running system, from then on: kept, by a monitor that keeps checking it, and where it alerts. Only when the claim can break again after met
-- the test of a good list: someone who did not write it can check every item without asking
+	- in the running system, from then on: kept, by a monitor that keeps checking it, and where it alerts. Only when the promise can break again after met
+- the test of a good list: someone who did not write it can check every promise without asking
 
 ## Non-goals
 

package/types/plan.md

@@ -1,18 +1,19 @@
 ---
 type: type
 ---
-The approach, in one or two sentences: how the cls, in order, meet the issue's Done. A known way to cut a kind of change gives a ready order ([[playbook#Cutting a change]]); when none fits, build one, and say so.
+The approach, in one or two sentences: how the cls, in order, keep the issue's promises. A known way to cut a kind of change gives a ready order ([[playbook#Cutting a change]]); when none fits, build one, and say so.
 
 ---
 ## Phases
 
-The refinement of the issue: the cls replace its Done with smaller specs, and the phases show how they combine, so that meeting all of them meets the issue (stepwise refinement: Wirth, 1971; Lamport, *A Science of Concurrent Programs*, ch. 6). Dependent CLs are split and ordered "at a high level before diving into coding" ([Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)), because "a bad line of a plan could lead to hundreds of bad lines of code" ([HumanLayer](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md)).
-- a phase: a group of cls that need nothing from each other, so they can be built side by side: no two change the same code, and none requires another's ensures. Two cls that must change the same code go in different phases, and each phase's reason says why its cls stay apart. Order is only between phases: a phase starts once every cl of the phases before it has landed (a partial order: Lamport, 1978). Inside a phase, cls are parallel, or a set (the same change in many places: SWE at Google, ch. 22). Each cl holds its `phase`, and this list names the same cls in the same phases
+The refinement of the issue: the cls replace its promises with smaller ones ([[terms#promise]]), and the phases show how they combine, so that meeting all of them meets the issue (stepwise refinement: Wirth, 1971; Lamport, *A Science of Concurrent Programs*, ch. 6). Dependent CLs are split and ordered "at a high level before diving into coding" ([Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)), because "a bad line of a plan could lead to hundreds of bad lines of code" ([HumanLayer](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md)).
+- a phase: a group of cls that need nothing from each other, so they can be built side by side: no two change the same code, and none needs what another promises. Two cls that must change the same code go in different phases, and each phase's reason says why its cls stay apart. Order is only between phases: a phase starts once every cl of the phases before it has landed (a partial order: Lamport, 1978). Inside a phase, cls are parallel, or a set (the same change in many places: SWE at Google, ch. 22). Each cl holds its `phase`, and this list names the same cls in the same phases
 - a hard line: where a cut must fall, whatever the design. A cl lands in one repo, through one review, and ships alone, so a part in another repo, for another reviewer or deployed apart is its own cut. Work that is not code (access, accounts, shares) is no cut: it is a step done by hand, checked by a read
-- a cut: the cls meet at seams, each an interface between cuts: what one side promises the other, and what neither touches. Cut along decisions hidden behind an interface, not along the steps of a flow ([Parnas, 1972](https://dl.acm.org/doi/10.1145/361598.361623))
-- a cl ([[cl]]): a contract: what it ensures, requires and must keep. It has its own intent and a check that can fail, fits one review, and leaves main working once it lands ([[changelist#Good CL]]). If you can't write a cut's check, the cut is wrong
-- the proof: every Done item is met by a cl, and every cl meets one. A cl that meets nothing is scope the issue did not ask for. A seam's promise is in the Check of the cl that creates the seam, and each Done item's test in the Check of the cl that completes it ([[kinetic#Policy]], the promise rule)
-- every claim stands on shown ground: the code or a probe's output, never a summary of them
+- a cut: the cls meet at seams ([[terms#seam]]), each an interface between cuts: what one side promises the other, and what neither touches. Cut along decisions hidden behind an interface, not along the steps of a flow ([Parnas, 1972](https://dl.acm.org/doi/10.1145/361598.361623))
+- a cl ([[cl]]): a contract: its promises, its phase and its seam. It has its own intent and promises that can fail, fits one review, and leaves main working once it lands ([[changelist#Good CL]]). If you can't write a cut's promises, the cut is wrong
+- the boundary: the plan stops at each cut's surface. It names the seams and what each cl promises, never the cases or the build inside, which are its builders'
+- the proof: every promise of the issue is kept by a cl, and every cl serves one. A cl that serves nothing is scope the issue did not ask for. A seam's promise is in the Check of the cl that creates the seam, and each issue promise's test in the Check of the cl that completes it ([[kinetic#Policy]], the promise rule)
+- every assumption stands on shown ground: the code or a probe's output, never a summary of them
 - the list: a line for each phase, what it builds and why it comes where it does, and under it a line for each of its cls, what it hides and what crosses to the others
 
 - Phase 1: what it builds, and why it comes first
@@ -22,4 +23,4 @@ The refinement of the issue: the cls replace its Done with smaller specs, and th
 
 ## Does not fit
 
-What could not be made to fit, said plainly: a seam it could not prove, a cut it could not check, a Done item no cl meets. Removed when everything fits. plan-review judges the plan against the issue's Intent and Done before any cl starts, and reads this first, because it is where forcing shows up. The plan is done when its issue is met, not when its last cl lands.
+What could not be made to fit, said plainly: a seam it could not prove, a cut it could not check, an issue promise no cl keeps. Removed when everything fits. plan-review judges the plan against the issue's Intent and promises before any cl starts, and reads this first, because it is where forcing shows up. The plan is done when its issue is met, not when its last cl lands.