nikos 0.0.7 → 0.1.0

package/dist/commands/story.js

@@ -25,6 +25,12 @@ export function newStory(input, dir) {
     if (!activities.includes(input.activity)) {
         throw new Error(`'${input.activity}' is not an activity in storymap.yaml. Activities: ${activities.join(", ") || "none"}`);
     }
+    if (input.step !== undefined) {
+        const steps = ((plain.activities ?? []).find((a) => a?.id === input.activity)?.steps ?? []).map((st) => st?.id);
+        if (!steps.includes(input.step)) {
+            throw new Error(`'${input.step}' is not a step of activity '${input.activity}'. Steps: ${steps.join(", ") || "none (add one with nikos step add)"}`);
+        }
+    }
     const releases = plain.releases ?? [];
     if (!releases.length)
         throw new Error("storymap.yaml has no releases to add the story to");
@@ -44,7 +50,7 @@ export function newStory(input, dir) {
     else
         map.setIn(["releases", index, "stories"], map.createNode([id], { flow: true }));
     state.setIn(["stories", id], state.createNode({ status: "todo" }));
-    const text = `@${id} @release-${release} @${priority} @activity-${input.activity}
+    const text = `@${id} @release-${release} @${priority} @activity-${input.activity}${input.step ? ` @step-${input.step}` : ""}
 Feature: ${title}
 
   As a <who it's for>
@@ -70,12 +76,12 @@ export function runStory(args) {
         return i >= 0 ? rest[i + 1] : undefined;
     };
     if (sub !== "add" || !title || title.startsWith("--") || !opt("activity")) {
-        console.error('Usage: nikos story add "<title>" --activity <id> [--release <n>] [--priority must|should|could]');
+        console.error('Usage: nikos story add "<title>" --activity <id> [--step <id>] [--release <n>] [--priority must|should|could]');
         return 1;
     }
     try {
         const release = opt("release");
-        const r = newStory({ title, activity: opt("activity"), release: release === undefined ? undefined : Number(release), priority: opt("priority") }, opt("dir") ?? process.cwd());
+        const r = newStory({ title, activity: opt("activity"), step: opt("step"), release: release === undefined ? undefined : Number(release), priority: opt("priority") }, opt("dir") ?? process.cwd());
         console.log(`Added ${r.id} to release ${r.release}\nCreated ${r.feature}`);
         console.log(`\nNext: write the user story and its scenarios in the feature file, then run nikos clear ${r.id}.`);
         return 0;

package/dist/commands/validate.js

@@ -6,15 +6,14 @@ import { fileURLToPath } from "node:url";
 import { parse } from "yaml";
 import { lintFeature } from "../lint/gherkin.js";
 import { lintConstitution } from "../lint/constitution.js";
-import { parseBet } from "./bet.js";
-import { featureStoryIds, findIntentDir, read, rel, walk } from "../lib/project.js";
+import { BET_ID, CROSS_REF, planningDir } from "../lib/bets.js";
+import { featureStoryIds, featureTag, findIntentDir, read, rel, walk } from "../lib/project.js";
 const here = dirname(fileURLToPath(import.meta.url));
 // Works from src/ (tests) and dist/ (published): schemas sit at the package root.
 const schemaDir = [join(here, "../../schemas"), join(here, "../schemas")].find((d) => existsSync(d));
 const ajv = new Ajv2020({ allErrors: true, strict: false });
 const checkStorymap = ajv.compile(JSON.parse(read(join(schemaDir, "storymap.schema.json"))));
 const checkState = ajv.compile(JSON.parse(read(join(schemaDir, "state.schema.json"))));
-const checkBet = ajv.compile(JSON.parse(read(join(schemaDir, "bet.schema.json"))));
 function pointer(e) {
     return e.instancePath.replace(/^\//, "").split("/").filter(Boolean).join(".") || "(root)";
 }
@@ -77,9 +76,18 @@ export function validate(start) {
     // Cross-file checks only when both files parsed into objects.
     const mapStories = new Map();
     const activityIds = new Set();
+    // Each step id names its activity; ids are unique across the map so a @step tag is enough.
+    const stepActivity = new Map();
     if (storymap && typeof storymap === "object") {
-        for (const a of storymap.activities ?? [])
+        for (const a of storymap.activities ?? []) {
             activityIds.add(a?.id);
+            for (const st of a?.steps ?? []) {
+                if (stepActivity.has(st?.id)) {
+                    errors.push({ file: "storymap.yaml", message: `step '${st.id}' appears more than once`, hint: "give each step an id of its own across the map" });
+                }
+                stepActivity.set(st?.id, a?.id);
+            }
+        }
         const numbers = [];
         for (const r of storymap.releases ?? []) {
             numbers.push(r?.number);
@@ -132,6 +140,18 @@ export function validate(start) {
         if (storymap && !mapStories.has(id)) {
             errors.push({ file, message: `${id} is not in any release in storymap.yaml` });
         }
+        const step = featureTag(text, "step");
+        if (step && storymap) {
+            const owner = stepActivity.get(step);
+            if (!owner)
+                errors.push({ file, message: `@step-${step} is not a step in storymap.yaml`, hint: "add it under the activity's steps, or fix the tag" });
+            else if (owner !== activity)
+                errors.push({ file, message: `@step-${step} belongs to activity '${owner}', not '${activity}'` });
+        }
+        const release = featureTag(text, "release");
+        if (release && mapStories.has(id) && Number(release) !== mapStories.get(id)) {
+            warnings.push({ file, message: `is tagged @release-${release} but storymap.yaml puts ${id} in release ${mapStories.get(id)}`, hint: `move it with nikos release move ${id} <n>, which keeps both in step` });
+        }
     }
     const stateStories = (state && typeof state === "object" && state.stories) || {};
     if (storymap && state) {
@@ -153,34 +173,29 @@ export function validate(start) {
                 errors.push({ file: "state.yaml", message: `run.queue has unknown story id ${id}` });
         }
     }
-    // Bets: schema, id matches the file name, and every linked story is in the story map.
-    for (const path of walk(join(dir, "bets"), ".md")) {
-        const file = rel(dir, path);
-        let bet;
-        try {
-            bet = parseBet(read(path));
-        }
-        catch (err) {
-            errors.push({ file, message: `front matter isn't valid YAML: ${err.message.split("\n")[0]}` });
-            continue;
-        }
-        if (!bet) {
-            errors.push({ file, message: "has no front matter", hint: "create bets with `nikos bet new`" });
-            continue;
-        }
-        if (!checkBet(bet.meta)) {
-            for (const e of checkBet.errors ?? [])
-                errors.push({ file, message: describe(e, bet.meta) });
-            continue;
-        }
-        if (bet.meta.id !== basename(path, ".md")) {
-            errors.push({ file, message: `id '${bet.meta.id}' doesn't match the file name`, hint: `rename the file to bets/${bet.meta.id}.md` });
-        }
-        if (storymap) {
-            for (const id of bet.meta.stories) {
-                if (!mapStories.has(id))
-                    errors.push({ file, message: `links ${id}, which is not in storymap.yaml` });
+    // Bet links: each names a bet in planning/bets/ or one in another repo (owner/repo#id).
+    if (storymap && typeof storymap === "object") {
+        const betsDir = join(planningDir(dir), "bets");
+        const check = (where, refs) => {
+            for (const ref of Array.isArray(refs) ? refs : []) {
+                if (typeof ref !== "string")
+                    continue;
+                if (CROSS_REF.test(ref))
+                    continue; // another repo's bet: checked for form only, never fetched
+                if (!BET_ID.test(ref)) {
+                    errors.push({ file: "storymap.yaml", message: `${where} names bet '${ref}', which is neither a bet id nor owner/repo#id`, hint: "use a bet id like faster-checkout, or owner/repo#bet-id for another repo's bet" });
+                }
+                else if (!existsSync(join(betsDir, `${ref}.md`))) {
+                    errors.push({ file: "storymap.yaml", message: `${where} names bet '${ref}', which has no planning/bets/${ref}.md`, hint: "create it with `nikos planning bet new`, or fix the name" });
+                }
             }
+        };
+        for (const r of storymap.releases ?? [])
+            check(`release ${r?.number}`, r?.bets);
+        for (const [id, refs] of Object.entries(storymap.story_bets ?? {})) {
+            if (!mapStories.has(id))
+                errors.push({ file: "storymap.yaml", message: `story_bets names ${id}, which is not in any release` });
+            check(id, refs);
         }
     }
     return { dir, errors, warnings, stories: mapStories.size, releases: storymap?.releases?.length ?? 0 };

package/dist/lib/bets.js

@@ -0,0 +1,25 @@
+// Bet links: releases (and, as an override, single stories) in storymap.yaml name
+// the bets they deliver. The bets themselves live in planning/, outside intent/.
+import { dirname, join } from "node:path";
+/** A bet in this repo: lowercase words joined by hyphens. */
+export const BET_ID = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/** A bet or key result in another repo: owner/repo#id. */
+export const CROSS_REF = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[a-z0-9]+(-[a-z0-9]+)*$/;
+export const isBetRef = (ref) => BET_ID.test(ref) || CROSS_REF.test(ref);
+/** The repo's planning/ folder, next to intent/. */
+export const planningDir = (intentDir) => join(dirname(intentDir), "planning");
+/** The bets a story delivers: its own `story_bets` entry, or else its release's `bets`. */
+export function betsFor(map, story) {
+    const release = (map?.releases ?? []).find((r) => (r?.stories ?? []).includes(story));
+    const own = map?.story_bets?.[story];
+    if (Array.isArray(own))
+        return { bets: own, from: "story", release: release?.number };
+    if (release && Array.isArray(release.bets) && release.bets.length)
+        return { bets: release.bets, from: "release", release: release.number };
+    return { bets: [], from: "none", release: release?.number };
+}
+/** Every story that delivers a bet, after story overrides. */
+export function storiesFor(map, bet) {
+    const all = (map?.releases ?? []).flatMap((r) => r?.stories ?? []);
+    return all.filter((s) => betsFor(map, s).bets.includes(bet));
+}

package/dist/lib/frontmatter.js

@@ -0,0 +1,8 @@
+import { parse } from "yaml";
+/** Split a Markdown file into its YAML front matter and body. */
+export function parseFrontMatter(text) {
+    const m = /^---\n([\s\S]*?)\n---\n?/.exec(text);
+    if (!m)
+        return undefined;
+    return { meta: parse(m[1]), body: text.slice(m[0].length) };
+}

package/dist/lib/project.js

@@ -24,6 +24,43 @@ export function rel(dir, path) {
     return relative(dir, path) || path;
 }
 /** Story id tags on the lines above `Feature:`. */
+/** The value of a `@<name>-<value>` tag above `Feature:`, e.g. featureTag(text, "step"). */
+export function featureTag(text, name) {
+    const head = text.split(/^\s*Feature:/m)[0];
+    return new RegExp(`(?:^|\\s)@${name}-([A-Za-z0-9-]+)`).exec(head)?.[1];
+}
+/**
+ * Set (or with value undefined, remove) a `@<name>-<value>` tag above `Feature:`. An existing tag
+ * is replaced where it stands; a new one goes after the tag `after` (e.g. the story id), or last.
+ */
+export function setFeatureTag(text, name, value, after) {
+    const lines = text.split("\n");
+    const at = lines.findIndex((l) => /^\s*Feature:/.test(l));
+    const tagLines = lines.slice(0, at < 0 ? 0 : at).flatMap((l, k) => (l.trim().startsWith("@") ? [k] : []));
+    if (!tagLines.length)
+        throw new Error("The feature has no tag line above Feature:");
+    const isOurs = (t) => t.startsWith(`@${name}-`);
+    const tagsOf = (k) => lines[k].trim().split(/\s+/).filter(Boolean);
+    const write = (k, tags) => (lines[k] = lines[k].match(/^\s*/)[0] + tags.join(" "));
+    const next = value === undefined ? [] : [`@${name}-${value}`];
+    let placed = false;
+    for (const k of tagLines) {
+        const tags = tagsOf(k);
+        const i = tags.findIndex(isOurs);
+        if (i < 0)
+            continue;
+        write(k, [...tags.slice(0, i), ...(placed ? [] : next), ...tags.slice(i + 1).filter((t) => !isOurs(t))]);
+        placed = true;
+    }
+    if (!placed && next.length) {
+        const k = tagLines.find((n) => after && tagsOf(n).includes(`@${after}`)) ?? tagLines[tagLines.length - 1];
+        const tags = tagsOf(k);
+        const j = after ? tags.indexOf(`@${after}`) : -1;
+        tags.splice(j >= 0 ? j + 1 : tags.length, 0, ...next);
+        write(k, tags);
+    }
+    return lines.join("\n");
+}
 export function featureStoryIds(text) {
     const ids = [];
     for (const line of text.split("\n")) {

package/dist/lint/gherkin.js

@@ -5,7 +5,7 @@ import { STORY_ID } from "../lib/project.js";
 const STATUS_TAGS = /^@(todo|done|wip|in[-_]?progress|doing|blocked|needs[-_]?rework|ready|review|approved|complete[d]?|skip|pending)$/i;
 const PRIORITY = /^@(must|should|could)$/;
 const AC_TAG = /^@AC\d+$/;
-const KNOWN_FEATURE_TAG = [STORY_ID, /^release-\d+$/, /^(must|should|could)$/, /^activity-[a-z0-9-]+$/, /^effort-(XS|S|M|L|XL)$/];
+const KNOWN_FEATURE_TAG = [STORY_ID, /^release-\d+$/, /^(must|should|could)$/, /^activity-[a-z0-9-]+$/, /^step-[a-z0-9-]+$/, /^effort-(XS|S|M|L|XL)$/];
 function parser() {
     return new Parser(new AstBuilder(IdGenerator.uuid()), new GherkinClassicTokenMatcher());
 }
@@ -42,7 +42,7 @@ export function lintFeature(text) {
             issues.push({ level: "error", message: `uses status tag ${tag}`, hint: "status lives in state.yaml, not in the feature" });
         }
         else if (!KNOWN_FEATURE_TAG.some((re) => re.test(tag.slice(1)))) {
-            issues.push({ level: "warning", message: `has unrecognised tag ${tag}`, hint: "allowed: story id, @release-N, @must/@should/@could, @activity-<id>, @effort-<size>" });
+            issues.push({ level: "warning", message: `has unrecognised tag ${tag}`, hint: "allowed: story id, @release-N, @must/@should/@could, @activity-<id>, @step-<id>, @effort-<size>" });
         }
     }
     if (tags.filter((t) => PRIORITY.test(t)).length !== 1) {

package/dist/planning/bets.js

@@ -0,0 +1,73 @@
+// Bet cards in planning/bets/<id>.md: what we believe, the key results it should move,
+// when we review it, and every review decision since.
+import { join } from "node:path";
+import { BET_ID } from "../lib/bets.js";
+import { DATE, betText, checkBet, describeErrors, loadBet, paths, today, writePlanning } from "./model.js";
+function checked(meta) {
+    if (!checkBet(meta))
+        throw new Error(`Not a valid bet card: ${describeErrors(checkBet.errors).join("; ")}`);
+    return meta;
+}
+/** Write planning/bets/<id>.md. Never overwrites an existing bet. */
+export function newBet(input, root) {
+    if (!BET_ID.test(input.id))
+        throw new Error(`'${input.id}' is not a bet id (lowercase words joined by hyphens, e.g. faster-checkout)`);
+    if (!input.owner?.trim())
+        throw new Error("A bet needs an owner (--owner)");
+    if (!input.hypothesis?.trim())
+        throw new Error("A bet needs a hypothesis (--hypothesis)");
+    if (!DATE.test(input.reviewOn ?? ""))
+        throw new Error("A bet needs a review date (--review YYYY-MM-DD)");
+    const meta = checked({
+        id: input.id,
+        owner: input.owner.trim(),
+        ...(input.team ? { team: input.team } : {}),
+        hypothesis: input.hypothesis.trim(),
+        krs: { ...(input.primary ? { primary: input.primary } : {}), also: input.also ?? [] },
+        ...(input.starts ? { starts: input.starts } : {}),
+        review_on: input.reviewOn,
+        ...(input.deadline ? { deadline: input.deadline } : {}),
+        confidence: input.confidence ?? "medium",
+        dependencies: input.dependencies ?? [],
+        outcome: "open",
+        reviews: [],
+    });
+    const body = `\n## Why we think so\n${input.evidence?.trim() || "The evidence behind the hypothesis: what we saw, and where."}\n`;
+    return writePlanning(root, join(paths(root).bets, `${input.id}.md`), betText(meta, body), { create: true });
+}
+export const DECISIONS = ["continue", "change", "stop", "complete"];
+/**
+ * Add a dated review decision to a bet. Earlier reviews are kept as they are.
+ * stop sets the outcome to stopped; complete needs the outcome the evidence shows (won or lost).
+ */
+export function reviewBet(root, id, r) {
+    if (!DECISIONS.includes(r.decision))
+        throw new Error(`A review decision is one of ${DECISIONS.join(", ")}`);
+    if (!r.reason?.trim())
+        throw new Error("A review needs a reason (--why)");
+    if (r.decision === "complete" && r.outcome !== "won" && r.outcome !== "lost") {
+        throw new Error("Completing a bet needs its outcome from the key result evidence: --outcome won or --outcome lost");
+    }
+    const bet = loadBet(root, id);
+    const meta = structuredClone(bet.meta);
+    const outcome = r.decision === "stop" ? "stopped" : r.decision === "complete" ? r.outcome : undefined;
+    meta.reviews = [...(meta.reviews ?? []), { date: r.date ?? today(), decision: r.decision, reason: r.reason.trim(), ...(outcome ? { outcome } : {}) }];
+    if (outcome)
+        meta.outcome = outcome;
+    return writePlanning(root, join(paths(root).bets, `${id}.md`), betText(checked(meta), bet.body), { expect: r.expect ?? bet.hash });
+}
+const EDITABLE = ["owner", "team", "hypothesis", "starts", "review_on", "deadline", "confidence", "dependencies", "outcome"];
+/** Change a bet's fields (not its reviews or id). `expect` is the hash of the version being edited. */
+export function editBet(root, id, fields, expect) {
+    const bet = loadBet(root, id);
+    const meta = structuredClone(bet.meta);
+    for (const [k, v] of Object.entries(fields)) {
+        if (!EDITABLE.includes(k))
+            throw new Error(`'${k}' can't be edited here`);
+        if (v === "" || v === null)
+            delete meta[k];
+        else
+            meta[k] = v;
+    }
+    return writePlanning(root, join(paths(root).bets, `${id}.md`), betText(checked(meta), bet.body), { expect: expect ?? bet.hash });
+}

package/dist/planning/cli.js

@@ -0,0 +1,152 @@
+// `nikos planning …`: the command line for the nikos-planning pack.
+import { betIds, findRoot, krIds, loadBet, loadKr, validatePlanning } from "./model.js";
+import { DECISIONS, newBet, reviewBet } from "./bets.js";
+import { checkIn, isStale, latest, newKr, reviseTarget } from "./krs.js";
+import { delivery, describeDelivery } from "./delivery.js";
+import { crossRefs, runSync } from "./upstream.js";
+import { runServe } from "./server.js";
+const help = `nikos planning — bets, key results and the planning dashboard
+
+Usage: nikos planning <command> [options] [--dir <repo>]
+
+Commands:
+  bet new <id>       Write planning/bets/<id>.md
+                     (--owner, --hypothesis, --review YYYY-MM-DD, --kr <primary>, --also <ref>,
+                      --team, --starts, --deadline, --confidence low|medium|high, --dependency, --evidence)
+  bet review <id> <continue|change|stop|complete>  Add a dated review decision (--why, --outcome won|lost)
+  kr new <id>        Write planning/krs/<id>.yaml
+                     (--title, --owner, --baseline, --target, --by YYYY-MM-DD, --unit, --objective,
+                      --aligns-to owner/repo#id, --stale-after <days>)
+  kr target <id> <n> Revise a key result's target; the original is kept
+  checkin <kr> <value>  Add a dated check-in (--note, --evidence, --date)
+  status             Every bet's delivery and outcome, every key result's latest value
+  validate           Check planning/ against its schemas
+  sync [--check]     Fetch the plans in planning/upstream.yaml read-only into .nikos/upstream/
+  serve              Open the local dashboard (--port, --export <file>)`;
+export function parseArgs(args) {
+    const positional = [];
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith("--")) {
+            const name = a.slice(2);
+            const next = args[i + 1];
+            const value = next !== undefined && !next.startsWith("--") ? (i++, next) : "true";
+            flags.set(name, [...(flags.get(name) ?? []), value]);
+        }
+        else
+            positional.push(a);
+    }
+    return { positional, all: (n) => flags.get(n) ?? [], opt: (n) => flags.get(n)?.[0], has: (n) => flags.has(n) };
+}
+const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+const num = (s) => (s === undefined || s.trim() === "" ? NaN : Number(s));
+export function status(root) {
+    const out = [];
+    const bets = betIds(root);
+    out.push(bets.length ? "Bets:" : "Bets: none");
+    for (const id of bets) {
+        const b = loadBet(root, id).meta;
+        out.push(`  ${id} — delivery: ${describeDelivery(delivery(root, id))} · outcome: ${b.outcome} · review on ${b.review_on}`);
+    }
+    const krs = krIds(root);
+    out.push(krs.length ? "Key results:" : "Key results: none");
+    for (const id of krs) {
+        const k = loadKr(root, id).data;
+        const last = latest(k);
+        const u = k.unit ?? "";
+        out.push(`  ${id} — ${k.title}: ${last ? `${last.value}${u} on ${last.date}` : "no check-ins"} (baseline ${k.baseline}${u}, target ${k.target}${u} by ${k.by})${isStale(k) ? " · stale" : ""}`);
+    }
+    return out.join("\n");
+}
+export async function runPlanning(args) {
+    const { positional, all, opt, has } = parseArgs(args);
+    const root = findRoot(opt("dir") ?? process.cwd());
+    const [cmd, sub, id, extra] = positional;
+    try {
+        switch (cmd) {
+            case undefined:
+            case "help":
+                console.log(help);
+                return 0;
+            case "bet":
+                if (sub === "new" && id) {
+                    const path = newBet({
+                        id,
+                        owner: opt("owner") ?? "",
+                        hypothesis: opt("hypothesis") ?? "",
+                        reviewOn: opt("review") ?? "",
+                        team: opt("team"),
+                        starts: opt("starts"),
+                        deadline: opt("deadline"),
+                        primary: opt("kr"),
+                        also: all("also"),
+                        confidence: opt("confidence"),
+                        dependencies: all("dependency"),
+                        evidence: opt("evidence"),
+                    }, root);
+                    console.log(`Wrote ${path}`);
+                    return 0;
+                }
+                if (sub === "review" && id && extra) {
+                    if (!DECISIONS.includes(extra))
+                        throw new Error(`A review decision is one of ${DECISIONS.join(", ")}`);
+                    const path = reviewBet(root, id, { decision: extra, reason: opt("why") ?? "", outcome: opt("outcome") });
+                    console.log(`Wrote ${path}`);
+                    return 0;
+                }
+                break;
+            case "kr":
+                if (sub === "new" && id) {
+                    const path = newKr({
+                        id,
+                        title: opt("title") ?? "",
+                        owner: opt("owner") ?? "",
+                        baseline: num(opt("baseline")),
+                        target: num(opt("target")),
+                        by: opt("by") ?? "",
+                        unit: opt("unit"),
+                        objective: opt("objective"),
+                        alignsTo: opt("aligns-to"),
+                        staleAfterDays: opt("stale-after") ? Number(opt("stale-after")) : undefined,
+                    }, root);
+                    console.log(`Wrote ${path}`);
+                    return 0;
+                }
+                if (sub === "target" && id && extra !== undefined) {
+                    console.log(`Wrote ${reviseTarget(root, id, num(extra))}`);
+                    return 0;
+                }
+                break;
+            case "checkin":
+                if (sub && id !== undefined) {
+                    console.log(`Wrote ${checkIn(root, sub, { value: num(id), note: opt("note"), evidence: opt("evidence"), date: opt("date") })}`);
+                    return 0;
+                }
+                break;
+            case "status":
+                console.log(status(root));
+                return 0;
+            case "validate": {
+                const issues = validatePlanning(root);
+                for (const i of issues)
+                    console.log(`✗ ${i.file}: ${i.message}`);
+                // Unresolved upstream references are reported, never fatal: planning carries on without them.
+                for (const r of crossRefs(root).filter((r) => !r.resolved))
+                    console.log(`? ${r.file}: ${r.ref} is unresolved (not synced or not accessible)`);
+                console.log(issues.length ? `\n${issues.length} ${issues.length === 1 ? "problem" : "problems"} found.` : `✓ planning/ is valid — ${count(betIds(root).length, "bet")}, ${count(krIds(root).length, "key result")}`);
+                return issues.length ? 1 : 0;
+            }
+            case "sync":
+                return await runSync(root, { check: has("check") });
+            case "serve":
+                return await runServe(root, { port: opt("port") ? Number(opt("port")) : undefined, exportTo: opt("export") });
+        }
+        console.error(`Unknown planning command.\n\n${help}`);
+        return 1;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/planning/delivery.js

@@ -0,0 +1,20 @@
+// Delivery status of a bet, worked out from the story map: the stories whose release (or
+// own story_bets) names the bet, and their status in state.yaml. Never stored, never the outcome.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { storiesFor } from "../lib/bets.js";
+import { paths } from "./model.js";
+const yamlAt = (p) => (existsSync(p) ? parse(readFileSync(p, "utf8")) : undefined);
+export function delivery(root, bet) {
+    const intent = paths(root).intent;
+    const map = yamlAt(join(intent, "storymap.yaml"));
+    const state = yamlAt(join(intent, "state.yaml"));
+    const ids = map ? storiesFor(map, bet) : [];
+    const stories = ids.map((id) => ({ id, status: state?.stories?.[id]?.status ?? "todo" }));
+    const done = stories.filter((s) => s.status === "done").length;
+    const releases = [...new Set((map?.releases ?? []).filter((r) => (r?.stories ?? []).some((s) => ids.includes(s))).map((r) => r.number))];
+    const status = !stories.length ? "Not started" : done === stories.length ? "Shipped" : "Building";
+    return { status, done, total: stories.length, stories, releases };
+}
+export const describeDelivery = (d) => d.status === "Building" ? `Building, ${d.done} of ${d.total} done` : d.status === "Shipped" ? `Shipped, ${d.total} of ${d.total} done` : "Not started";

package/dist/planning/krs.js

@@ -0,0 +1,73 @@
+// Key results in planning/krs/<id>.yaml: a baseline, a target and a date, and dated
+// check-ins that are only ever added to. Revising the target keeps the original.
+import { join } from "node:path";
+import { BET_ID } from "../lib/bets.js";
+import { DATE, checkKr, describeErrors, krText, loadKr, paths, today, writePlanning } from "./model.js";
+function checked(data) {
+    if (!checkKr(data))
+        throw new Error(`Not a valid key result: ${describeErrors(checkKr.errors).join("; ")}`);
+    return data;
+}
+export function newKr(input, root) {
+    if (!BET_ID.test(input.id))
+        throw new Error(`'${input.id}' is not a key result id (lowercase words joined by hyphens)`);
+    if (!input.title?.trim())
+        throw new Error("A key result needs a title (--title)");
+    if (!input.owner?.trim())
+        throw new Error("A key result needs an owner (--owner)");
+    if (!Number.isFinite(input.baseline) || !Number.isFinite(input.target))
+        throw new Error("A key result needs a numeric --baseline and --target");
+    if (!DATE.test(input.by ?? ""))
+        throw new Error("A key result needs a date (--by YYYY-MM-DD)");
+    const data = checked({
+        id: input.id,
+        title: input.title.trim(),
+        ...(input.objective ? { objective: input.objective } : {}),
+        owner: input.owner.trim(),
+        ...(input.unit !== undefined ? { unit: input.unit } : {}),
+        baseline: input.baseline,
+        target: input.target,
+        original_target: input.target,
+        by: input.by,
+        ...(input.alignsTo ? { aligns_to: input.alignsTo } : {}),
+        ...(input.staleAfterDays ? { stale_after_days: input.staleAfterDays } : {}),
+        checkins: [],
+    });
+    return writePlanning(root, join(paths(root).krs, `${input.id}.yaml`), krText(data), { create: true });
+}
+/** Add a dated check-in. Earlier check-ins are never changed. */
+export function checkIn(root, id, c) {
+    if (!Number.isFinite(c.value))
+        throw new Error("A check-in needs a numeric value");
+    const kr = loadKr(root, id);
+    const data = structuredClone(kr.data);
+    data.checkins = [
+        ...(data.checkins ?? []),
+        { date: c.date ?? today(), value: c.value, ...(c.note?.trim() ? { note: c.note.trim() } : {}), ...(c.evidence?.trim() ? { evidence: c.evidence.trim() } : {}) },
+    ];
+    return writePlanning(root, join(paths(root).krs, `${id}.yaml`), krText(checked(data)), { expect: c.expect ?? kr.hash });
+}
+/** Move the target. The original target stays recorded. */
+export function reviseTarget(root, id, target, expect) {
+    if (!Number.isFinite(target))
+        throw new Error("A target is a number");
+    const kr = loadKr(root, id);
+    const data = structuredClone(kr.data);
+    data.original_target ??= data.target;
+    data.target = target;
+    return writePlanning(root, join(paths(root).krs, `${id}.yaml`), krText(checked(data)), { expect: expect ?? kr.hash });
+}
+export const latest = (kr) => (kr.checkins?.length ? kr.checkins[kr.checkins.length - 1] : undefined);
+const days = (from, to) => Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000);
+/** Stale when the last check-in (or, with none, nothing at all) is older than stale_after_days (default 14). */
+export function isStale(kr, on = today()) {
+    const last = latest(kr);
+    if (!last)
+        return true;
+    return days(last.date, on) > (kr.stale_after_days ?? 14);
+}
+/** Progress from baseline toward target, 0..1 (can pass 1). Works for targets below the baseline too. */
+export function progress(kr) {
+    const v = latest(kr)?.value ?? kr.baseline;
+    return kr.target === kr.baseline ? 1 : (v - kr.baseline) / (kr.target - kr.baseline);
+}