@repo-os/repoos 0.5.51 → 0.5.52

package/README.md

@@ -308,10 +308,9 @@ loopback servers need zero setup; remote servers use short-lived, revocable
 capability tokens (created over HTTPS on the server, stored in the Keychain)
 for their attention and search endpoints.
 
-The Hub's DMG is published on
-[GitHub Releases](https://github.com/repo-os/repoos/releases) with each tag
-release (the first Hub DMG is pending). Setup, pairing, and limitation details
-are in the [Hub guide](https://github.com/repo-os/repoos/blob/main/user-docs/macos-hub.md).
+Download the latest [RepoOS Hub DMG](https://github.com/repo-os/repoos/releases/latest/download/RepoOSHub.dmg),
+or browse [GitHub Releases](https://github.com/repo-os/repoos/releases). Setup,
+pairing, and limitation details are in the [Hub guide](https://docs.repoos.org/macos-hub).
 
 ## Roadmap
 

package/dist/.build-info.json

@@ -1,4 +1,4 @@
 {
-  "hash": "9978dc66ddd3de60d301a374cf6cf80f0e7f6fa67545d1dcab764e930f29b35a",
-  "version": "0.5.51"
+  "hash": "c59ba0faf030004be937d5bd9fb28afc6fdd9156857ae68454cba1c959f0f979",
+  "version": "0.5.52"
 }

package/dist/.build-stamp.json

@@ -1,3 +1,3 @@
 {
-  "generatedAt": "2026-09-23T02:28:26.540Z"
+  "generatedAt": "2026-09-23T08:36:16.981Z"
 }

package/dist/core/git.d.ts

@@ -396,6 +396,13 @@ export declare function preflightMerge(root: string, branch: string, opts?: {
  * is not clean; callers should treat that as a merge blocker.
  */
 export declare function commitTaskFile(root: string, absPath: string, message: string): boolean;
+/**
+ * `commitTaskFile` for several paths in one commit — e.g. a story definition
+ * renamed on disk, where both the removed old path and the new one must land
+ * together. A path may be deleted from the working tree; `git add` stages the
+ * removal. Same fail-soft contract and `--only` scoping as `commitTaskFile`.
+ */
+export declare function commitFiles(root: string, absPaths: string[], message: string): boolean;
 /**
  * The dirty/uncommitted file paths in a checkout (`git status --porcelain`),
  * including tracked modifications and untracked files, in repo-relative form.

package/dist/core/git.js

@@ -1047,20 +1047,30 @@ export async function preflightMerge(root, branch, opts = {}) {
  * is not clean; callers should treat that as a merge blocker.
  */
 export function commitTaskFile(root, absPath, message) {
-    const rel = relative(root, absPath);
-    if (rel.startsWith("..") || isAbsolute(rel))
+    return commitFiles(root, [absPath], message);
+}
+/**
+ * `commitTaskFile` for several paths in one commit — e.g. a story definition
+ * renamed on disk, where both the removed old path and the new one must land
+ * together. A path may be deleted from the working tree; `git add` stages the
+ * removal. Same fail-soft contract and `--only` scoping as `commitTaskFile`.
+ */
+export function commitFiles(root, absPaths, message) {
+    const rels = absPaths.map((p) => relative(root, p));
+    if (rels.length === 0 || rels.some((rel) => rel.startsWith("..") || isAbsolute(rel))) {
         return false;
-    const status = git(root, ["status", "--porcelain", "--", rel]);
+    }
+    const status = git(root, ["status", "--porcelain", "--", ...rels]);
     if (status === null)
         return false;
     if (status.trim() === "")
         return true;
-    if (git(root, ["add", "--", rel]) === null)
+    if (git(root, ["add", "-A", "--", ...rels]) === null)
         return false;
-    // `--only` with a pathspec commits just this file and leaves everything else
-    // already in the index staged (#0353): a plain `git commit` would sweep in
-    // whatever a human or agent had staged in the checkout under our message.
-    return git(root, ["commit", "-o", "-m", message, "--", rel]) !== null;
+    // `--only` with a pathspec commits just these files and leaves everything
+    // else already in the index staged (#0353): a plain `git commit` would sweep
+    // in whatever a human or agent had staged in the checkout under our message.
+    return git(root, ["commit", "-o", "-m", message, "--", ...rels]) !== null;
 }
 /**
  * The dirty/uncommitted file paths in a checkout (`git status --porcelain`),

package/dist/core/review-verdict.d.ts

@@ -14,10 +14,11 @@
  * The UI was right and the server's gate was wrong — this is now the single
  * shared implementation both sides use, so they can never disagree again.
  *
- * Order matters: each list is checked most-specific-first so a report that
- * mentions a milder verdict in passing while explaining a worse one (e.g.
- * "back to the drawing board" text discussing what would merely "need some
- * work") doesn't get misread as the mild outcome.
+ * When the report has a `## Verdict` section, only that section is read (the
+ * first non-empty line there). Review prose often names the other outcomes
+ * while discussing tests or alternatives; scanning the entire report can turn
+ * a declared "good to go" into a false rejection. Reports without that heading
+ * (legacy) still use a whole-document scan so older stored reports keep working.
  */
 export type ReviewVerdict = "good to go" | "needs some work" | "back to the drawing board";
 export type ReviewRelevance = "still relevant" | "no longer needed" | "needs rescoping";

package/dist/core/review-verdict.js

@@ -14,10 +14,11 @@
  * The UI was right and the server's gate was wrong — this is now the single
  * shared implementation both sides use, so they can never disagree again.
  *
- * Order matters: each list is checked most-specific-first so a report that
- * mentions a milder verdict in passing while explaining a worse one (e.g.
- * "back to the drawing board" text discussing what would merely "need some
- * work") doesn't get misread as the mild outcome.
+ * When the report has a `## Verdict` section, only that section is read (the
+ * first non-empty line there). Review prose often names the other outcomes
+ * while discussing tests or alternatives; scanning the entire report can turn
+ * a declared "good to go" into a false rejection. Reports without that heading
+ * (legacy) still use a whole-document scan so older stored reports keep working.
  */
 const VERDICT_ORDER = [
     "back to the drawing board",
@@ -29,16 +30,28 @@ const RELEVANCE_ORDER = [
     "needs rescoping",
     "still relevant",
 ];
-export function parseReviewVerdict(markdown) {
-    if (!markdown)
-        return null;
-    const lower = markdown.toLowerCase();
+function verdictFromText(text) {
+    const lower = text.toLowerCase();
     for (const label of VERDICT_ORDER) {
         if (lower.includes(label))
             return label;
     }
     return null;
 }
+export function parseReviewVerdict(markdown) {
+    if (!markdown)
+        return null;
+    const heading = /^#{1,6}\s+verdict\s*$/im.exec(markdown);
+    if (heading) {
+        const section = markdown
+            .slice((heading.index ?? 0) + heading[0].length)
+            .split(/^#{1,6}\s+/m, 1)[0];
+        const line = section.split(/\r?\n/).find((value) => value.trim());
+        return line ? verdictFromText(line) : null;
+    }
+    // Legacy reports without a Verdict heading: scan the full body.
+    return verdictFromText(markdown);
+}
 export function parseReviewRelevance(markdown) {
     if (!markdown)
         return null;

package/dist/core/review-verdict.test.js

@@ -23,12 +23,18 @@ describe("parseReviewVerdict", () => {
     it("prefers the worse verdict when a milder one is only mentioned in passing", () => {
         expect(parseReviewVerdict("## Verdict\nback to the drawing board — closer work would only need some work, but this misses the mark entirely.")).toBe("back to the drawing board");
     });
+    it("uses the declared verdict instead of later mentions in suggestions", () => {
+        expect(parseReviewVerdict("## Verdict\n`good to go` — nothing blocks sign-off.\n\n## Suggestions\nTest needs some work and back to the drawing board paths too.")).toBe("good to go");
+    });
     it("is case-insensitive", () => {
         expect(parseReviewVerdict("## Verdict\nGood To Go.")).toBe("good to go");
     });
     it("returns null when no known verdict phrase is present", () => {
         expect(parseReviewVerdict("## Bugs\nNone found.")).toBeNull();
     });
+    it("scans the full document for legacy reports without a Verdict heading", () => {
+        expect(parseReviewVerdict("## Summary\nStill reviewing.\n\n## Outcome\ngood to go — ship it when ready.")).toBe("good to go");
+    });
 });
 describe("parseReviewRelevance", () => {
     it("parses a bold-wrapped relevance label", () => {

package/dist/core/story-definition-files.d.ts

@@ -0,0 +1,49 @@
+import type { RepoOSConfig } from "./types.js";
+import type { StoryDefinition } from "./story-display.js";
+export declare const STORIES_DIR = "stories";
+export declare function fallbackStoryName(text: string): string;
+export declare function setStoryPmWorking(path: string, on: boolean): void;
+export declare function isStoryPmWorking(path: string): boolean;
+export declare function storySlug(name: string): string;
+export declare function collisionFreeStoryPath(config: RepoOSConfig, name: string, 
+/** A path the caller is replacing, so it never counts as a collision. */
+ownPath?: string): string;
+export declare function parseStoryDefinitionFile(content: string, path: string): StoryDefinition | null;
+export declare function listStoryDefinitions(config: RepoOSConfig): StoryDefinition[];
+export declare function findStoryDefinitionByKey(config: RepoOSConfig, key: string): StoryDefinition | null;
+export interface WriteStoryDefinitionInput {
+    name: string;
+    body: string;
+    createdBy?: string;
+    path?: string;
+}
+export declare function writeStoryDefinition(config: RepoOSConfig, input: WriteStoryDefinitionInput): StoryDefinition;
+/**
+ * Replace an existing definition's name and body in place, keeping its
+ * `created_at` / `created_by`. The PM flesh-out uses this to swap the
+ * placeholder written at submit time for the generated story. When the new
+ * name slugs differently the file is renamed to match; `previousPath` is set
+ * then so the caller can commit the removal too.
+ */
+export declare function rewriteStoryDefinition(config: RepoOSConfig, path: string, input: {
+    name: string;
+    body: string;
+}): {
+    definition: StoryDefinition;
+    previousPath?: string;
+};
+export interface ParsedGeneratedStory {
+    name: string;
+    body: string;
+    /** Ids of existing tasks the PM judged part of this story. */
+    taskIds: string[];
+    hadFrontmatter: boolean;
+}
+/** An existing task the PM may pull into a new story. */
+export interface StoryTaskCandidate {
+    id: string;
+    title: string;
+    status: string;
+}
+export declare function storyFreeformPrompt(humanName: string, description: string, candidates?: StoryTaskCandidate[]): string;
+export declare function parseGeneratedStoryDefinition(rawOutput: string, humanName: string, rawDescription: string): ParsedGeneratedStory;

package/dist/core/story-definition-files.js

@@ -0,0 +1,252 @@
+/**
+ * Git-tracked story definition files under `stories/` (#0486). Node-only I/O.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { FM_DELIM, parseDocument, serializeDocument } from "./frontmatter.js";
+import { normalizeStoryName, storyKey } from "./stories.js";
+export const STORIES_DIR = "stories";
+export function fallbackStoryName(text) {
+    const line = text
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => Boolean(l) && l !== FM_DELIM) ?? "";
+    if (line.length > 0) {
+        return line.length <= 60 ? line : `${line.slice(0, 57).trimEnd()}…`;
+    }
+    const flat = text
+        .replace(/\s+/g, " ")
+        .replace(/\s*---\s*/g, " ")
+        .trim();
+    return flat.length <= 60 ? flat || "Untitled story" : `${flat.slice(0, 57).trimEnd()}…`;
+}
+function storiesRoot(config) {
+    return join(config.root, STORIES_DIR);
+}
+function isStoryFile(name) {
+    return name.endsWith(".md") && !name.startsWith(".");
+}
+/**
+ * Story files the PM agent is fleshing out right now (by repo-relative path).
+ * In-memory on purpose: a server reload drops the run, and the indicator must
+ * clear with it rather than stick. Written by `src/server/story-pm.ts`.
+ */
+const pmWorking = new Set();
+export function setStoryPmWorking(path, on) {
+    if (on)
+        pmWorking.add(path);
+    else
+        pmWorking.delete(path);
+}
+export function isStoryPmWorking(path) {
+    return pmWorking.has(path);
+}
+export function storySlug(name) {
+    return (normalizeStoryName(name)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 55) || "story");
+}
+export function collisionFreeStoryPath(config, name, 
+/** A path the caller is replacing, so it never counts as a collision. */
+ownPath) {
+    const base = storySlug(name);
+    let path = `${STORIES_DIR}/${base}.md`;
+    let n = 2;
+    while (path !== ownPath && existsSync(join(config.root, path))) {
+        path = `${STORIES_DIR}/${base}-${n}.md`;
+        n += 1;
+    }
+    return path;
+}
+export function parseStoryDefinitionFile(content, path) {
+    const { data, body, hadFrontmatter } = parseDocument(content);
+    if (!hadFrontmatter)
+        return null;
+    const name = normalizeStoryName(data.name);
+    if (!name)
+        return null;
+    const createdAt = typeof data.created_at === "string" && data.created_at.trim() ? data.created_at.trim() : "";
+    const createdBy = typeof data.created_by === "string" && data.created_by.trim() ? data.created_by.trim() : "";
+    return {
+        key: storyKey(name),
+        name,
+        path,
+        body: body.trim(),
+        createdAt,
+        createdBy,
+    };
+}
+export function listStoryDefinitions(config) {
+    const dir = storiesRoot(config);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(isStoryFile)
+        .map((file) => {
+        const path = `${STORIES_DIR}/${file}`;
+        try {
+            return parseStoryDefinitionFile(readFileSync(join(dir, file), "utf8"), path);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((d) => d !== null)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findStoryDefinitionByKey(config, key) {
+    const k = key.toLowerCase();
+    return listStoryDefinitions(config).find((d) => d.key === k) ?? null;
+}
+export function writeStoryDefinition(config, input) {
+    const name = normalizeStoryName(input.name);
+    if (!name)
+        throw new Error("story name is required");
+    const body = input.body.trim();
+    if (!body)
+        throw new Error("story description is required");
+    const existing = findStoryDefinitionByKey(config, storyKey(name));
+    if (existing) {
+        throw new Error(`A story named "${existing.name}" already exists`);
+    }
+    const path = input.path ?? collisionFreeStoryPath(config, name);
+    if (!path.startsWith(`${STORIES_DIR}/`) || !path.endsWith(".md")) {
+        throw new Error("invalid story definition path");
+    }
+    const createdAt = new Date().toISOString();
+    const createdBy = input.createdBy?.trim() || "unknown";
+    const content = serializeDocument({ name, created_at: createdAt, created_by: createdBy }, body.endsWith("\n") ? body : `${body}\n`);
+    const absPath = join(config.root, path);
+    mkdirSync(storiesRoot(config), { recursive: true });
+    writeFileSync(absPath, content, "utf8");
+    return {
+        key: storyKey(name),
+        name,
+        path,
+        body,
+        createdAt,
+        createdBy,
+    };
+}
+/**
+ * Replace an existing definition's name and body in place, keeping its
+ * `created_at` / `created_by`. The PM flesh-out uses this to swap the
+ * placeholder written at submit time for the generated story. When the new
+ * name slugs differently the file is renamed to match; `previousPath` is set
+ * then so the caller can commit the removal too.
+ */
+export function rewriteStoryDefinition(config, path, input) {
+    const absOld = join(config.root, path);
+    if (!existsSync(absOld))
+        throw new Error(`story definition not found: ${path}`);
+    const current = parseStoryDefinitionFile(readFileSync(absOld, "utf8"), path);
+    if (!current)
+        throw new Error(`story definition is unreadable: ${path}`);
+    const name = normalizeStoryName(input.name);
+    if (!name)
+        throw new Error("story name is required");
+    const body = input.body.trim();
+    if (!body)
+        throw new Error("story description is required");
+    const clash = findStoryDefinitionByKey(config, storyKey(name));
+    if (clash && clash.path !== path) {
+        throw new Error(`A story named "${clash.name}" already exists`);
+    }
+    const nextPath = storySlug(name) === storySlug(current.name) ? path : collisionFreeStoryPath(config, name, path);
+    const content = serializeDocument({ name, created_at: current.createdAt, created_by: current.createdBy }, `${body}\n`);
+    writeFileSync(join(config.root, nextPath), content, "utf8");
+    if (nextPath !== path)
+        unlinkSync(absOld);
+    return {
+        definition: {
+            key: storyKey(name),
+            name,
+            path: nextPath,
+            body,
+            createdAt: current.createdAt,
+            createdBy: current.createdBy,
+        },
+        previousPath: nextPath !== path ? path : undefined,
+    };
+}
+export function storyFreeformPrompt(humanName, description, candidates = []) {
+    const nameHint = humanName.trim().length > 0
+        ? `The human already chose the story name: "${normalizeStoryName(humanName)}". Use that exact name in frontmatter.`
+        : "The human did not provide a name — propose a concise story name in frontmatter.";
+    const taskList = candidates.length
+        ? [
+            "",
+            "Existing tasks that are not yet tagged with any story (id · status · title).",
+            "If any of them clearly belong to this story, list their ids in a `tasks`",
+            "frontmatter list. Leave it out (or empty) when none fit — only include a",
+            "task you are confident belongs here.",
+            "",
+            ...candidates.map((t) => `${t.id} · ${t.status} · ${t.title.replace(/\s+/g, " ")}`),
+        ]
+        : [];
+    return [
+        "You are the PM agent for RepoOS. Turn the user's freeform description into a",
+        "story definition: a delivery slice that may later be broken into tasks tagged",
+        "with the same story name. This is NOT a task file — no id, status, branch, or",
+        "assignee.",
+        "",
+        nameHint,
+        "",
+        "The user's description:",
+        "",
+        "```",
+        description.trim(),
+        "```",
+        ...taskList,
+        "",
+        "Respond with a frontmatter block and markdown body only, like:",
+        "---",
+        "name: Project updates email",
+        'tasks: ["0123", "0456"]',
+        "---",
+        "",
+        "# Project updates email",
+        "",
+        "Scope, outcomes, non-goals, and open questions in helpful PM prose.",
+        "",
+        "Do NOT include created_at or created_by — the system sets those.",
+        "Respond with ONLY the frontmatter block and body, starting with '---', with no",
+        "preamble, commentary, or code fences.",
+    ].join("\n");
+}
+function parseTaskIds(raw) {
+    const items = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(/[\s,]+/) : [];
+    const ids = items
+        .map((v) => String(v ?? "")
+        .replace(/^#/, "")
+        .trim())
+        .filter((v) => /^\d+$/.test(v))
+        .map((v) => v.padStart(4, "0"));
+    return [...new Set(ids)];
+}
+export function parseGeneratedStoryDefinition(rawOutput, humanName, rawDescription) {
+    // Agents sometimes wrap the whole answer in a ```markdown fence despite the
+    // prompt; unwrap it so the frontmatter is still found.
+    const trimmed = rawOutput.trim();
+    const fenced = trimmed.match(/^```[a-z]*\n([\s\S]*?)\n```$/i);
+    const { data, body, hadFrontmatter } = parseDocument(fenced ? fenced[1].trim() : trimmed);
+    const fromFm = typeof data.name === "string" && data.name.trim() ? normalizeStoryName(data.name) : "";
+    const human = normalizeStoryName(humanName);
+    if (hadFrontmatter && (fromFm || body.trim())) {
+        return {
+            // The human's explicit name always wins over the PM's proposal.
+            name: human || fromFm || fallbackStoryName(rawDescription),
+            body: body.trim() || rawDescription.trim(),
+            taskIds: parseTaskIds(data.tasks),
+            hadFrontmatter: true,
+        };
+    }
+    return {
+        name: human || fallbackStoryName(rawDescription),
+        body: rawDescription.trim(),
+        taskIds: [],
+        hadFrontmatter: false,
+    };
+}

package/dist/core/story-definitions.d.ts

@@ -0,0 +1,3 @@
+/** Re-exports for server/tests — UI must import `./story-display.js` only. */
+export * from "./story-display.js";
+export * from "./story-definition-files.js";

package/dist/core/story-definitions.js

@@ -0,0 +1,3 @@
+/** Re-exports for server/tests — UI must import `./story-display.js` only. */
+export * from "./story-display.js";
+export * from "./story-definition-files.js";

package/dist/core/story-display.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser-safe story display helpers (#0486): merge registered definitions with
+ * task-derived roll-ups. No Node imports — safe for the UI bundle.
+ */
+import { type StoryGroup, type StoryTaskLike } from "./stories.js";
+export interface StoryDefinition {
+    key: string;
+    name: string;
+    path: string;
+    body: string;
+    createdAt: string;
+    createdBy: string;
+}
+export interface MergedStoryGroup extends StoryGroup {
+    excerpt: string;
+    body: string;
+    registered: boolean;
+}
+export declare function storyExcerpt(body: string, max?: number): string;
+export declare function mergeStoriesForDisplay<T extends StoryTaskLike>(tasks: T[], definitions: StoryDefinition[]): MergedStoryGroup[];

package/dist/core/story-display.js

@@ -0,0 +1,55 @@
+/**
+ * Browser-safe story display helpers (#0486): merge registered definitions with
+ * task-derived roll-ups. No Node imports — safe for the UI bundle.
+ */
+import { deriveStories, sortStories } from "./stories.js";
+import { STATUSES } from "./types.js";
+export function storyExcerpt(body, max = 200) {
+    const flat = body
+        .replace(/^#+\s+/gm, "")
+        .replace(/[*_`>#-]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (flat.length <= max)
+        return flat;
+    return `${flat.slice(0, max - 1).trimEnd()}…`;
+}
+export function mergeStoriesForDisplay(tasks, definitions) {
+    const defByKey = new Map(definitions.map((d) => [d.key, d]));
+    const derived = deriveStories(tasks);
+    const merged = [];
+    const seen = new Set();
+    for (const group of derived) {
+        seen.add(group.key);
+        const def = defByKey.get(group.key);
+        merged.push({
+            ...group,
+            name: def?.name ?? group.name,
+            excerpt: def ? storyExcerpt(def.body) : "",
+            body: def?.body ?? "",
+            registered: !!def,
+        });
+    }
+    const emptyCounts = () => Object.fromEntries(STATUSES.map((s) => [s, 0]));
+    for (const def of definitions) {
+        if (seen.has(def.key))
+            continue;
+        merged.push({
+            key: def.key,
+            name: def.name,
+            tasks: [],
+            total: 0,
+            done: 0,
+            counts: emptyCounts(),
+            active: 0,
+            review: 0,
+            attention: 0,
+            complete: false,
+            lastActivity: null,
+            excerpt: storyExcerpt(def.body),
+            body: def.body,
+            registered: true,
+        });
+    }
+    return sortStories(merged);
+}

package/dist/core/types.d.ts

@@ -1095,4 +1095,17 @@ export interface BoardIndex {
     taskCount: number;
     tasks: BoardTask[];
     counts: Record<Status, number>;
+    /** Registered story definition files (`stories/*.md`) when `[stories] enabled`. */
+    storyDefinitions?: StoryDefinitionRecord[];
+}
+/** One git-tracked story definition surfaced on the board payload (#0486). */
+export interface StoryDefinitionRecord {
+    key: string;
+    name: string;
+    path: string;
+    body: string;
+    createdAt: string;
+    createdBy: string;
+    /** True while the PM agent is fleshing this story out in the background. */
+    pmWorking?: boolean;
 }

package/dist/server/live-index.d.ts

@@ -104,7 +104,7 @@ export type RepoEvent = {
  | {
     type: "review";
     id: string;
-    state: "running" | "ready" | "failed" | "cancelled";
+    state: "running" | "ready" | "failed" | "incomplete" | "cancelled";
     at: string;
     error?: string;
 }
@@ -154,6 +154,19 @@ export type RepoEvent = {
     type: "hello";
     taskCount: number;
     at: string;
+} | {
+    type: "story.definitionsChanged";
+    at: string;
+}
+/** The PM finished fleshing out a New story (ok or not); `path` is its final file. */
+ | {
+    type: "story.pmFinished";
+    path: string;
+    name: string;
+    ok: boolean;
+    reason?: string;
+    taggedTaskIds: string[];
+    at: string;
 } | {
     type: "system.stats";
     stats: SystemStats;
@@ -308,5 +321,7 @@ export declare class LiveIndex {
     boardSnapshot(): BoardIndex;
     on(fn: Listener): () => void;
     private emit;
+    /** Story definition files under `stories/` changed on disk (#0486). */
+    notifyStoryDefinitionsChanged(): void;
 }
 export {};

package/dist/server/live-index.js

@@ -14,6 +14,7 @@ import { STATUSES, PRIORITIES } from "../core/types.js";
 import { parseTask } from "../core/task.js";
 import { isGitRepo, localBranches, lastCommitForFile, worktreeStatus, worktreePaths, worktreeList, currentBranch, emptyGitInfo, resolveWorktreeStatuses, } from "../core/git.js";
 import { buildIndex, buildIndexAsync, readWorktreeDirtyCache, writeWorktreeDirtyCache, } from "../core/indexer.js";
+import { isStoryPmWorking, listStoryDefinitions } from "../core/story-definition-files.js";
 import { patchTaskFile } from "./write.js";
 function priorityRank(p) {
     const i = PRIORITIES.indexOf(p);
@@ -352,7 +353,7 @@ export class LiveIndex {
     /** Lightweight board snapshot — skips body, extra, agent overrides. */
     boardSnapshot() {
         const tasks = this.getTasks();
-        return {
+        const base = {
             version: 1,
             generatedAt: now(),
             root: this.config.root,
@@ -360,6 +361,18 @@ export class LiveIndex {
             tasks: tasks.map(toBoardTask),
             counts: this.counts(),
         };
+        if (this.config.stories?.enabled === true) {
+            base.storyDefinitions = listStoryDefinitions(this.config).map((d) => ({
+                key: d.key,
+                name: d.name,
+                path: d.path,
+                body: d.body,
+                createdAt: d.createdAt,
+                createdBy: d.createdBy,
+                pmWorking: isStoryPmWorking(d.path),
+            }));
+        }
+        return base;
     }
     // ---- events ----
     on(fn) {
@@ -376,6 +389,10 @@ export class LiveIndex {
             }
         }
     }
+    /** Story definition files under `stories/` changed on disk (#0486). */
+    notifyStoryDefinitionsChanged() {
+        this.emit({ type: "story.definitionsChanged", at: now() });
+    }
 }
 function now() {
     return new Date().toISOString();