@mku1tra/work 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Kelly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/schema.d.ts

@@ -0,0 +1,322 @@
+/**
+ * work: the types of the work, on basis. The work (objectives, issues), the plan that cuts an issue into CLs, and the
+ * cl note that carries one cut to the agents that build it: what is tracked, how it nests and what blocks it. Each type
+ * has a note in types/ that says what each part of its notes holds, and whose body a new note starts from. It holds no
+ * notes: a graph that imports it holds the work, in its own ground. Work can belong to any note.
+ */
+import * as z from "zod";
+export declare const work: Readonly<{
+    name: "work";
+    description: string;
+    abstract: boolean;
+    parents: readonly [];
+    schema: z.ZodObject<{
+        type: z.ZodLiteral<"work">;
+        name: z.ZodString;
+        description: z.ZodString;
+        belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    key: Readonly<readonly [] | never[]>;
+}>;
+export declare const objective: Readonly<{
+    name: "objective";
+    description: string;
+    abstract: boolean;
+    parents: readonly [Readonly<{
+        name: "work";
+        description: string;
+        abstract: boolean;
+        parents: readonly [];
+        schema: z.ZodObject<{
+            type: z.ZodLiteral<"work">;
+            name: z.ZodString;
+            description: z.ZodString;
+            belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        key: Readonly<readonly [] | never[]>;
+    }>];
+    schema: z.ZodObject<{
+        type: z.ZodLiteral<"objective">;
+        name: z.ZodString;
+        description: z.ZodString;
+        belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        status: z.ZodEnum<{
+            draft: "draft";
+            active: "active";
+            archived: "archived";
+            dropped: "dropped";
+        }>;
+    }, z.core.$strict>;
+    key: Readonly<readonly [] | never[]>;
+}>;
+export declare const issue: Readonly<{
+    name: "issue";
+    description: string;
+    abstract: boolean;
+    parents: readonly [Readonly<{
+        name: "work";
+        description: string;
+        abstract: boolean;
+        parents: readonly [];
+        schema: z.ZodObject<{
+            type: z.ZodLiteral<"work">;
+            name: z.ZodString;
+            description: z.ZodString;
+            belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        key: Readonly<readonly [] | never[]>;
+    }>];
+    schema: z.ZodObject<{
+        type: z.ZodLiteral<"issue">;
+        name: z.ZodString;
+        description: z.ZodString;
+        belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        kind: z.ZodEnum<{
+            bug: "bug";
+            "feature-request": "feature-request";
+            "internal-cleanup": "internal-cleanup";
+            vulnerability: "vulnerability";
+            project: "project";
+            epic: "epic";
+            feature: "feature";
+            milestone: "milestone";
+            story: "story";
+            task: "task";
+        }>;
+        priority: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+            P4: "P4";
+        }>;
+        repo: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            dropped: "dropped";
+            new: "new";
+            "in-progress": "in-progress";
+            done: "done";
+        }>;
+    }, z.core.$strict>;
+    key: Readonly<readonly [] | never[]>;
+}>;
+export declare const plan: Readonly<{
+    name: "plan";
+    description: string;
+    abstract: boolean;
+    parents: readonly [];
+    schema: z.ZodObject<{
+        type: z.ZodLiteral<"plan">;
+        name: z.ZodString;
+        description: z.ZodString;
+        belongsTo: z.ZodString;
+        status: z.ZodEnum<{
+            draft: "draft";
+            active: "active";
+            dropped: "dropped";
+            done: "done";
+            review: "review";
+        }>;
+    }, z.core.$strict>;
+    key: Readonly<readonly [] | never[]>;
+}>;
+export declare const cl: Readonly<{
+    name: "cl";
+    description: string;
+    abstract: boolean;
+    parents: readonly [];
+    schema: z.ZodObject<{
+        type: z.ZodLiteral<"cl">;
+        name: z.ZodString;
+        description: z.ZodString;
+        belongsTo: z.ZodString;
+        phase: z.ZodOptional<z.ZodNumber>;
+        repo: z.ZodOptional<z.ZodString>;
+        shape: z.ZodOptional<z.ZodObject<{
+            change: z.ZodEnum<{
+                behavior: "behavior";
+                structure: "structure";
+            }>;
+            checked: z.ZodEnum<{
+                repo: "repo";
+                system: "system";
+            }>;
+        }, z.core.$strip>>;
+        checkout: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        test: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            dropped: "dropped";
+            new: "new";
+            "in-progress": "in-progress";
+            done: "done";
+        }>;
+    }, z.core.$strict>;
+    key: Readonly<readonly [] | never[]>;
+}>;
+/** A plan's phases are its cls' `phase`, and they run 1, 2, 3 with no gap, so each cl has one. */
+export declare const phases: import("@mku1tra/basis").Rule;
+/** A plan is named for its issue: `<issue>-plan`. */
+export declare const planName: import("@mku1tra/basis").Rule;
+/** A cl is named for its issue and its cut: `<issue>-<cut>`, whether it belongs to the issue's plan or to the issue. */
+export declare const clName: import("@mku1tra/basis").Rule;
+declare const schema: import("@mku1tra/basis").Schema<{
+    readonly work: Readonly<{
+        name: "work";
+        description: string;
+        abstract: boolean;
+        parents: readonly [];
+        schema: z.ZodObject<{
+            type: z.ZodLiteral<"work">;
+            name: z.ZodString;
+            description: z.ZodString;
+            belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        key: Readonly<readonly [] | never[]>;
+    }>;
+    readonly objective: Readonly<{
+        name: "objective";
+        description: string;
+        abstract: boolean;
+        parents: readonly [Readonly<{
+            name: "work";
+            description: string;
+            abstract: boolean;
+            parents: readonly [];
+            schema: z.ZodObject<{
+                type: z.ZodLiteral<"work">;
+                name: z.ZodString;
+                description: z.ZodString;
+                belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            key: Readonly<readonly [] | never[]>;
+        }>];
+        schema: z.ZodObject<{
+            type: z.ZodLiteral<"objective">;
+            name: z.ZodString;
+            description: z.ZodString;
+            belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            status: z.ZodEnum<{
+                draft: "draft";
+                active: "active";
+                archived: "archived";
+                dropped: "dropped";
+            }>;
+        }, z.core.$strict>;
+        key: Readonly<readonly [] | never[]>;
+    }>;
+    readonly issue: Readonly<{
+        name: "issue";
+        description: string;
+        abstract: boolean;
+        parents: readonly [Readonly<{
+            name: "work";
+            description: string;
+            abstract: boolean;
+            parents: readonly [];
+            schema: z.ZodObject<{
+                type: z.ZodLiteral<"work">;
+                name: z.ZodString;
+                description: z.ZodString;
+                belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            key: Readonly<readonly [] | never[]>;
+        }>];
+        schema: z.ZodObject<{
+            type: z.ZodLiteral<"issue">;
+            name: z.ZodString;
+            description: z.ZodString;
+            belongsTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            kind: z.ZodEnum<{
+                bug: "bug";
+                "feature-request": "feature-request";
+                "internal-cleanup": "internal-cleanup";
+                vulnerability: "vulnerability";
+                project: "project";
+                epic: "epic";
+                feature: "feature";
+                milestone: "milestone";
+                story: "story";
+                task: "task";
+            }>;
+            priority: z.ZodEnum<{
+                P0: "P0";
+                P1: "P1";
+                P2: "P2";
+                P3: "P3";
+                P4: "P4";
+            }>;
+            repo: z.ZodOptional<z.ZodString>;
+            status: z.ZodEnum<{
+                dropped: "dropped";
+                new: "new";
+                "in-progress": "in-progress";
+                done: "done";
+            }>;
+        }, z.core.$strict>;
+        key: Readonly<readonly [] | never[]>;
+    }>;
+    readonly plan: Readonly<{
+        name: "plan";
+        description: string;
+        abstract: boolean;
+        parents: readonly [];
+        schema: z.ZodObject<{
+            type: z.ZodLiteral<"plan">;
+            name: z.ZodString;
+            description: z.ZodString;
+            belongsTo: z.ZodString;
+            status: z.ZodEnum<{
+                draft: "draft";
+                active: "active";
+                dropped: "dropped";
+                done: "done";
+                review: "review";
+            }>;
+        }, z.core.$strict>;
+        key: Readonly<readonly [] | never[]>;
+    }>;
+    readonly cl: Readonly<{
+        name: "cl";
+        description: string;
+        abstract: boolean;
+        parents: readonly [];
+        schema: z.ZodObject<{
+            type: z.ZodLiteral<"cl">;
+            name: z.ZodString;
+            description: z.ZodString;
+            belongsTo: z.ZodString;
+            phase: z.ZodOptional<z.ZodNumber>;
+            repo: z.ZodOptional<z.ZodString>;
+            shape: z.ZodOptional<z.ZodObject<{
+                change: z.ZodEnum<{
+                    behavior: "behavior";
+                    structure: "structure";
+                }>;
+                checked: z.ZodEnum<{
+                    repo: "repo";
+                    system: "system";
+                }>;
+            }, z.core.$strip>>;
+            checkout: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            test: z.ZodOptional<z.ZodString>;
+            status: z.ZodEnum<{
+                dropped: "dropped";
+                new: "new";
+                "in-progress": "in-progress";
+                done: "done";
+            }>;
+        }, z.core.$strict>;
+        key: Readonly<readonly [] | never[]>;
+    }>;
+}, readonly []>;
+export default schema;

package/dist/schema.js

@@ -0,0 +1,179 @@
+/**
+ * work: the types of the work, on basis. The work (objectives, issues), the plan that cuts an issue into CLs, and the
+ * cl note that carries one cut to the agents that build it: what is tracked, how it nests and what blocks it. Each type
+ * has a note in types/ that says what each part of its notes holds, and whose body a new note starts from. It holds no
+ * notes: a graph that imports it holds the work, in its own ground. Work can belong to any note.
+ */
+import { defineRule, defineSchema, defineType, manyOrNone, one, } from "@mku1tra/basis";
+import * as z from "zod";
+export const work = defineType({
+    name: "work",
+    description: "A tracked piece of work: where it belongs, and what blocks it. Abstract: a note is of a type that inherits it.",
+    abstract: true,
+    fields: {
+        // The one note this is part of, of any type: other work, or a note about the thing it changes, often in another
+        // repo. It is the roll-up, not the folder. A plain string, as "[[name]]", so Obsidian still follows it: the graph
+        // that holds the work lints alone, so the lint cannot see a note of another repo, and it does not check this.
+        belongsTo: z.string().nullable().optional(),
+        // What this cannot finish without. Only the obvious dependencies; review catches the implicit ones. The return type
+        // is said: objective and issue inherit work, so TypeScript cannot infer a type that names itself.
+        dependsOn: manyOrNone(() => [objective, issue]),
+    },
+});
+export const objective = defineType({
+    name: "objective",
+    description: "An end state to reach, with about three key results that show it is reached; issues hang under it. One is active at a time. The key results live in the body.",
+    parents: [work],
+    fields: {
+        status: z
+            .enum(["draft", "active", "archived", "dropped"])
+            .describe("draft: being written. active: the one being worked toward. archived: reached, or no longer current. dropped: abandoned"),
+    },
+});
+export const issue = defineType({
+    name: "issue",
+    description: "A tracked piece of work, from a bug to a project; every CL points to one. Its kind says which.",
+    parents: [work],
+    fields: {
+        kind: z
+            .enum([
+            "bug",
+            "feature-request",
+            "internal-cleanup",
+            "vulnerability",
+            "project",
+            "epic",
+            "feature",
+            "milestone",
+            "story",
+            "task",
+        ])
+            .describe("What the work is (Google Issue Tracker's types). A problem: bug, feature-request, internal-cleanup, vulnerability. A piece of work, big to small: project, epic, feature, milestone, story, task"),
+        priority: z
+            .enum(["P0", "P1", "P2", "P3", "P4"])
+            .describe("How soon it needs doing: P0, now at any cost, to P4, eventually. P2 is the default"),
+        // The repo the work changes, as "[[name]]" of its note: a plain string, as belongsTo is, since the repo's note is
+        // outside the graph that holds the work, and its lint cannot see it.
+        repo: z.string().optional(),
+        status: z
+            .enum(["new", "in-progress", "done", "dropped"])
+            .describe("new: not started. in-progress: claimed, being worked on. done: met, verified, proven where it runs and validated by a person; a controller reaches only verified, so it never sets done. dropped: abandoned, kept for history"),
+    },
+});
+export const plan = defineType({
+    name: "plan",
+    description: "The refinement of one issue, written as an argument: how its cls, in phases, meet the issue's done. Only when the issue takes more than one CL. Draft while it is cut, active once plan-review passes it.",
+    fields: {
+        // The issue it plans.
+        belongsTo: one(() => issue),
+        status: z
+            .enum(["draft", "review", "active", "done", "dropped"])
+            .describe("draft: being cut. review: handed in, waiting for plan-review, and for a person's sign-off when the operator asks for one. active: passed, the cut in force. done: the issue's check is met. dropped: abandoned, kept for history"),
+    },
+});
+export const cl = defineType({
+    name: "cl",
+    description: "The spec of one cut, the CL that builds it, as a contract: its check is what it ensures, its phase what it requires, its seam what it keeps. Its shape, checkout and test command are data; its intent, check, seam and the description of its checkout are prose. The note holds the spec only: what happens to it (its state, attempts, results and findings) is the controller's record, keyed by its name. new once written, done once the CL lands.",
+    fields: {
+        // The plan it is a cut of, or the issue itself when the issue takes one CL.
+        belongsTo: one(() => [plan, issue]),
+        phase: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("Its phase in its plan, from 1: the phases run in order, and the cls of one phase need nothing from each other. None when it is the issue's lone cl"),
+        repo: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The repo it changes, by its folder's name: one of its issue's. A CL lands in one repo, so a change across repos is a cl per repo. None when its issue changes one repo"),
+        shape: z
+            .object({
+            change: z
+                .enum(["behavior", "structure"])
+                .describe("behavior: its check fails before and passes after. structure: its check passes before and after"),
+            checked: z
+                .enum(["repo", "system"])
+                .describe("where its check runs: in the repo, or on the running system"),
+        })
+            .optional()
+            .describe("What the change is, and where its check runs"),
+        checkout: z
+            .array(z.string().min(1))
+            .min(1)
+            .optional()
+            .describe("The paths its builders get on disk, from its repo's root, as git sparse-checkout patterns: a file, or a folder for all under it. Every path conceivably relevant to the cut, so they start from what the planner found, and its Checkout section says what each is"),
+        test: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The command its checks run: its new test files and the existing ones that test what it changes"),
+        status: z
+            .enum(["new", "in-progress", "done", "dropped"])
+            .describe("new: written, not started. in-progress: its CL is being built. done: its CL landed. dropped: abandoned, kept for history"),
+    },
+});
+/** A plan's phases are its cls' `phase`, and they run 1, 2, 3 with no gap, so each cl has one. */
+export const phases = defineRule({
+    name: "phases",
+    description: "A plan's cls each have a phase, and the phases run from 1 with no gap.",
+    on: plan,
+    check: (node, graph) => {
+        const cls = graph.all(cl).filter((c) => c.belongsTo === node.name);
+        const none = cls.filter((c) => c.phase === undefined).map((c) => c.name);
+        const have = new Set(cls.flatMap((c) => (c.phase === undefined ? [] : [c.phase])));
+        const missing = [...Array(Math.max(0, ...have)).keys()]
+            .map((i) => i + 1)
+            .filter((p) => !have.has(p));
+        return [
+            ...(none.length
+                ? [{ message: `its cls with no phase: ${none.join(", ")}` }]
+                : []),
+            ...(missing.length
+                ? [
+                    {
+                        message: `its phases have a gap: no cl in phase ${missing.join(", ")}`,
+                    },
+                ]
+                : []),
+        ];
+    },
+});
+/** A plan is named for its issue: `<issue>-plan`. */
+export const planName = defineRule({
+    name: "plan-name",
+    description: "A plan is named <issue>-plan, for the issue it belongs to.",
+    on: plan,
+    check: (node) => node.name === `${node.belongsTo}-plan`
+        ? []
+        : [
+            {
+                message: `a plan of ${node.belongsTo} is named ${node.belongsTo}-plan`,
+            },
+        ],
+});
+/** A cl is named for its issue and its cut: `<issue>-<cut>`, whether it belongs to the issue's plan or to the issue. */
+export const clName = defineRule({
+    name: "cl-name",
+    description: "A cl is named <issue>-<cut>, for the issue it belongs to through its plan, or directly.",
+    on: cl,
+    check: (node, graph) => {
+        const issueName = graph.get(node.belongsTo, plan)?.belongsTo ?? node.belongsTo;
+        return node.name.startsWith(`${issueName}-`) &&
+            node.name !== `${issueName}-plan`
+            ? []
+            : [{ message: `a cl of ${issueName} is named ${issueName}-<cut>` }];
+    },
+});
+// Named, then exported: tsc does not rewrite the `.ts` of an import() inside `export default`'s expression, so the
+// built package would import a file it does not ship.
+const schema = defineSchema({
+    name: "work",
+    description: "The work: what is tracked, how it nests, and what blocks it.",
+    types: { work, objective, issue, plan, cl },
+    rules: [phases, planName, clName],
+    typeNotes: new URL("../types/", import.meta.url),
+    exports: () => import("./schema.js"),
+});
+export default schema;

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@mku1tra/work",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/matta-kelly/assembly.git",
+    "directory": "work"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/schema.d.ts",
+      "default": "./dist/schema.js"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "!types/basis.config.ts"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@mku1tra/basis": "^0.30.0",
+    "zod": "^4.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types/cl.md

@@ -0,0 +1,32 @@
+---
+type: type
+---
+The cut's intent, in one line: one sentence of done, said as what is true after its CL lands.
+
+---
+## 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
+
+## Seam
+
+What it keeps: the decision the cut hides from the other cls, what it must not change, and what crosses to them: the names, types and shapes the other side reads.
+
+## Checkout
+
+The cl's context on disk: its `checkout` is the paths its builders get, as a git sparse checkout, so they start from what the planner already found and spend no turns finding it. It fences exploration, not edits.
+
+- the paths: every file or folder conceivably relevant to the cut. Err wide: an extra path costs tokens, a missing one costs a raise
+- each path: one line, what it is and why it is here: "`orchestrator/ledger.ts`: the ledger, where an attempt's record is kept"
+- the exemplar: one file in the checkout its builders should write like, since a model of good code in the repo carries further than any rule
+- a fact from outside the code: a probe's output or a doc, written here with its source
+- a gap: a raise, not a search. A builder that needs a path the checkout does not hold raises it and stops, and the planner widens the checkout

package/types/issue.md

@@ -0,0 +1,29 @@
+---
+type: type
+---
+What this issue gets done, in one line: one sentence of done, said as what is true after.
+
+---
+## Intent
+
+The work, shaped: the problem it answers and the rough form of the answer, solved enough to see whole and bounded enough to know where it stops (shaping: Singer, *Shape Up*, 2019). The main elements and how they connect, never the details, which are the plan's.
+
+What validation (was it the right thing) is judged against. Every plan, CL and result is validated against it, and where one disagrees, the intent wins. It is never criteria: no list of done captures a need in full, and the gap is why the intent wins, and why a person validates.
+
+## 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)).
+
+- 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
+	- 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
+	- 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
+
+## Non-goals
+
+What this issue will not do, said plainly. The fence for review: work past it is scope the issue did not ask for, and a shrink inside it is a raise, never quiet.

package/types/objective.md

@@ -0,0 +1,17 @@
+---
+type: type
+---
+The end state, in one line.
+
+An objective and its key results: where to go, and how to tell you are getting there ([re:Work](https://rework.withgoogle.com/intl/en/guides/set-goals-with-okrs)). Fill it in over this guide.
+
+- objective: an end state, obvious to an outsider whether it was met. "ship feature Y", not "keep doing X"
+- key results: about 3, each measurable, each an outcome, not an activity
+- one active at a time
+- status: draft, active, archived, dropped
+- issues hang under it by `belongsTo`
+- not a to-do list
+
+---
+## Key results
+-

package/types/plan.md

@@ -0,0 +1,25 @@
+---
+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.
+
+---
+## 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
+- 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
+- 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
+	- [[<issue>-<cut>]]: what it hides, and what crosses to the others
+- Phase 2: what it builds, and what it needs from phase 1
+	- [[<issue>-<cut>]]: what it hides, and what crosses to the others
+
+## 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.

package/types/work.md

@@ -0,0 +1,4 @@
+---
+type: type
+---
+

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.