nikos 0.1.1 → 0.2.1

package/dist/commands/map.js

@@ -1,12 +1,16 @@
 // 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";
+// Served live by the planning dashboard, it also gets a filter bar (see FILTER_JS).
+import { loadStates } from "../lib/state-files.js";
+import { writeFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { parse } from "yaml";
-import { featureStoryIds, findIntentDir, read, walk } from "../lib/project.js";
+import { approvalLapse, loadApprovals } from "../lib/approvals.js";
+import { store } from "../lib/store.js";
+import { featureStoryIds, featureTags, findIntentDir, isDone, read, specHash, 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 yamlAt = (path) => (store().exists(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) {
@@ -42,23 +46,47 @@ function featureStory(text, id) {
         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,
+        type: { technical: "technical", "bug-risk": "bug_risk" }[featureTags(text, "type")[0] ?? ""] ?? "user_story",
+        personas: featureTags(text, "persona"),
+        dependsOn: featureTags(text, "depends"),
     };
 }
 /** 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 states = loadStates(intent);
+    const approvals = loadApprovals(intent);
+    // Approved is shown as a status: done, plus an approval that still holds.
+    const approvedBy = (id, hash) => {
+        const a = approvals[id];
+        return a && !approvalLapse(a, states[id], hash) ? a.by : "";
+    };
+    const stateOf = (id, deps, hash) => {
+        const st = states[id] ?? {};
+        const by = approvedBy(id, hash);
+        const status = by ? "approved" : st.status ?? "todo";
+        return {
+            status,
+            blocked: (st.blockers ?? []).length > 0,
+            waitingOn: isDone(status) || status === "cancelled" ? [] : deps.filter((d) => !isDone(states[d]?.status)),
+            approvedBy: by,
+            specChanged: isDone(status) && !!st.spec_hash && !!hash && st.spec_hash !== hash,
+            cancelledReason: String(st.cancelled_reason ?? ""),
+        };
+    };
     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 f = featureStory(text, id);
+        features.set(id, { ...f, ...stateOf(id, f.dependsOn, specHash(text)) });
     }
-    const story = (id) => features.get(id) ?? { id, title: id, activity: "", step: "", priority: "", effort: "", narrative: "", criteria: [], ...stateOf(id) };
+    const story = (id) => features.get(id) ?? {
+        id, title: id, activity: "", step: "", priority: "", effort: "", narrative: "", criteria: [], type: "user_story", personas: [], dependsOn: [], ...stateOf(id, []),
+    };
     const releases = (Array.isArray(map.releases) ? map.releases : []).map((r) => ({
         number: Number(r.number),
         title: String(r.title ?? `Release ${r.number}`),
@@ -69,6 +97,8 @@ export function storyMapOf(dir) {
     const placed = new Set(releases.flatMap((r) => r.stories.map((s) => s.id)));
     return {
         project: String(map.project ?? ""),
+        key: String(map.key ?? ""),
+        personas: (Array.isArray(map.personas) ? map.personas : []).map((p) => ({ id: String(p.id), title: String(p.title ?? p.id), description: String(p.description ?? "") })),
         activities: (Array.isArray(map.activities) ? map.activities : []).map((a) => ({
             id: String(a.id),
             title: String(a.title ?? a.id),
@@ -78,17 +108,23 @@ export function storyMapOf(dir) {
         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. */
+/**
+ * Each status's tint class and the word shown on its card. Blocked wins over the status, and a
+ * changed spec wins over done or approved: what was proved is no longer what the feature says.
+ */
 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" },
+    approved: { cls: "approved", word: "approved" },
+    cancelled: { cls: "cancelled", word: "cancelled" },
 };
-const statusOf = (s) => (s.blocked ? { cls: "blocked", word: "blocked" } : STATUS[s.status] ?? STATUS.todo);
+const statusOf = (s) => s.blocked ? { cls: "blocked", word: "blocked" } : s.specChanged ? { cls: "changed", word: "spec changed" } : STATUS[s.status] ?? STATUS.todo;
+const TYPE_WORD = { technical: "Technical", bug_risk: "Bug risk" };
 const pad = (n) => String(n).padStart(2, "0");
-/** The whole story map as one standalone HTML page. */
-export function renderMap(dir) {
+/** The whole story map as one standalone HTML page. live adds the dashboard's filter bar and its script. */
+export function renderMap(dir, opts = {}) {
     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));
@@ -106,24 +142,37 @@ export function renderMap(dir) {
     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 foot = s.waitingOn.length
+            ? `<span class="wait">Waits on ${esc(s.waitingOn.join(", "))}</span>`
+            : s.criteria.length
+                ? `<span>${s.criteria.length} ${s.criteria.length === 1 ? "criterion" : "criteria"}${musts ? ` · ${musts} must` : ""}</span>`
+                : `<span class="warn">No criteria</span>`;
+        const type = TYPE_WORD[s.type] ? `<span class="stype">${TYPE_WORD[s.type]}</span>` : "";
+        // data- attributes let the live dashboard filter cards; the exported page ignores them.
+        const data = `data-story="${esc(s.id)}" data-status="${esc(st.cls)}" data-type="${esc(s.type)}" data-personas="${esc(s.personas.join(" "))}" data-search="${esc(`${s.id} ${s.title} ${s.narrative}`.toLowerCase())}"`;
+        return `<a class="card ${st.cls}" ${data} href="#story-${esc(s.id)}"><span class="crow"><span class="sid">${esc(s.id)}</span>${type}<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 live = stories.filter((s) => s.status !== "cancelled");
+        const n = (f) => live.filter(f).length;
+        const approved = n((s) => s.status === "approved");
+        const parts = [
+            `${n((s) => isDone(s.status))} of ${live.length} done`,
+            ...(approved ? [`${approved} approved`] : []),
+            `${n((s) => s.status === "in_progress")} in progress`,
+            `${n((s) => s.status === "todo")} to do`,
+        ];
+        const warn = [[n((s) => s.blocked), "blocked"], [n((s) => s.specChanged), "spec changed"]];
+        return parts.join(" · ") + warn.map(([k, w]) => (k ? ` · <span class="warn">${k} ${w}</span>` : "")).join("");
     };
     const band = (id, code, heading, goal, bets, stories) => {
-        const shipped = stories.length > 0 && stories.every((s) => s.status === "done");
+        const live = stories.filter((s) => s.status !== "cancelled");
+        const shipped = live.length > 0 && live.every((s) => isDone(s.status) && !s.specChanged);
         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>`;
+        return `<section class="band" id="${esc(id)}" data-release="${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) : "";
@@ -136,13 +185,22 @@ export function renderMap(dir) {
     ].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 facts = [s.id, TYPE_WORD[s.type], s.priority, s.effort && `effort ${s.effort}`].filter(Boolean).map((f) => esc(f)).join(" · ");
+        const persona = (id) => m.personas.find((p) => p.id === id)?.title ?? id;
+        const notes = [
+            s.personas.length && `For ${s.personas.map(persona).join(", ")}`,
+            s.dependsOn.length && `Depends on ${s.dependsOn.map((d) => (s.waitingOn.includes(d) ? `${d} (not done)` : d)).join(", ")}`,
+            s.status === "approved" && `Approved by ${s.approvedBy || "someone"}`,
+            s.status === "cancelled" && `Cancelled: ${s.cancelledReason}`,
+            s.specChanged && "The feature changed after it was done, so its scenarios no longer prove it",
+        ].filter(Boolean).map((n) => `<li>${esc(n)}</li>`).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>`;
+        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>` : ""}${notes ? `<ul class="notes">${notes}</ul>` : ""}</div><div class="eyebrow">Acceptance criteria</div>${criteria}</aside></div>`;
     };
     const title = m.project ? `${m.project} · Story map` : "Story map";
+    const filters = opts.live ? filterBar(m, everything) : "";
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -153,7 +211,7 @@ export function renderMap(dir) {
 </head>
 <body>
 <header class="top"><h1>${esc(title)}</h1><nav class="jumps" aria-label="Releases">${jumps}</nav></header>
-<main>
+${filters}<main>
 <div class="board" style="--cols:${Math.max(1, columns.length)}">
 ${spine}
 ${bands}
@@ -161,10 +219,107 @@ ${unreleased}
 </div>
 </main>
 ${everything.map(panel).join("\n")}
+${opts.live ? `<script>${FILTER_JS}</script>` : ""}
 </body>
 </html>
 `;
 }
+/** Search, release, status, type and persona filters, and the release-rows switch. Live page only. */
+function filterBar(m, stories) {
+    const option = (value, text) => `<option value="${esc(value)}">${esc(text)}</option>`;
+    const statuses = [...new Set(stories.map((s) => statusOf(s)))].map((st) => st.cls);
+    const words = Object.fromEntries([...Object.values(STATUS), { cls: "blocked", word: "blocked" }, { cls: "changed", word: "spec changed" }].map((x) => [x.cls, x.word]));
+    const chips = [...new Set(statuses)]
+        .map((cls) => `<label class="chip ${esc(cls)}"><input type="checkbox" name="status" value="${esc(cls)}">${esc(words[cls] ?? cls)}</label>`)
+        .join("");
+    const types = [...new Set(stories.map((s) => s.type))].filter((t) => t !== "user_story");
+    return `<div class="filters" role="search">
+<input type="search" id="f-q" placeholder="Search stories" aria-label="Search stories">
+<select id="f-release" aria-label="Release">${option("", "All releases")}${m.releases.map((r) => option(`release-${r.number}`, `R${r.number} · ${r.title}`)).join("")}${m.unreleased.length ? option("unreleased", "Not in a release") : ""}</select>
+${types.length ? `<select id="f-type" aria-label="Story type">${option("", "All types")}${option("user_story", "User stories")}${types.map((t) => option(t, TYPE_WORD[t] ?? t)).join("")}</select>` : ""}
+${m.personas.length ? `<select id="f-persona" aria-label="Persona">${option("", "Everyone")}${m.personas.map((p) => option(p.id, p.title)).join("")}</select>` : ""}
+<fieldset class="chips"><legend>Status</legend>${chips}</fieldset>
+<label class="switch"><input type="checkbox" id="f-rows" checked>Release rows</label>
+<span id="f-count" class="count" aria-live="polite"></span>
+</div>
+`;
+}
+// Runs only on the dashboard's live map. Filters hide cards; with release rows off, every
+// release's cards are shown together in one band, column by column.
+const FILTER_JS = `
+(function () {
+  var board = document.querySelector('.board');
+  var bands = Array.prototype.slice.call(board.querySelectorAll('.band'));
+  var $ = function (id) { return document.getElementById(id); };
+  var merged = document.createElement('section');
+  merged.className = 'band';
+  merged.hidden = true;
+  merged.setAttribute('data-release', 'all');
+  var lane = document.createElement('div');
+  lane.className = 'lane';
+  var first = board.querySelector('.lane');
+  if (first) {
+    Array.prototype.forEach.call(first.children, function (cell, i) {
+      var c = document.createElement('div');
+      c.className = 'cell';
+      c.setAttribute('data-activity', cell.getAttribute('data-activity'));
+      bands.forEach(function (b) {
+        var cells = b.querySelectorAll('.lane > .cell');
+        if (cells[i]) Array.prototype.forEach.call(cells[i].children, function (card) { c.appendChild(card.cloneNode(true)); });
+      });
+      lane.appendChild(c);
+    });
+  }
+  merged.appendChild(lane);
+  board.appendChild(merged);
+
+  function value(id) { var el = $(id); return el ? el.value : ''; }
+  function apply() {
+    var q = value('f-q').trim().toLowerCase();
+    var release = value('f-release');
+    var type = value('f-type');
+    var persona = value('f-persona');
+    var rows = $('f-rows').checked;
+    var statuses = Array.prototype.map.call(document.querySelectorAll('input[name=status]:checked'), function (i) { return i.value; });
+    var filtering = q || type || persona || statuses.length;
+    var shown = 0, total = 0;
+    var match = function (card) {
+      return (!release || rows ? true : card.getAttribute('data-release-of') === release) &&
+        (!q || card.getAttribute('data-search').indexOf(q) >= 0) &&
+        (!type || card.getAttribute('data-type') === type) &&
+        (!persona || (' ' + card.getAttribute('data-personas') + ' ').indexOf(' ' + persona + ' ') >= 0) &&
+        (!statuses.length || statuses.indexOf(card.getAttribute('data-status')) >= 0);
+    };
+    bands.forEach(function (b) {
+      b.hidden = !rows || (release && b.getAttribute('data-release') !== release);
+    });
+    merged.hidden = rows;
+    var active = rows ? bands.filter(function (b) { return !b.hidden; }) : [merged];
+    active.forEach(function (b) {
+      var visible = 0;
+      Array.prototype.forEach.call(b.querySelectorAll('.card'), function (card) {
+        var ok = match(card);
+        card.hidden = !ok;
+        total++;
+        if (ok) { shown++; visible++; }
+      });
+      if (rows && filtering && !visible) b.hidden = true;
+    });
+    $('f-count').textContent = filtering || release ? shown + ' of ' + total + ' stories' : '';
+  }
+  // Remember which release each card came from, so the release filter works with rows off.
+  bands.forEach(function (b) {
+    Array.prototype.forEach.call(b.querySelectorAll('.card'), function (card) {
+      Array.prototype.forEach.call(merged.querySelectorAll('.card[data-story="' + card.getAttribute('data-story') + '"]'), function (copy) {
+        copy.setAttribute('data-release-of', b.getAttribute('data-release'));
+      });
+    });
+  });
+  document.querySelector('.filters').addEventListener('input', apply);
+  document.querySelector('.filters').addEventListener('change', apply);
+  apply();
+})();
+`;
 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; }
@@ -215,8 +370,28 @@ main { flex: 1; min-height: 0; overflow: auto; background-color: var(--paper); b
 .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); }
+.approved { --fill: #EAF6EE; --edge: #C7E6D2; --word: #1E7A50; }
+.card.approved .stitle { text-decoration: line-through; text-decoration-color: rgba(26,26,24,.35); }
+.changed { --fill: #FFF6E5; --edge: #F2D9A6; --word: #B45309; }
+.card.changed { border-left: 4px solid #D97706; }
+.cancelled { --fill: transparent; --edge: #E3E1D9; --word: #7D786E; }
+.card.cancelled { border-style: dashed; box-shadow: none; opacity: .7; }
+.card.cancelled .stitle { text-decoration: line-through; }
+.stype { font-size: 11px; padding: 0 6px; border-radius: 99px; background: var(--elevated); color: var(--ink-2); }
+.wait { color: var(--warn); }
+.notes { margin: 10px 0 0; padding-left: 18px; color: var(--ink-2); }
 .blocked { --fill: #FDECEC; --edge: #F3C2C2; --word: #B83232; }
 .card.blocked { border-left: 4px solid #D64545; }
+[hidden] { display: none !important; }
+.filters { display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px; padding: 10px 24px; border-bottom: 1px solid var(--line); background: var(--surface); }
+.filters input[type=search], .filters select { height: 30px; border: 1px solid var(--line-2); border-radius: 6px; background: var(--surface); color: var(--ink); font: inherit; padding: 0 10px; }
+.filters input[type=search] { width: 220px; max-width: 100%; }
+.chips { display: flex; flex-wrap: wrap; gap: 6px; border: 0; margin: 0; padding: 0; }
+.chips legend { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); }
+.chip { display: inline-flex; align-items: center; gap: 5px; height: 28px; padding: 0 10px; border: 1px solid var(--edge, var(--line)); border-radius: 99px; background: var(--fill, var(--surface)); color: var(--word, var(--ink)); font-size: 12px; cursor: pointer; }
+.chip input { margin: 0; accent-color: var(--brand); }
+.chip:has(input:checked) { outline: 2px solid var(--brand); outline-offset: -1px; }
+.switch { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: var(--ink-2); }
 .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); }
@@ -237,6 +412,8 @@ main { flex: 1; min-height: 0; overflow: auto; background-color: var(--paper); b
 @media (max-width: 767px) {
   body { height: auto; display: block; }
   .top { padding: 12px 16px; }
+  .filters { padding: 10px 16px; }
+  .filters input[type=search] { width: 100%; }
   main { background-image: none; }
   .board { width: auto; padding: 0 16px 32px; }
   .spine { display: none; }
@@ -258,7 +435,7 @@ export function runMap(args) {
     const out = resolve(flag("--out") ?? "storymap.html");
     const dir = resolve(flag("--dir") ?? process.cwd());
     try {
-        if (!existsSync(join(findIntentDir(dir), "storymap.yaml")))
+        if (!store().exists(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);

package/dist/commands/migrate.d.ts

@@ -0,0 +1,10 @@
+export type Layout = "per-story" | "single-file";
+export interface MigrateResult {
+    layout: Layout;
+    states: number;
+    approvals: number;
+    /** The CODEOWNERS file, when a rule for approvals was carried over to the new layout. */
+    codeowners?: string;
+}
+export declare function migrate(dir: string, to: Layout): MigrateResult;
+export declare function runMigrate(args: string[]): number;

package/dist/commands/migrate.js

@@ -0,0 +1,105 @@
+// `nikos migrate per-story`: move every story's state and approval to its own file, so people
+// and agents working on different stories in parallel branches never edit the same file.
+// intent/state.yaml keeps format_version and the run queue; each story gets intent/state/<ID>.yaml
+// and, once approved, intent/approvals/<ID>.yaml. `nikos migrate single-file` moves them back.
+// Both layouts read and write the same through lib/state-files.ts.
+import { dirname, join } from "node:path";
+import { parse, parseDocument, stringify } from "yaml";
+import { findIntentDir, read } from "../lib/project.js";
+import { approvalsDir, approvalsFile, stateDir, statePath, storyApprovalPath, storyFiles, storyStatePath } from "../lib/state-files.js";
+import { store } from "../lib/store.js";
+import { validate } from "./validate.js";
+const CODEOWNERS = ["CODEOWNERS", ".github/CODEOWNERS", ".gitlab/CODEOWNERS", "docs/CODEOWNERS"];
+/** Give a CODEOWNERS rule on approvals.yaml a matching rule on approvals/, or the other way round. */
+function carryCodeowners(root, to) {
+    const file = CODEOWNERS.map((f) => join(root, f)).find((f) => store().exists(f));
+    if (!file)
+        return undefined;
+    const text = read(file);
+    const [from, into] = to === "per-story" ? [/^(\S*intent\/)approvals\.yaml(\s+.+)$/m, "approvals/"] : [/^(\S*intent\/)approvals\/(\s+.+)$/m, "approvals.yaml"];
+    const m = text.match(from);
+    if (!m)
+        return undefined;
+    const line = `${m[1]}${into}${m[2]}`;
+    if (text.split("\n").includes(line))
+        return undefined;
+    store().write(file, `${text}${text.endsWith("\n") ? "" : "\n"}${line}\n`);
+    return file;
+}
+export function migrate(dir, to) {
+    const intent = findIntentDir(dir);
+    if (!store().exists(statePath(intent)))
+        throw new Error("No intent/state.yaml here: set nikOS up first (nikos init)");
+    const before = validate(intent);
+    if (before.errors.length)
+        throw new Error(`Fix intent/ first (nikos validate lists ${before.errors.length} ${before.errors.length === 1 ? "problem" : "problems"}), so nothing is lost moving it`);
+    const doc = parseDocument(read(statePath(intent)));
+    let states = 0;
+    let approvals = 0;
+    if (to === "per-story") {
+        const stories = doc.toJS()?.stories ?? {};
+        for (const [id, entry] of Object.entries(stories)) {
+            store().write(storyStatePath(intent, id), stringify(entry));
+            states++;
+        }
+        doc.set("stories", doc.createNode({}));
+        doc.commentBefore = `${doc.commentBefore ? `${doc.commentBefore}\n` : ""} Each story's state is in intent/state/<ID>.yaml.`;
+        store().write(statePath(intent), doc.toString({ flowCollectionPadding: false }));
+        if (store().exists(approvalsFile(intent))) {
+            for (const [id, a] of Object.entries(parse(read(approvalsFile(intent)))?.approvals ?? {})) {
+                store().write(storyApprovalPath(intent, id), stringify(a));
+                approvals++;
+            }
+            store().remove(approvalsFile(intent));
+        }
+    }
+    else {
+        for (const f of storyFiles(stateDir(intent))) {
+            doc.setIn(["stories", f.id], doc.createNode(parse(read(f.path))));
+            store().remove(f.path);
+            states++;
+        }
+        if (doc.commentBefore)
+            doc.commentBefore = doc.commentBefore.replace(/\n? Each story's state is in intent\/state\/<ID>\.yaml\./, "") || null;
+        store().write(statePath(intent), doc.toString({ flowCollectionPadding: false }));
+        const files = storyFiles(approvalsDir(intent));
+        if (files.length) {
+            const path = approvalsFile(intent);
+            const adoc = parseDocument(store().exists(path) ? read(path) : "# Sign-offs on done stories, written by nikos approve.\nformat_version: 1\napprovals: {}\n");
+            for (const f of files) {
+                adoc.setIn(["approvals", f.id], adoc.createNode(parse(read(f.path))));
+                store().remove(f.path);
+                approvals++;
+            }
+            store().write(path, adoc.toString({ flowCollectionPadding: false }));
+        }
+    }
+    const after = validate(intent);
+    if (after.errors.length)
+        throw new Error(`The move left problems in intent/; check it with nikos validate:\n${after.errors.map((e) => `  ${e.file}: ${e.message}`).join("\n")}`);
+    const codeowners = carryCodeowners(dirname(intent), to);
+    return { layout: to, states, approvals, ...(codeowners ? { codeowners } : {}) };
+}
+export function runMigrate(args) {
+    const i = args.indexOf("--dir");
+    const dir = i >= 0 ? args[i + 1] : process.cwd();
+    const to = args.find((a, n) => !a.startsWith("--") && (i < 0 || n !== i + 1));
+    if (to !== "per-story" && to !== "single-file") {
+        console.error("Usage: nikos migrate per-story | single-file [--dir <path>]\n  per-story    each story's state and approval in its own file, so parallel branches don't conflict\n  single-file  back to intent/state.yaml and intent/approvals.yaml");
+        return 1;
+    }
+    try {
+        const r = migrate(dir, to);
+        console.log(r.layout === "per-story"
+            ? `Moved ${r.states} stories to intent/state/<ID>.yaml${r.approvals ? ` and ${r.approvals} approvals to intent/approvals/<ID>.yaml` : ""}.`
+            : `Moved ${r.states} stories back to intent/state.yaml${r.approvals ? ` and ${r.approvals} approvals to intent/approvals.yaml` : ""}.`);
+        if (r.codeowners)
+            console.log(`Added a matching approvals rule to ${r.codeowners}.`);
+        console.log("Commit the change in one go, on a branch nobody else is moving stories on.");
+        return 0;
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/next.d.ts

@@ -0,0 +1,19 @@
+export interface NextResult {
+    /** The story to build next, or undefined when nothing is left to do. */
+    story?: string;
+    /** Stories already started; finish these before starting something new. */
+    open: {
+        id: string;
+        status: string;
+    }[];
+    /** Todo stories passed over because a story they depend on isn't done yet. */
+    waiting: {
+        id: string;
+        on: string[];
+    }[];
+}
+/** Each story's @depends-<id> tags, from its feature file. */
+export declare function dependencies(intentDir: string): Map<string, string[]>;
+/** The first todo story in run.queue, then in story map order, whose dependencies are all done. */
+export declare function next(dir: string): NextResult;
+export declare function runNext(args: string[]): number;

package/dist/commands/next.js

@@ -1,19 +1,41 @@
 import { join } from "node:path";
+import { loadStates } from "../lib/state-files.js";
 import { parse } from "yaml";
-import { findIntentDir, read } from "../lib/project.js";
-/** The first todo story in run.queue, then in story map order. */
+import { featureStoryIds, featureTags, findIntentDir, isDone, read, walk } from "../lib/project.js";
+/** Each story's @depends-<id> tags, from its feature file. */
+export function dependencies(intentDir) {
+    const deps = new Map();
+    for (const file of walk(join(intentDir, "features"), ".feature")) {
+        const text = read(file);
+        const id = featureStoryIds(text)[0];
+        if (id)
+            deps.set(id, featureTags(text, "depends"));
+    }
+    return deps;
+}
+/** The first todo story in run.queue, then in story map order, whose dependencies are all done. */
 export function next(dir) {
     const intentDir = findIntentDir(dir);
     const map = parse(read(join(intentDir, "storymap.yaml")));
     const state = parse(read(join(intentDir, "state.yaml")));
-    const stories = state?.stories ?? {};
+    const stories = loadStates(intentDir);
     const mapOrder = (map?.releases ?? [])
         .slice()
         .sort((a, b) => a.number - b.number)
         .flatMap((r) => r.stories ?? []);
     const order = [...new Set([...(state?.run?.queue ?? []), ...mapOrder])];
     const open = order.filter((id) => ["in_progress", "needs_rework"].includes(stories[id]?.status ?? "")).map((id) => ({ id, status: stories[id].status }));
-    return { story: order.find((id) => (stories[id]?.status ?? "todo") === "todo"), open };
+    const deps = dependencies(intentDir);
+    const waiting = [];
+    for (const id of order) {
+        if ((stories[id]?.status ?? "todo") !== "todo")
+            continue;
+        const on = (deps.get(id) ?? []).filter((d) => !isDone(stories[d]?.status));
+        if (!on.length)
+            return { story: id, open, waiting };
+        waiting.push({ id, on });
+    }
+    return { open, waiting };
 }
 export function runNext(args) {
     const i = args.indexOf("--dir");
@@ -22,7 +44,9 @@ export function runNext(args) {
         for (const o of r.open)
             console.log(`! ${o.id} is ${o.status}; finish it first`);
         if (!r.story) {
-            console.log("Nothing left to do: every story is started or done.");
+            for (const w of r.waiting)
+                console.log(`! ${w.id} is waiting on ${w.on.join(", ")}`);
+            console.log(r.waiting.length ? "Nothing is ready: every todo story waits on another." : "Nothing left to do: every story is started or done.");
             return 0;
         }
         console.log(r.story);

package/dist/commands/plan.d.ts

@@ -0,0 +1,8 @@
+export interface NewPlanOptions {
+    dir?: string;
+    summary?: string;
+    date?: string;
+}
+export declare function planVersions(intentDir: string, story: string): number[];
+export declare function newPlan(story: string, opts?: NewPlanOptions): string;
+export declare function runPlan(args: string[]): number;

package/dist/commands/plan.js

@@ -1,16 +1,17 @@
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse } from "yaml";
 import { STORY_ID, findIntentDir, read } from "../lib/project.js";
+import { store } from "../lib/store.js";
 const here = dirname(fileURLToPath(import.meta.url));
 const templateDir = [join(here, "../../templates"), join(here, "../templates")].find((d) => existsSync(d));
 export function planVersions(intentDir, story) {
     const plans = join(intentDir, "plans");
-    if (!existsSync(plans))
+    if (!store().exists(plans))
         return [];
     const re = new RegExp(`^${story}\\.v(\\d+)\\.md$`);
-    return readdirSync(plans)
+    return store().list(plans)
         .map((f) => re.exec(f)?.[1])
         .filter((v) => !!v)
         .map(Number)
@@ -21,7 +22,7 @@ export function newPlan(story, opts = {}) {
         throw new Error(`'${story}' is not a story id (expected e.g. HT-1)`);
     const intentDir = findIntentDir(opts.dir ?? process.cwd());
     const mapPath = join(intentDir, "storymap.yaml");
-    if (existsSync(mapPath)) {
+    if (store().exists(mapPath)) {
         const map = parse(read(mapPath));
         const known = (map?.releases ?? []).some((r) => (r?.stories ?? []).includes(story));
         if (!known)
@@ -30,16 +31,16 @@ export function newPlan(story, opts = {}) {
     const versions = planVersions(intentDir, story);
     const version = (versions.at(-1) ?? 0) + 1;
     const path = join(intentDir, "plans", `${story}.v${version}.md`);
-    const content = read(join(templateDir, "plan.md"))
+    // The template ships with nikOS, so it's always read from disk.
+    const content = readFileSync(join(templateDir, "plan.md"), "utf8")
         .replace("{{story}}", story)
         .replace("{{version}}", String(version))
         .replace("{{date}}", opts.date ?? new Date().toISOString().slice(0, 10))
         .replace("{{supersedes}}", version > 1 ? `supersedes: ${version - 1}\n` : "")
         .replace("{{summary}}", opts.summary ?? "One to three plain sentences on the approach.")
         .replace("{{first_step}}", "First step, in eight words or fewer");
-    mkdirSync(dirname(path), { recursive: true });
-    // "wx" fails if the file exists, so an earlier plan can never be overwritten.
-    writeFileSync(path, content, { flag: "wx" });
+    // create fails if the file exists, so an earlier plan can never be overwritten.
+    store().write(path, content, { create: true });
     return path;
 }
 export function runPlan(args) {