nikos 0.0.6 → 0.1.0

package/README.md

@@ -62,13 +62,12 @@ it"); the playbooks run these steps and stop at each point that needs you.
 ```text
 intent/
 ├── constitution.md      who it's for, the problem, what proves it works
-├── storymap.yaml        activities, releases, and the order to build stories in
+├── storymap.yaml        activities and steps, releases, and the order to build stories in
 ├── state.yaml           each story's status: todo, in_progress, needs_rework, done
 ├── decisions.md         why things are the way they are, append-only
 ├── features/            one .feature file per story; its scenarios are the criteria
 │   └── <activity>/<story>.feature
-├── plans/               how each story will be built, versioned: <story>.v<N>.md
-└── bets/                time-boxed bets and the stories that test them
+└── plans/               how each story will be built, versioned: <story>.v<N>.md
 ```
 
 Every file is plain text you can read, review and diff. The full format:
@@ -82,6 +81,8 @@ Every file is plain text you can read, review and diff. The full format:
 | `nikos init` | Create `intent/` in this repo |
 | `nikos validate` | Check `intent/` is well formed |
 | `nikos story add "<title>"` | Add a story to the map, state and a starter feature |
+| `nikos step add "<title>"` | Add a step under an activity |
+| `nikos release add\|rename\|move\|reorder` | Define releases and move stories between them, keeping feature tags in step |
 | `nikos clear <id>` | Check a story is ready to build |
 | `nikos plan new <id>` | Start the next version of a story's plan |
 | `nikos verify setup` | Add a Cucumber runner for this repo's stack |
@@ -91,7 +92,7 @@ Every file is plain text you can read, review and diff. The full format:
 | `nikos show <id>` | Summarise a story: feature, status, plan, bets, decisions |
 | `nikos decide "<title>"` | Append a decision to `decisions.md` |
 | `nikos decisions "<q>"` | Quote the decisions about a topic or story |
-| `nikos bet new <id>` | Write a time-boxed bet card linked to its stories |
+| `nikos map` | Write a read-only story map page |
 
 ## Links
 

package/dist/cli.js

@@ -7,10 +7,14 @@ import { runVerify } from "./commands/verify.js";
 import { runNext } from "./commands/next.js";
 import { runState } from "./commands/state.js";
 import { runDecide } from "./commands/decide.js";
-import { runBet } from "./commands/bet.js";
 import { runShow } from "./commands/show.js";
 import { runDecisions } from "./commands/decisions.js";
 import { runStory } from "./commands/story.js";
+import { runStep } from "./commands/step.js";
+import { runRelease } from "./commands/release.js";
+import { runVideo } from "./commands/video.js";
+import { runMap } from "./commands/map.js";
+import { runPlanning } from "./planning/cli.js";
 const commands = {
     init: runInit,
     validate: runValidate,
@@ -20,10 +24,14 @@ const commands = {
     next: runNext,
     state: runState,
     decide: runDecide,
-    bet: runBet,
     show: runShow,
     decisions: runDecisions,
     story: runStory,
+    step: runStep,
+    release: runRelease,
+    video: runVideo,
+    map: runMap,
+    planning: runPlanning,
 };
 const help = `nikos — spec-driven development for AI coding agents
 
@@ -33,7 +41,12 @@ Commands:
   init             Create intent/ in this repo (--name, --key)
   validate [dir]   Check the intent/ folder is well formed
   story add "<title>"  Add a story to the map, state and a starter feature
-                   (--activity, --release, --priority)
+                   (--activity, --step, --release, --priority)
+  step add "<title>"   Add a step under an activity (--activity, --id)
+  release add "<title>"  Add the next release (--goal)
+  release rename <n>   Change a release's title or goal (--goal)
+  release move <id> <n>  Move a story to another release, retagging its feature
+  release reorder <n> <pos>  Move a release and renumber them all
   plan new <id>    Start the next version of a story's plan
   clear <id>       Check a story is Lean and Executable before building
   verify setup     Set up a Cucumber runner for this repo's stack
@@ -44,8 +57,11 @@ Commands:
   state set <id> <status>  Move a story; done only if its scenarios pass
   decide "<title>" Append a decision to decisions.md
                    (--why, --story, --category, --supersedes)
-  bet new <bet-id> Write a time-boxed bet card linked to its stories
-                   (--hypothesis, --kr, --uplift, --time-box, --story, --blocker)
+  video            Draft a video brief and storyboard from the done stories
+                   (--out, default marketing/storymap-video)
+  map              Write a read-only story map page (--out, default storymap.html)
+  planning <cmd>   Bets, key results and the planning dashboard (nikos-planning pack;
+                   run \`nikos planning help\`)
 
 Docs: https://nikos.tools`;
 async function main(argv) {

package/dist/commands/map.js

@@ -0,0 +1,272 @@
+// The story map: activities as columns, releases as numbered bands, stories as cards tinted
+// by state.yaml. Read-only and script-free: the page has nothing to edit and runs no code, so
+// it can be shared as a file. Selecting a story opens its panel with :target, in CSS alone.
+import { existsSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { parse } from "yaml";
+import { featureStoryIds, findIntentDir, read, walk } from "../lib/project.js";
+export const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const yamlAt = (path) => (existsSync(path) ? parse(read(path)) : undefined);
+const PRIORITY = /@(must|should|could|wont)\b/;
+/** One story's details from its feature file: title, tags, narrative and criteria. */
+function featureStory(text, id) {
+    const [head, body = ""] = text.split(/^\s*Feature:/m);
+    const lines = body.split("\n");
+    const narrative = [];
+    for (const line of lines.slice(1)) {
+        const t = line.trim();
+        if (t.startsWith("@") || /^(Scenario|Background|Rule|Scenario Outline):/.test(t))
+            break;
+        if (t)
+            narrative.push(t);
+    }
+    const criteria = [];
+    let tags = "";
+    for (const line of lines) {
+        const t = line.trim();
+        if (t.startsWith("@"))
+            tags = t;
+        const m = /^Scenario(?: Outline)?:\s*(.+)$/.exec(t);
+        if (!m)
+            continue;
+        const ac = /@(AC\d+)\b/.exec(tags)?.[1] ?? "";
+        criteria.push({ id: ac, title: m[1].replace(/^AC\d+\s*[—–-]\s*/, ""), priority: PRIORITY.exec(tags)?.[1] ?? "" });
+        tags = "";
+    }
+    return {
+        id,
+        title: lines[0]?.trim() || id,
+        activity: /@activity-([a-z0-9-]+)/.exec(head)?.[1] ?? "",
+        step: /@step-([a-z0-9-]+)/.exec(head)?.[1] ?? "",
+        priority: PRIORITY.exec(head)?.[1] ?? "",
+        effort: /@effort-([A-Za-z0-9]+)/.exec(head)?.[1] ?? "",
+        narrative: narrative.map((l, i) => (i ? l.replace(/^So that\b/, "so that") : l)).join(", "),
+        criteria,
+    };
+}
+/** The story map as data: activities, releases with their bets, and every story's status. */
+export function storyMapOf(dir) {
+    const intent = findIntentDir(dir);
+    const map = yamlAt(join(intent, "storymap.yaml")) ?? {};
+    const states = yamlAt(join(intent, "state.yaml"))?.stories ?? {};
+    const stateOf = (id) => ({ status: states[id]?.status ?? "todo", blocked: (states[id]?.blockers ?? []).length > 0 });
+    const features = new Map();
+    for (const file of walk(join(intent, "features"), ".feature")) {
+        const text = read(file);
+        const id = featureStoryIds(text)[0];
+        if (!id)
+            continue;
+        features.set(id, { ...featureStory(text, id), ...stateOf(id) });
+    }
+    const story = (id) => features.get(id) ?? { id, title: id, activity: "", step: "", priority: "", effort: "", narrative: "", criteria: [], ...stateOf(id) };
+    const releases = (Array.isArray(map.releases) ? map.releases : []).map((r) => ({
+        number: Number(r.number),
+        title: String(r.title ?? `Release ${r.number}`),
+        goal: String(r.goal ?? ""),
+        bets: Array.isArray(r.bets) ? r.bets.map(String) : [],
+        stories: (Array.isArray(r.stories) ? r.stories : []).map((s) => story(String(s))),
+    }));
+    const placed = new Set(releases.flatMap((r) => r.stories.map((s) => s.id)));
+    return {
+        project: String(map.project ?? ""),
+        activities: (Array.isArray(map.activities) ? map.activities : []).map((a) => ({
+            id: String(a.id),
+            title: String(a.title ?? a.id),
+            steps: (Array.isArray(a.steps) ? a.steps : []).map((st) => ({ id: String(st.id), title: String(st.title ?? st.id) })),
+        })),
+        releases,
+        unreleased: [...features.values()].filter((s) => !placed.has(s.id)),
+    };
+}
+/** Each status's tint class and the word shown on its card. Blocked wins over the status. */
+const STATUS = {
+    todo: { cls: "todo", word: "to do" },
+    in_progress: { cls: "doing", word: "in progress" },
+    needs_rework: { cls: "rework", word: "rework" },
+    done: { cls: "done", word: "done" },
+};
+const statusOf = (s) => (s.blocked ? { cls: "blocked", word: "blocked" } : STATUS[s.status] ?? STATUS.todo);
+const pad = (n) => String(n).padStart(2, "0");
+/** The whole story map as one standalone HTML page. */
+export function renderMap(dir) {
+    const m = storyMapOf(dir);
+    // One column per step; an activity with no steps (or the "Other" bucket) gets one column.
+    const known = new Set(m.activities.map((a) => a.id));
+    const everything = [...m.releases.flatMap((r) => r.stories), ...m.unreleased];
+    const groups = [
+        ...m.activities,
+        ...(everything.some((s) => !known.has(s.activity)) ? [{ id: "", title: "Other", steps: [] }] : []),
+    ].map((a) => ({ ...a, columns: a.steps.length ? a.steps.map((st) => ({ key: `${a.id}/${st.id}`, label: `${a.title} · ${st.title}` })) : [{ key: `${a.id}/`, label: a.title }] }));
+    const columns = groups.flatMap((g) => g.columns);
+    const columnOf = (s) => {
+        const g = groups.find((x) => x.id === (known.has(s.activity) ? s.activity : ""));
+        return g.columns.find((c) => c.key === `${g.id}/${s.step}`)?.key ?? g.columns[0].key;
+    };
+    const hasSteps = m.activities.some((a) => a.steps.length);
+    const card = (s) => {
+        const st = statusOf(s);
+        const musts = s.criteria.filter((c) => c.priority === "must").length;
+        const foot = s.criteria.length
+            ? `<span>${s.criteria.length} ${s.criteria.length === 1 ? "criterion" : "criteria"}${musts ? ` · ${musts} must` : ""}</span>`
+            : `<span class="warn">No criteria</span>`;
+        return `<a class="card ${st.cls}" data-story="${esc(s.id)}" href="#story-${esc(s.id)}"><span class="crow"><span class="sid">${esc(s.id)}</span><span class="sword">${esc(st.word)}</span></span><span class="stitle">${esc(s.title)}</span><span class="cfoot">${foot}</span></a>`;
+    };
+    const tally = (stories) => {
+        const n = (f) => stories.filter(f).length;
+        const parts = [`${n((s) => s.status === "done")} done`, `${n((s) => s.status === "in_progress")} in progress`, `${n((s) => s.status === "todo")} to do`];
+        const blocked = n((s) => s.blocked);
+        return parts.join(" · ") + (blocked ? ` · <span class="warn">${blocked} blocked</span>` : "");
+    };
+    const band = (id, code, heading, goal, bets, stories) => {
+        const shipped = stories.length > 0 && stories.every((s) => s.status === "done");
+        const chips = bets.map((b) => `<span class="bet">${esc(b)}</span>`).join("");
+        const cells = columns
+            .map((c) => `<div class="cell" data-activity="${esc(c.label)}">${stories.filter((s) => columnOf(s) === c.key).map(card).join("")}</div>`)
+            .join("");
+        return `<section class="band" id="${esc(id)}"><div class="divider"><span class="rnum">${esc(code)}</span><h2>${esc(heading)}</h2>${shipped ? `<span class="stamp">Shipped</span>` : ""}<span class="tally">${stories.length ? tally(stories) : "no stories"}</span><span class="rule"></span></div>${goal ? `<p class="goal">${esc(goal)}</p>` : ""}${chips ? `<div class="bets"><span class="eyebrow">Delivers</span>${chips}</div>` : ""}${stories.length ? `<div class="lane">${cells}</div>` : `<p class="empty">No stories yet.</p>`}</section>`;
+    };
+    const bands = m.releases.map((r) => band(`release-${r.number}`, pad(r.number), `Release ${r.number} · ${r.title}`, r.goal, r.bets, r.stories)).join("");
+    const unreleased = m.unreleased.length ? band("unreleased", "--", "Not in a release", "", [], m.unreleased) : "";
+    const spine = `<div class="spine"><div class="activities">${groups
+        .map((g) => `<div class="activity" style="--span:${g.columns.length}"><span class="eyebrow">Activity</span><strong>${esc(g.title)}</strong></div>`)
+        .join("")}</div>${hasSteps ? `<div class="steps">${groups.map((g) => (g.steps.length ? g.steps.map((st) => `<div class="step">${esc(st.title)}</div>`).join("") : `<div class="step none"></div>`)).join("")}</div>` : ""}</div>`;
+    const jumps = [
+        ...m.releases.map((r) => `<a class="jump" href="#release-${r.number}"><span class="rcode">R${r.number}</span>${esc(r.title)}<span class="count">${r.stories.length}</span></a>`),
+        ...(m.unreleased.length ? [`<a class="jump" href="#unreleased">Not in a release<span class="count">${m.unreleased.length}</span></a>`] : []),
+    ].join("");
+    const panel = (s) => {
+        const st = statusOf(s);
+        const facts = [s.id, s.priority, s.effort && `effort ${s.effort}`].filter(Boolean).map((f) => esc(f)).join(" · ");
+        const criteria = s.criteria.length
+            ? `<ol class="criteria">${s.criteria.map((c) => `<li><span class="sid">${esc(c.id)}</span>${esc(c.title)}${c.priority ? ` <span class="prio">${esc(c.priority)}</span>` : ""}</li>`).join("")}</ol>`
+            : `<p class="warn">No criteria yet.</p>`;
+        return `<div class="sheet-wrap" id="story-${esc(s.id)}"><a class="scrim" href="#" aria-label="Close"></a><aside class="sheet" aria-label="${esc(s.id)}"><div class="sheet-head"><span class="sid">${esc(s.id)}</span><a class="close" href="#" aria-label="Close">×</a></div><div class="status-card ${st.cls}"><span class="sword">${esc(st.word)}</span><div class="sc-title">${esc(s.title)}</div><div class="facts">${facts}</div>${s.narrative ? `<p class="narrative">${esc(s.narrative)}</p>` : ""}</div><div class="eyebrow">Acceptance criteria</div>${criteria}</aside></div>`;
+    };
+    const title = m.project ? `${m.project} · Story map` : "Story map";
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<header class="top"><h1>${esc(title)}</h1><nav class="jumps" aria-label="Releases">${jumps}</nav></header>
+<main>
+<div class="board" style="--cols:${Math.max(1, columns.length)}">
+${spine}
+${bands}
+${unreleased}
+</div>
+</main>
+${everything.map(panel).join("\n")}
+</body>
+</html>
+`;
+}
+const CSS = `
+:root { --paper: #FAFAF7; --surface: #FFFFFF; --elevated: #F2F0E9; --line: #E8E6DF; --line-2: #D6D3C8; --ink: #1A1A18; --ink-2: #57534E; --muted: #6E695F; --brand: #1B4FD8; --brand-subtle: rgba(27,79,216,.07); --stamp: #DC2626; --warn: #B45309; --col: 240px; --gap: 16px; }
+* { box-sizing: border-box; }
+body { margin: 0; height: 100vh; display: flex; flex-direction: column; background: var(--paper); color: var(--ink); font: 13px/1.45 Inter, system-ui, -apple-system, "Segoe UI", sans-serif; }
+.sid, .rnum, .rcode, .count, .tally, .cfoot, .facts, .stamp { font-family: "JetBrains Mono", ui-monospace, Menlo, monospace; }
+.eyebrow { font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .06em; color: var(--ink-2); }
+.warn { color: var(--warn); font-weight: 600; }
+.top { padding: 16px 24px 12px; display: flex; flex-wrap: wrap; gap: 10px 24px; align-items: center; justify-content: space-between; border-bottom: 1px solid var(--line); background: var(--paper); }
+h1 { font-size: 15px; margin: 0; }
+.jumps { display: flex; flex-wrap: wrap; gap: 6px; }
+.jump { display: inline-flex; align-items: center; gap: 6px; height: 28px; padding: 0 12px; border: 1px solid var(--line); border-radius: 99px; background: var(--surface); color: var(--ink); text-decoration: none; font-size: 12px; }
+.jump:hover { border-color: var(--line-2); }
+.rcode, .count { font-size: 11px; color: var(--muted); }
+main { flex: 1; min-height: 0; overflow: auto; background-color: var(--paper); background-image: linear-gradient(rgba(26,26,24,.06) 1px, transparent 1px), linear-gradient(90deg, rgba(26,26,24,.06) 1px, transparent 1px); background-size: 24px 24px; background-attachment: local; }
+.board { width: max-content; min-width: 100%; padding: 0 24px 48px; }
+.spine { position: sticky; top: 0; z-index: 3; padding: 24px 0 4px; background: var(--paper); }
+.activities, .steps { display: flex; gap: var(--gap); }
+.steps { margin-top: 8px; }
+.step { width: var(--col); min-height: 32px; border-radius: 4px; background: var(--brand-subtle); padding: 7px 10px; font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .06em; color: var(--ink-2); }
+.step.none { background: none; }
+.activity { width: calc(var(--span, 1) * var(--col) + (var(--span, 1) - 1) * var(--gap)); display: grid; gap: 2px; background: var(--surface); border: 1px solid var(--line); border-top: 2px solid var(--brand); border-radius: 4px; padding: 10px 14px; box-shadow: 0 1px 2px rgba(60,50,30,.06); }
+.activity strong { font-size: 13px; }
+.band { scroll-margin-top: 90px; }
+.divider { display: flex; align-items: center; gap: 12px; margin: 20px 0 10px; }
+.rnum { color: var(--brand); font-size: 13px; font-weight: 600; }
+.divider h2 { margin: 0; font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .06em; color: var(--ink-2); white-space: nowrap; }
+.tally { font-size: 11px; color: var(--muted); white-space: nowrap; }
+.rule { flex: 1; border-top: 1px solid var(--line); min-width: 24px; }
+.stamp { display: inline-block; transform: rotate(-3deg); color: var(--stamp); border: 2px solid var(--stamp); box-shadow: inset 0 0 0 1px rgba(220,38,38,.45); padding: .15rem .5rem; font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .08em; opacity: .85; mix-blend-mode: multiply; }
+.goal { margin: -4px 0 10px; color: var(--ink-2); max-width: 720px; }
+.bets { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; margin: -4px 0 10px; }
+.bet { font-size: 12px; padding: 2px 9px; border-radius: 99px; background: var(--brand-subtle); color: var(--brand); }
+.lane { display: flex; gap: var(--gap); }
+.cell { width: var(--col); min-height: 48px; display: flex; flex-direction: column; gap: 4px; }
+.empty { color: var(--muted); margin: 0 0 8px; }
+.card { --fill: #F4F3EE; --edge: #E3E1D9; --word: #7D786E; display: flex; flex-direction: column; min-height: 32px; border: 1px solid var(--edge); border-radius: 4px; background: var(--fill); color: var(--ink); text-decoration: none; box-shadow: 0 1px 2px rgba(60,50,30,.06); }
+.card:hover { border-color: var(--line-2); }
+.card:focus-visible { outline: 2px solid var(--brand); outline-offset: 1px; box-shadow: 0 0 0 5px rgba(27,79,216,.15); }
+.crow { display: flex; align-items: baseline; gap: 6px; padding: 4px 8px 0; }
+.card .sid { font-size: 11px; letter-spacing: .06em; color: var(--muted); }
+.sword { margin-left: auto; font-size: 11px; font-weight: 500; color: var(--word); }
+.sword::first-letter { text-transform: uppercase; }
+.stitle { padding: 2px 8px; font-size: 13px; line-height: 1.35; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+.cfoot { display: flex; justify-content: space-between; padding: 0 8px 4px; font-size: 11px; letter-spacing: .04em; color: var(--muted); }
+.doing { --fill: #EDF3FD; --edge: #CFDDF8; --word: #1E7A50; }
+.card.doing { border-left: 4px solid #1E9E5C; }
+.rework { --fill: #F1EEFB; --edge: #DCD5F3; --word: #C2680F; }
+.card.rework { border-left: 4px solid #E8892B; }
+.done { --fill: #F1EEFB; --edge: #DCD5F3; --word: #6D5BB8; }
+.card.done .stitle { text-decoration: line-through; text-decoration-color: rgba(26,26,24,.35); }
+.blocked { --fill: #FDECEC; --edge: #F3C2C2; --word: #B83232; }
+.card.blocked { border-left: 4px solid #D64545; }
+.sheet-wrap { display: none; }
+.sheet-wrap:target { display: block; position: fixed; inset: 0; z-index: 10; }
+.scrim { position: absolute; inset: 0; background: rgba(0,0,0,.4); }
+.sheet { position: absolute; top: 0; right: 0; bottom: 0; width: 700px; max-width: 95vw; overflow-y: auto; background: var(--surface); border-left: 1px solid var(--line); box-shadow: 0 25px 50px -12px rgba(0,0,0,.25); padding: 16px 20px 32px; animation: slide .28s cubic-bezier(.2,.8,.3,1); }
+@keyframes slide { from { transform: translateX(40px); opacity: 0; } }
+.sheet-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 14px; }
+.close { font-size: 22px; line-height: 1; color: var(--muted); text-decoration: none; padding: 0 4px; }
+.status-card { border: 1px solid var(--edge, var(--line)); background: var(--fill, var(--surface)); border-radius: 8px; padding: 14px; margin-bottom: 20px; }
+.status-card .sword { display: block; margin: 0 0 4px; }
+.sc-title { font-size: 15px; font-weight: 600; margin-bottom: 4px; }
+.facts { font-size: 11px; color: var(--muted); }
+.narrative { margin: 10px 0 0; color: var(--ink-2); }
+.criteria { margin: 8px 0 0; padding-left: 0; list-style: none; display: grid; gap: 6px; }
+.criteria li { border: 1px solid var(--line); border-radius: 4px; padding: 8px 10px; }
+.criteria .sid { font-size: 11px; color: var(--muted); margin-right: 8px; }
+.prio { font-size: 11px; color: var(--muted); }
+@media (prefers-reduced-motion: reduce) { .sheet { animation: none; } }
+@media (max-width: 767px) {
+  body { height: auto; display: block; }
+  .top { padding: 12px 16px; }
+  main { background-image: none; }
+  .board { width: auto; padding: 0 16px 32px; }
+  .spine { display: none; }
+  .lane { display: block; }
+  .cell { width: auto; min-height: 0; }
+  .cell:empty { display: none; }
+  .cell::before { content: attr(data-activity); display: block; margin: 12px 0 6px; padding-bottom: 4px; border-bottom: 1px solid rgba(27,79,216,.3); font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: .06em; color: var(--brand); }
+  .band { scroll-margin-top: 12px; }
+  .divider { flex-wrap: wrap; gap: 4px 12px; }
+  .rule { display: none; }
+}
+`;
+/** `nikos map`: write the story map as a standalone page. */
+export function runMap(args) {
+    const flag = (name) => {
+        const i = args.indexOf(name);
+        return i >= 0 ? args[i + 1] : undefined;
+    };
+    const out = resolve(flag("--out") ?? "storymap.html");
+    const dir = resolve(flag("--dir") ?? process.cwd());
+    try {
+        if (!existsSync(join(findIntentDir(dir), "storymap.yaml")))
+            throw new Error(`No storymap.yaml in ${findIntentDir(dir)}: run nikos init first`);
+        writeFileSync(out, renderMap(dir));
+        const shown = relative(process.cwd(), out);
+        console.log(`Wrote ${shown && !shown.startsWith("..") ? shown : out}`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/release.js

@@ -0,0 +1,170 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isMap, isSeq, parseDocument } from "yaml";
+import { featureStoryIds, findIntentDir, read, setFeatureTag, walk } from "../lib/project.js";
+import { validate } from "./validate.js";
+const yamlOpts = { lineWidth: 0, flowCollectionPadding: false };
+function open(dir) {
+    const intentDir = findIntentDir(dir);
+    const mapPath = join(intentDir, "storymap.yaml");
+    // A Document keeps comments and the order of everything we don't touch.
+    const map = parseDocument(read(mapPath));
+    const releases = map.get("releases", true);
+    if (!isSeq(releases))
+        throw new Error("storymap.yaml has no releases list");
+    return { intentDir, mapPath, map, releases: releases };
+}
+const numberOf = (r) => Number(r.get("number"));
+const storiesOf = (r) => {
+    const s = r.get("stories", true);
+    return isSeq(s) ? s.items.map((i) => String(i?.value ?? i)) : [];
+};
+function find(o, n) {
+    const r = o.releases.items.find((i) => isMap(i) && numberOf(i) === n);
+    if (!r)
+        throw new Error(`There is no release ${n}. Releases: ${o.releases.items.map(numberOf).join(", ") || "none"}`);
+    return r;
+}
+/** Rewrite the @release-<n> tag on each moved story's feature file. */
+function retag(intentDir, moved) {
+    if (!moved.size)
+        return;
+    for (const file of walk(join(intentDir, "features"), ".feature")) {
+        const text = read(file);
+        const id = featureStoryIds(text)[0];
+        if (id && moved.has(id))
+            writeFileSync(file, setFeatureTag(text, "release", String(moved.get(id)), id));
+    }
+}
+function save(o) {
+    writeFileSync(o.mapPath, o.map.toString(yamlOpts));
+    return validate(o.intentDir);
+}
+const cleanTitle = (title) => {
+    const t = title?.trim();
+    if (!t)
+        throw new Error("A release needs a title");
+    return t;
+};
+/** 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: [] }));
+    const added = o.releases.items[o.releases.items.length - 1];
+    added.get("stories", true).flow = true;
+    return { number, validation: save(o) };
+}
+/** Change a release's title and/or goal. An empty goal removes it. */
+export function renameRelease(input, dir) {
+    if (input.title === undefined && input.goal === undefined)
+        throw new Error("Give a new title, a --goal, or both");
+    const o = open(dir);
+    const r = find(o, input.number);
+    if (input.title !== undefined)
+        r.set("title", cleanTitle(input.title));
+    if (input.goal !== undefined) {
+        const goal = input.goal.trim();
+        if (!goal)
+            r.delete("goal");
+        else if (r.has("goal"))
+            r.set("goal", goal);
+        else {
+            // Keep goal next to the title rather than after the stories.
+            const at = r.items.findIndex((p) => p.key?.value === "title") + 1;
+            r.items.splice(at, 0, o.map.createPair("goal", goal));
+        }
+    }
+    return { number: input.number, validation: save(o) };
+}
+/** Move a story to another release (to the end of its build order), keeping its feature tag in step. */
+export function moveStory(input, dir) {
+    const o = open(dir);
+    const target = find(o, input.to);
+    const from = o.releases.items.find((r) => storiesOf(r).includes(input.id));
+    if (!from)
+        throw new Error(`${input.id} is not in any release in storymap.yaml`);
+    const fromNumber = numberOf(from);
+    if (fromNumber === input.to)
+        throw new Error(`${input.id} is already in release ${input.to}`);
+    const seq = from.get("stories", true);
+    seq.items.splice(storiesOf(from).indexOf(input.id), 1);
+    const dest = target.get("stories", true);
+    if (isSeq(dest))
+        dest.add(input.id);
+    else
+        target.set("stories", o.map.createNode([input.id], { flow: true }));
+    retag(o.intentDir, new Map([[input.id, input.to]]));
+    return { id: input.id, from: fromNumber, to: input.to, 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);
+    const r = find(o, input.number);
+    const count = o.releases.items.length;
+    if (!Number.isInteger(input.to) || input.to < 1 || input.to > count)
+        throw new Error(`Position must be from 1 to ${count}`);
+    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);
+    return { order: items.map((i) => ({ number: numberOf(i), title: String(i.get("title")) })), validation: save(o) };
+}
+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>`;
+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.`);
+}
+export function runRelease(args) {
+    const [sub, ...rest] = args;
+    const opt = (n) => {
+        const i = rest.indexOf(`--${n}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    const positional = rest.filter((a, i) => !a.startsWith("--") && !(i > 0 && rest[i - 1].startsWith("--")));
+    const dir = opt("dir") ?? process.cwd();
+    try {
+        if (sub === "add" && positional[0]) {
+            const r = addRelease({ title: positional[0], goal: opt("goal") }, dir);
+            console.log(`Added release ${r.number}: ${positional[0].trim()}`);
+            report(r.validation);
+        }
+        else if (sub === "rename" && positional[0]) {
+            const r = renameRelease({ number: Number(positional[0]), title: positional[1], goal: opt("goal") }, dir);
+            console.log(`Updated release ${r.number}`);
+            report(r.validation);
+        }
+        else if (sub === "move" && positional[0] && positional[1]) {
+            const r = moveStory({ id: positional[0], to: Number(positional[1]) }, dir);
+            console.log(`Moved ${r.id} from release ${r.from} to release ${r.to}`);
+            report(r.validation);
+        }
+        else if (sub === "reorder" && positional[0] && positional[1]) {
+            const r = reorderRelease({ number: Number(positional[0]), to: Number(positional[1]) }, dir);
+            console.log(`Releases are now:\n${r.order.map((x) => `  ${x.number}. ${x.title}`).join("\n")}`);
+            report(r.validation);
+        }
+        else {
+            console.error(USAGE);
+            return 1;
+        }
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/show.js

@@ -1,11 +1,12 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parse } from "yaml";
-import { STORY_ID, findIntentDir, read, rel, walk } from "../lib/project.js";
+import { STORY_ID, findIntentDir, read, rel } from "../lib/project.js";
 import { parseFeature, scenariosOf } from "../lint/gherkin.js";
 import { featureFor } from "./clear.js";
 import { planVersions } from "./plan.js";
-import { parseBet } from "./bet.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);
 /** Everything the intent/ folder says about one story, in plain text. */
@@ -48,16 +49,15 @@ export function show(story, dir) {
     out.push("");
     if (versions.length) {
         const v = versions.at(-1);
-        const plan = parseBet(read(join(intentDir, "plans", `${story}.v${v}.md`)));
+        const plan = parseFrontMatter(read(join(intentDir, "plans", `${story}.v${v}.md`)));
         out.push(`Plan: v${v} (intent/plans/${story}.v${v}.md)${plan?.meta?.summary ? ` — ${plan.meta.summary}` : ""}`);
     }
     else {
         out.push("Plan: none yet");
     }
-    const bets = walk(join(intentDir, "bets"), ".md")
-        .map((p) => parseBet(read(p))?.meta)
-        .filter((m) => Array.isArray(m?.stories) && m.stories.includes(story));
-    out.push(bets.length ? `Bets: ${bets.map((b) => `${b.id} (${b.status}, ends ${b.time_box}, intent/bets/${b.id}.md)`).join(", ")}` : "Bets: none");
+    const { bets, from, release: rn } = betsFor(map, story);
+    const where = (b) => (BET_ID.test(b) ? `${b} (planning/bets/${b}.md)` : b);
+    out.push(bets.length ? `Bets: ${bets.map(where).join(", ")} — from ${from === "story" ? "the story" : `release ${rn}`}` : "Bets: none");
     const decisions = decisionEntries(dir).filter((e) => e.title.includes(`(${story})`));
     out.push(decisions.length ? "Decisions:" : "Decisions: none recorded for this story");
     for (const d of decisions)

package/dist/commands/step.js

@@ -0,0 +1,59 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isMap, isSeq, parseDocument } from "yaml";
+import { findIntentDir, read } from "../lib/project.js";
+import { slugify } from "./init.js";
+import { validate } from "./validate.js";
+const yamlOpts = { lineWidth: 0, flowCollectionPadding: false };
+/** Add a step to an activity in storymap.yaml. Its id is the title's slug unless given. */
+export function newStep(input, dir) {
+    const title = input.title?.trim();
+    if (!title)
+        throw new Error("A step needs a title");
+    const intentDir = findIntentDir(dir);
+    const mapPath = join(intentDir, "storymap.yaml");
+    // A Document keeps comments and the order of everything we don't touch.
+    const map = parseDocument(read(mapPath));
+    const activities = map.get("activities", true);
+    const list = isSeq(activities) ? activities.items.filter(isMap) : [];
+    const activity = list.find((a) => a.get("id") === input.activity);
+    if (!activity)
+        throw new Error(`'${input.activity}' is not an activity in storymap.yaml. Activities: ${list.map((a) => a.get("id")).join(", ") || "none"}`);
+    const id = input.id ?? slugify(title);
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(id))
+        throw new Error(`'${id}' is not a step id: use lowercase words joined by hyphens`);
+    const taken = list.flatMap((a) => {
+        const steps = a.get("steps", true);
+        return isSeq(steps) ? steps.items.filter(isMap).map((s) => String(s.get("id"))) : [];
+    });
+    if (taken.includes(id))
+        throw new Error(`There is already a step '${id}'; give it a different --id`);
+    const steps = activity.get("steps", true);
+    if (isSeq(steps))
+        steps.add(map.createNode({ id, title }));
+    else
+        activity.set("steps", map.createNode([{ id, title }]));
+    writeFileSync(mapPath, map.toString(yamlOpts));
+    return { id, validation: validate(intentDir) };
+}
+export function runStep(args) {
+    const [sub, title, ...rest] = args;
+    const opt = (n) => {
+        const i = rest.indexOf(`--${n}`);
+        return i >= 0 ? rest[i + 1] : undefined;
+    };
+    if (sub !== "add" || !title || title.startsWith("--") || !opt("activity")) {
+        console.error('Usage: nikos step add "<title>" --activity <id> [--id <step-id>]');
+        return 1;
+    }
+    try {
+        const r = newStep({ title, activity: opt("activity"), id: opt("id") }, opt("dir") ?? process.cwd());
+        console.log(`Added step ${r.id} to activity ${opt("activity")}`);
+        console.log(`\nTag a story's feature with @step-${r.id}, or add one with nikos story add "<title>" --activity ${opt("activity")} --step ${r.id}.`);
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}