nikos 0.1.0 → 0.2.0

package/dist/commands/release.d.ts

@@ -0,0 +1,66 @@
+import { type ValidationResult } from "./validate.js";
+/** Add the next numbered release, with no stories yet. */
+export declare function addRelease(input: {
+    title: string;
+    goal?: string;
+}, dir: string): {
+    number: number;
+    validation: ValidationResult;
+};
+/** Change a release's title and/or goal. An empty goal removes it. */
+export declare function renameRelease(input: {
+    number: number;
+    title?: string;
+    goal?: string;
+}, dir: string): {
+    number: number;
+    validation: ValidationResult;
+};
+/** Move a story to another release (to the end of its build order), keeping its feature tag in step. */
+export declare function moveStory(input: {
+    id: string;
+    to: number;
+}, dir: string): {
+    id: string;
+    from: number;
+    to: number;
+    validation: ValidationResult;
+};
+/** Remove an empty release and renumber the ones after it, retagging their stories. */
+export declare function removeRelease(input: {
+    number: number;
+}, dir: string): {
+    number: number;
+    title: string;
+    validation: ValidationResult;
+};
+/** Move a release to a new position and renumber them all from 1, retagging every story that moved. */
+export declare function reorderRelease(input: {
+    number: number;
+    to: number;
+}, dir: string): {
+    order: {
+        number: number;
+        title: string;
+    }[];
+    validation: ValidationResult;
+};
+export interface ReleaseCheck {
+    number: number;
+    title: string;
+    ready: boolean;
+    /** "4 of 6 done · 2 approved · 1 cancelled" */
+    summary: string;
+    /** What stands between the release and shipping, one line per problem. */
+    gaps: string[];
+}
+/**
+ * Is a release ready to ship? Every story that isn't cancelled must be done (or approved), not
+ * blocked, have scenarios, and still match the feature it was done against; its dependencies
+ * outside the release must be done too. With run, each done story's scenarios run again.
+ */
+export declare function checkRelease(input: {
+    number: number;
+    run?: boolean;
+}, dir: string): ReleaseCheck;
+export declare function runRelease(args: string[]): number;

package/dist/commands/release.js

@@ -1,7 +1,11 @@
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { store } from "../lib/store.js";
+import { dirname, join } from "node:path";
 import { isMap, isSeq, parseDocument } from "yaml";
-import { featureStoryIds, findIntentDir, read, setFeatureTag, walk } from "../lib/project.js";
+import { featureStoryIds, findIntentDir, isDone, read, setFeatureTag, walk } from "../lib/project.js";
+import { storyMapOf } from "./map.js";
+import { resolveSettings } from "../lib/settings.js";
+import { failingScenarios } from "./state.js";
+import { verify } from "./verify.js";
 import { validate } from "./validate.js";
 const yamlOpts = { lineWidth: 0, flowCollectionPadding: false };
 function open(dir) {
@@ -33,11 +37,23 @@ function retag(intentDir, moved) {
         const text = read(file);
         const id = featureStoryIds(text)[0];
         if (id && moved.has(id))
-            writeFileSync(file, setFeatureTag(text, "release", String(moved.get(id)), id));
+            store().write(file, setFeatureTag(text, "release", String(moved.get(id)), id));
     }
 }
+/** Number the releases 1, 2, 3… in list order, retagging the stories of any that changed. */
+function renumber(o) {
+    const moved = new Map();
+    o.releases.items.forEach((item, i) => {
+        if (numberOf(item) === i + 1)
+            return;
+        item.set("number", i + 1);
+        for (const id of storiesOf(item))
+            moved.set(id, i + 1);
+    });
+    retag(o.intentDir, moved);
+}
 function save(o) {
-    writeFileSync(o.mapPath, o.map.toString(yamlOpts));
+    store().write(o.mapPath, o.map.toString(yamlOpts));
     return validate(o.intentDir);
 }
 const cleanTitle = (title) => {
@@ -46,12 +62,19 @@ const cleanTitle = (title) => {
         throw new Error("A release needs a title");
     return t;
 };
+/** Refuse a title another release already has (ignoring case), so two releases can't share a name. */
+function uniqueTitle(o, title, except) {
+    const taken = o.releases.items.find((r) => r !== except && String(r.get("title")).trim().toLowerCase() === title.toLowerCase());
+    if (taken)
+        throw new Error(`Release ${numberOf(taken)} is already called '${String(taken.get("title"))}'`);
+    return title;
+}
 /** Add the next numbered release, with no stories yet. */
 export function addRelease(input, dir) {
     const o = open(dir);
     const number = Math.max(0, ...o.releases.items.map(numberOf)) + 1;
     const goal = input.goal?.trim();
-    o.releases.add(o.map.createNode({ number, title: cleanTitle(input.title), ...(goal ? { goal } : {}), stories: [] }));
+    o.releases.add(o.map.createNode({ number, title: uniqueTitle(o, cleanTitle(input.title)), ...(goal ? { goal } : {}), stories: [] }));
     const added = o.releases.items[o.releases.items.length - 1];
     added.get("stories", true).flow = true;
     return { number, validation: save(o) };
@@ -63,7 +86,7 @@ export function renameRelease(input, dir) {
     const o = open(dir);
     const r = find(o, input.number);
     if (input.title !== undefined)
-        r.set("title", cleanTitle(input.title));
+        r.set("title", uniqueTitle(o, cleanTitle(input.title), r));
     if (input.goal !== undefined) {
         const goal = input.goal.trim();
         if (!goal)
@@ -98,6 +121,22 @@ export function moveStory(input, dir) {
     retag(o.intentDir, new Map([[input.id, input.to]]));
     return { id: input.id, from: fromNumber, to: input.to, validation: save(o) };
 }
+/** Remove an empty release and renumber the ones after it, retagging their stories. */
+export function removeRelease(input, dir) {
+    const o = open(dir);
+    const r = find(o, input.number);
+    const stories = storiesOf(r);
+    if (stories.length)
+        throw new Error(`Release ${input.number} still has ${stories.join(", ")}. Move its stories out first with nikos release move`);
+    const bets = r.get("bets", true);
+    if (isSeq(bets) && bets.items.length)
+        throw new Error(`Release ${input.number} delivers bets (${bets.items.map((b) => String(b?.value ?? b)).join(", ")}). Move them to another release first`);
+    const title = String(r.get("title"));
+    const items = o.releases.items;
+    items.splice(items.indexOf(r), 1);
+    renumber(o);
+    return { number: input.number, title, validation: save(o) };
+}
 /** Move a release to a new position and renumber them all from 1, retagging every story that moved. */
 export function reorderRelease(input, dir) {
     const o = open(dir);
@@ -108,22 +147,73 @@ export function reorderRelease(input, dir) {
     const items = o.releases.items;
     items.splice(items.indexOf(r), 1);
     items.splice(input.to - 1, 0, r);
-    const moved = new Map();
-    items.forEach((item, i) => {
-        if (numberOf(item) === i + 1)
-            return;
-        item.set("number", i + 1);
-        for (const id of storiesOf(item))
-            moved.set(id, i + 1);
-    });
-    retag(o.intentDir, moved);
+    renumber(o);
     return { order: items.map((i) => ({ number: numberOf(i), title: String(i.get("title")) })), validation: save(o) };
 }
+const STATUS_WORD = { todo: "to do", in_progress: "in progress", needs_rework: "in rework" };
+/**
+ * Is a release ready to ship? Every story that isn't cancelled must be done (or approved), not
+ * blocked, have scenarios, and still match the feature it was done against; its dependencies
+ * outside the release must be done too. With run, each done story's scenarios run again.
+ */
+export function checkRelease(input, dir) {
+    const map = storyMapOf(dir);
+    const release = map.releases.find((r) => r.number === input.number);
+    if (!release)
+        throw new Error(`There is no release ${input.number}. Releases: ${map.releases.map((r) => r.number).join(", ") || "none"}`);
+    const inRelease = new Set(release.stories.map((s) => s.id));
+    // approval.policy: required-for-release makes a done story without a sign-off a gap.
+    const needApproval = resolveSettings(dirname(findIntentDir(dir)))["approval.policy"].value === "required-for-release";
+    const live = release.stories.filter((s) => s.status !== "cancelled");
+    const gaps = [];
+    for (const s of live) {
+        if (!isDone(s.status))
+            gaps.push(`${s.id} is ${STATUS_WORD[s.status] ?? s.status}`);
+        if (s.blocked)
+            gaps.push(`${s.id} is blocked`);
+        if (!s.criteria.length)
+            gaps.push(`${s.id} has no scenarios`);
+        if (s.specChanged)
+            gaps.push(`${s.id}'s feature changed after it was ${s.status}`);
+        if (needApproval && s.status === "done" && !s.specChanged)
+            gaps.push(`${s.id} isn't approved`);
+        const outside = s.waitingOn.filter((d) => !inRelease.has(d));
+        if (outside.length)
+            gaps.push(`${s.id} depends on ${outside.join(", ")}, which ${outside.length === 1 ? "isn't" : "aren't"} done`);
+    }
+    if (input.run) {
+        const root = dirname(findIntentDir(dir));
+        for (const s of live.filter((x) => isDone(x.status) && x.criteria.length)) {
+            let run;
+            try {
+                run = verify(root, s.id);
+            }
+            catch (err) {
+                gaps.push(`${s.id}'s scenarios couldn't run: ${err.message}`);
+                continue;
+            }
+            if (run.status !== 0) {
+                const failing = failingScenarios(run.output);
+                gaps.push(`${s.id}'s scenarios fail${failing.length ? `: ${failing.join(", ")}` : ""}`);
+            }
+        }
+    }
+    const n = (f) => live.filter(f).length;
+    const cancelled = release.stories.length - live.length;
+    const summary = [
+        `${n((s) => isDone(s.status))} of ${live.length} done`,
+        ...(n((s) => s.status === "approved") ? [`${n((s) => s.status === "approved")} approved`] : []),
+        ...(cancelled ? [`${cancelled} cancelled`] : []),
+    ].join(" · ");
+    return { number: release.number, title: release.title, ready: live.length > 0 && gaps.length === 0, summary, gaps: live.length ? gaps : ["it has no stories"] };
+}
 const USAGE = `Usage:
   nikos release add "<title>" [--goal "<goal>"]
   nikos release rename <n> ["<title>"] [--goal "<goal>"]   (--goal "" removes it)
   nikos release move <story-id> <n>
-  nikos release reorder <n> <position>`;
+  nikos release reorder <n> <position>
+  nikos release remove <n>   (only an empty release)
+  nikos release check <n> [--run]   (--run reruns each done story's scenarios)`;
 function report(v) {
     if (v.errors.length)
         console.log(`\n! intent/ now has ${v.errors.length} ${v.errors.length === 1 ? "problem" : "problems"}; run nikos validate to see them.`);
@@ -157,6 +247,18 @@ export function runRelease(args) {
             console.log(`Releases are now:\n${r.order.map((x) => `  ${x.number}. ${x.title}`).join("\n")}`);
             report(r.validation);
         }
+        else if (sub === "check" && positional[0]) {
+            const r = checkRelease({ number: Number(positional[0]), run: rest.includes("--run") }, dir);
+            console.log(`Release ${r.number} · ${r.title}: ${r.ready ? "ready" : "not ready"} — ${r.summary}`);
+            for (const g of r.gaps)
+                console.log(`  ✗ ${g}`);
+            return r.ready ? 0 : 1;
+        }
+        else if (sub === "remove" && positional[0]) {
+            const r = removeRelease({ number: Number(positional[0]) }, dir);
+            console.log(`Removed release ${r.number}: ${r.title}`);
+            report(r.validation);
+        }
         else {
             console.error(USAGE);
             return 1;

package/dist/commands/show.d.ts

@@ -0,0 +1,3 @@
+/** Everything the intent/ folder says about one story, in plain text. */
+export declare function show(story: string, dir: string): string;
+export declare function runShow(args: string[]): number;

package/dist/commands/show.js

@@ -1,14 +1,16 @@
-import { existsSync } from "node:fs";
+import { store } from "../lib/store.js";
+import { loadStates } from "../lib/state-files.js";
 import { join } from "node:path";
 import { parse } from "yaml";
-import { STORY_ID, findIntentDir, read, rel } from "../lib/project.js";
+import { approvalLapse, loadApprovals } from "../lib/approvals.js";
+import { STORY_ID, featureTags, findIntentDir, isDone, read, rel, specHash } from "../lib/project.js";
 import { parseFeature, scenariosOf } from "../lint/gherkin.js";
 import { featureFor } from "./clear.js";
 import { planVersions } from "./plan.js";
 import { parseFrontMatter } from "../lib/frontmatter.js";
 import { BET_ID, betsFor } from "../lib/bets.js";
 import { decisionEntries } from "./decisions.js";
-const yamlFile = (path) => (existsSync(path) ? parse(read(path)) : undefined);
+const yamlFile = (path) => (store().exists(path) ? parse(read(path)) : undefined);
 /** Everything the intent/ folder says about one story, in plain text. */
 export function show(story, dir) {
     if (!STORY_ID.test(story))
@@ -25,13 +27,24 @@ export function show(story, dir) {
     const effort = tags.find((t) => t.startsWith("effort-"))?.slice(7);
     const map = yamlFile(join(intentDir, "storymap.yaml"));
     const release = (map?.releases ?? []).find((r) => (r?.stories ?? []).includes(story));
-    const entry = yamlFile(join(intentDir, "state.yaml"))?.stories?.[story];
+    const states = loadStates(intentDir);
+    const entry = states[story];
+    const text = read(file);
     const out = [`${story} — ${feature.name}`];
     if (entry) {
         const extra = [entry.claimed_by && `claimed by ${entry.claimed_by}`, entry.updated && `updated ${entry.updated}`].filter(Boolean);
         out.push(`Status: ${entry.status}${extra.length ? ` (${extra.join(", ")})` : ""}`);
         if (entry.blockers?.length)
             out.push(`Blockers: ${entry.blockers.join("; ")}`);
+        const approval = loadApprovals(intentDir)[story];
+        if (approval) {
+            const lapse = approvalLapse(approval, entry, specHash(text));
+            out.push(lapse ? `! Approved by ${approval.by} on ${approval.on}, but that no longer holds: ${lapse}` : `Approved by ${approval.by} on ${approval.on}`);
+        }
+        if (entry.status === "cancelled")
+            out.push(`Cancelled: ${entry.cancelled_reason ?? "no reason given"}`);
+        if (isDone(entry.status) && entry.spec_hash && entry.spec_hash !== specHash(text))
+            out.push(`! The feature changed after it was ${entry.status}: its scenarios no longer prove it`);
     }
     else {
         out.push("Status: not in state.yaml");
@@ -39,6 +52,15 @@ export function show(story, dir) {
     out.push([release ? `Release ${release.number}${release.title ? ` (${release.title})` : ""}` : "Not in a release", priority, effort && `effort ${effort}`]
         .filter(Boolean)
         .join(" · "));
+    const deps = featureTags(text, "depends");
+    if (deps.length)
+        out.push(`Depends on: ${deps.map((d) => `${d} (${states[d]?.status ?? "unknown"})`).join(", ")}`);
+    const personas = featureTags(text, "persona");
+    if (personas.length)
+        out.push(`For: ${personas.join(", ")}`);
+    const type = featureTags(text, "type")[0];
+    if (type)
+        out.push(`Type: ${type}`);
     out.push("", `Feature: intent/${rel(intentDir, file)}`);
     for (const line of feature.description.split("\n").map((l) => l.trim()).filter(Boolean))
         out.push(`  ${line}`);

package/dist/commands/start.d.ts

@@ -0,0 +1,28 @@
+import { type Suggestion } from "./suggest.js";
+export interface StartResult {
+    /** One line per thing start did, or found already done. */
+    done: string[];
+    /** Things it couldn't do on its own, for the agent to ask about. */
+    ask: string[];
+    next: Suggestion;
+}
+export declare function start(root: string, opts?: {
+    name?: string;
+    key?: string;
+}): StartResult;
+export interface CompanyResult {
+    created: string[];
+    skipped: string[];
+    /** The line each department or team runs (or asks their agent to) to join. */
+    join: string;
+}
+/** Write a company plan repo: plan.yaml, settings every level inherits, the departments, and a README on joining. */
+export declare function companyInit(dir: string, opts: {
+    name: string;
+    period?: string;
+    departments?: string[];
+    repo?: string;
+    host?: string;
+}): CompanyResult;
+export declare function runStart(args: string[]): number;
+export declare function runCompany(args: string[]): number;

package/dist/commands/start.js

@@ -0,0 +1,138 @@
+// `nikos start` and `nikos company init`: the first run, for a team and for a company.
+// start sets a repo up with sensible defaults: intent/ (name and key from the folder), a
+// Cucumber runner for its stack, and CI for its host, each only when it's missing.
+// company init writes a company plan repo that departments and teams join.
+import { existsSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { stringify } from "yaml";
+import { store } from "../lib/store.js";
+import { detectStack } from "../verify/detect.js";
+import { detectHost, setupCi } from "./ci.js";
+import { init } from "./init.js";
+import { suggest } from "./suggest.js";
+import { setupVerify } from "./verify.js";
+export function start(root, opts = {}) {
+    const done = [];
+    const ask = [];
+    if (store().exists(join(root, "intent", "storymap.yaml")))
+        done.push("intent/ is already set up");
+    else {
+        const r = init(root, opts);
+        const map = r.validation;
+        done.push(`Created intent/ for ${opts.name ?? basename(resolve(root))} (${map.stories} starter story)`);
+    }
+    const stack = detectStack(root);
+    if (!stack)
+        ask.push("Which language is this project in? There's no package.json, pyproject.toml or requirements.txt yet, so there's no scenario runner.");
+    else {
+        const v = setupVerify(root);
+        done.push(v.created.length ? `Set up a Cucumber runner for ${stack} (${v.created.join(", ")}). Install it with: ${v.install}` : `The ${stack} scenario runner is already set up`);
+    }
+    const host = detectHost(root);
+    if (!host)
+        ask.push("Is this repo on GitHub or GitLab? There's no origin remote yet, so CI isn't set up.");
+    else if (stack) {
+        const c = setupCi(root, { host });
+        done.push(c.created.length ? `Added CI for ${host} (${c.created.join(", ")})${c.todo ? `. ${c.todo.split("\n")[0]}` : ""}` : `CI for ${host} is already set up`);
+    }
+    return { done, ask, next: suggest(root) };
+}
+/** Write a company plan repo: plan.yaml, settings every level inherits, the departments, and a README on joining. */
+export function companyInit(dir, opts) {
+    const name = opts.name?.trim();
+    if (!name)
+        throw new Error("Give the company's name");
+    const root = resolve(dir);
+    const repo = opts.repo ?? `<owner>/${basename(root)}`;
+    const join_ = `npx -y nikos join ${repo}${opts.host && opts.host !== "github.com" ? ` --host ${opts.host}` : ""}`;
+    const files = {
+        "planning/plan.yaml": `# ${name}'s plan. Departments and teams align their key results and bets to it.\n${stringify({ name, period: opts.period ?? "Set the period, e.g. Q1 2027", level: "company", pillars: [] })}`,
+        "nikos.settings.yaml": `# Settings every department, group and team that joins this plan inherits.
+# Lock a key (locked: [approval.policy]) so the levels below can't change it.
+format_version: 1
+approval:
+  policy: optional          # off | optional | required-for-release
+tracker:
+  system: none              # jira | linear | github | gitlab | …: connect it with the tracker playbook
+`,
+        "planning/downstream.yaml": `# The departments and teams that plan against this one: name, and their repo once they have one.\n${stringify((opts.departments ?? []).map((d) => ({ name: d.trim() })).filter((d) => d.name)) || "[]\n"}`,
+        "README.md": `# ${name} plan
+
+The company's objectives, key results and bets, planned with [nikOS](https://nikos.tools).
+Departments and teams plan against it from their own repos, and inherit the settings in
+\`nikos.settings.yaml\`.
+
+## Join this plan
+
+From a department's or team's repo, ask your agent to "join our company plan", or run:
+
+\`\`\`
+${join_}
+\`\`\`
+
+It links your repo, fetches a read-only copy of this plan, and shows the settings you inherit.
+Nothing in your repo moves.
+`,
+    };
+    const created = [];
+    const skipped = [];
+    for (const [rel, text] of Object.entries(files)) {
+        const path = join(root, rel);
+        if (store().exists(path))
+            skipped.push(rel);
+        else {
+            store().write(path, text, { create: true });
+            created.push(rel);
+        }
+    }
+    for (const sub of ["krs", "bets"]) {
+        const keep = join(root, "planning", sub, ".gitkeep");
+        if (!store().exists(join(root, "planning", sub)))
+            store().write(keep, "");
+    }
+    return { created, skipped, join: join_ };
+}
+export function runStart(args) {
+    const flag = (n) => {
+        const i = args.indexOf(`--${n}`);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    try {
+        const r = start(flag("dir") ?? process.cwd(), { name: flag("name"), key: flag("key") });
+        for (const d of r.done)
+            console.log(`✓ ${d}`);
+        for (const a of r.ask)
+            console.log(`? ${a}`);
+        console.log(`\n${r.next.summary}\n${r.next.options.map((o, n) => `  ${n + 1}. ${o.label}`).join("\n")}`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}
+export function runCompany(args) {
+    const [sub, ...rest] = args;
+    const flag = (n) => {
+        const i = rest.indexOf(`--${n}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    if (sub !== "init" || !flag("name")) {
+        console.error('Usage: nikos company init --name "<company>" [--period "Q1 2027"] [--departments "Payments, Growth"] [--repo owner/company-plan] [--host gitlab.com] [--dir <path>]');
+        return 1;
+    }
+    try {
+        const dir = flag("dir") ?? process.cwd();
+        const r = companyInit(dir, { name: flag("name"), period: flag("period"), departments: flag("departments")?.split(","), repo: flag("repo"), host: flag("host") });
+        if (r.created.length)
+            console.log(`Created:\n${r.created.map((f) => `  + ${f}`).join("\n")}`);
+        if (r.skipped.length)
+            console.log(`Skipped (already there):\n${r.skipped.map((f) => `  = ${f}`).join("\n")}`);
+        console.log(`\nEach department or team joins with:\n  ${r.join}${existsSync(join(dir, ".git")) ? "" : "\n\nThis folder isn't a git repo yet: create the repo on GitHub or GitLab and push it, so others can join."}`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/state.d.ts

@@ -0,0 +1,27 @@
+export type Status = "todo" | "in_progress" | "needs_rework" | "done" | "cancelled";
+export interface StateResult {
+    story: string;
+    from: Status;
+    to: Status;
+    /** Scenarios that stopped a move to done. */
+    failing: string[];
+    /** The runner's output when it gated the move. */
+    output?: string;
+}
+/** Scenario names from a cucumber-js or behave run that didn't pass. */
+export declare function failingScenarios(output: string): string[];
+export declare class StateError extends Error {
+    readonly result?: StateResult | undefined;
+    constructor(message: string, result?: StateResult | undefined);
+}
+export interface StateOptions {
+    dir?: string;
+    by?: string;
+    date?: string;
+    /** Why the story is cancelled; required for a move to cancelled. */
+    reason?: string;
+    /** The time recorded as done_at; tests pin it. */
+    now?: string;
+}
+export declare function setState(story: string, to: Status, opts?: StateOptions): StateResult;
+export declare function runState(args: string[]): number;

package/dist/commands/state.js

@@ -1,15 +1,19 @@
-import { writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { parseDocument } from "yaml";
-import { STORY_ID, findIntentDir, read } from "../lib/project.js";
+import { dirname } from "node:path";
+import { noEntry, storyState, updateStory } from "../lib/state-files.js";
+import { STORY_ID, findIntentDir, read, specHash } from "../lib/project.js";
+import { featureFor } from "./clear.js";
 import { formatResult, validate } from "./validate.js";
 import { verify } from "./verify.js";
-/** The moves docs/format.md allows. `done` also needs the story's scenarios to pass. */
+/**
+ * The moves docs/format.md allows. `done` also needs the story's scenarios to pass; `cancelled`
+ * needs a reason. Approval isn't a status: it's a person's entry in approvals.yaml.
+ */
 const MOVES = {
-    todo: ["in_progress"],
-    in_progress: ["needs_rework", "done"],
-    needs_rework: ["in_progress"],
+    todo: ["in_progress", "cancelled"],
+    in_progress: ["needs_rework", "done", "cancelled"],
+    needs_rework: ["in_progress", "cancelled"],
     done: ["needs_rework"],
+    cancelled: ["todo"],
 };
 /** Scenario names from a cucumber-js or behave run that didn't pass. */
 export function failingScenarios(output) {
@@ -37,15 +41,16 @@ export class StateError extends Error {
 export function setState(story, to, opts = {}) {
     if (!STORY_ID.test(story))
         throw new StateError(`'${story}' is not a story id (expected e.g. HT-1)`);
+    if (to === "approved")
+        throw new StateError(`Approval isn't a status: a person approves ${story} with nikos approve, or by reviewing a change to intent/approvals.yaml`);
     if (!(to in MOVES))
-        throw new StateError(`'${to}' is not a status (todo, in_progress, needs_rework, done)`);
+        throw new StateError(`'${to}' is not a status (${Object.keys(MOVES).join(", ")})`);
+    if (to === "cancelled" && !opts.reason?.trim())
+        throw new StateError(`Say why ${story} is cancelled: --reason "<why>"`);
     const intentDir = findIntentDir(opts.dir ?? process.cwd());
-    const path = join(intentDir, "state.yaml");
-    // A Document keeps comments and the order of everything we don't touch.
-    const doc = parseDocument(read(path));
-    const from = doc.getIn(["stories", story, "status"]);
+    const from = storyState(intentDir, story)?.status;
     if (!from)
-        throw new StateError(`${story} has no entry in state.yaml`);
+        throw new StateError(noEntry(intentDir, story));
     if (!MOVES[from]?.includes(to)) {
         throw new StateError(`${story} can't move from ${from} to ${to}. From ${from} it can move to: ${MOVES[from].join(", ")}`);
     }
@@ -66,18 +71,31 @@ export function setState(story, to, opts = {}) {
         }
         result.output = run.output;
     }
-    doc.setIn(["stories", story, "status"], to);
-    if (opts.by && to === "in_progress")
-        doc.setIn(["stories", story, "claimed_by"], opts.by);
-    doc.setIn(["stories", story, "updated"], opts.date ?? new Date().toISOString().slice(0, 10));
-    // No padding keeps "[A-1, A-2]" as written instead of "[ A-1, A-2 ]".
-    writeFileSync(path, doc.toString({ flowCollectionPadding: false }));
+    const feature = featureFor(story, dirname(intentDir));
+    // A Document keeps comments and the order of everything we don't touch.
+    updateStory(intentDir, story, (doc, entry) => {
+        doc.setIn([...entry, "status"], to);
+        if (opts.by && to === "in_progress")
+            doc.setIn([...entry, "claimed_by"], opts.by);
+        if (to === "done") {
+            // What the scenarios proved: validate warns if the feature changes afterwards. done_at
+            // marks this done, so an approval of an earlier done doesn't carry over.
+            if (feature)
+                doc.setIn([...entry, "spec_hash"], specHash(read(feature)));
+            doc.setIn([...entry, "done_at"], opts.now ?? new Date().toISOString());
+        }
+        if (to === "cancelled")
+            doc.setIn([...entry, "cancelled_reason"], opts.reason.trim());
+        else
+            doc.deleteIn([...entry, "cancelled_reason"]);
+        doc.setIn([...entry, "updated"], opts.date ?? new Date().toISOString().slice(0, 10));
+    });
     return result;
 }
 export function runState(args) {
     const [sub, story, to, ...rest] = args;
     if (sub !== "set" || !story || !to) {
-        console.error("Usage: nikos state set <story-id> <todo|in_progress|needs_rework|done> [--by <name>] [--dir <path>]");
+        console.error("Usage: nikos state set <story-id> <todo|in_progress|needs_rework|done|cancelled> [--by <name>] [--reason <why>] [--dir <path>]");
         return 1;
     }
     const opt = (n) => {
@@ -85,7 +103,7 @@ export function runState(args) {
         return i >= 0 ? rest[i + 1] : undefined;
     };
     try {
-        const r = setState(story, to, { dir: opt("dir"), by: opt("by") });
+        const r = setState(story, to, { dir: opt("dir"), by: opt("by"), reason: opt("reason") });
         console.log(`${r.story}: ${r.from} → ${r.to}`);
     }
     catch (err) {

package/dist/commands/step.d.ts

@@ -0,0 +1,17 @@
+import { type ValidationResult } from "./validate.js";
+/** Add a step to an activity in storymap.yaml. Its id is the title's slug unless given. */
+export declare function newStep(input: {
+    title: string;
+    activity: string;
+    id?: string;
+}, dir: string): {
+    id: string;
+    validation: ValidationResult;
+};
+/** Add an activity to the story map, e.g. an area of an existing product or an imported epic. Returns its id; an existing one is left as it is. */
+export declare function newActivity(input: {
+    title: string;
+    id?: string;
+}, dir: string): string;
+export declare function runActivity(args: string[]): number;
+export declare function runStep(args: string[]): number;