@purview-dev/pm-docs-site 0.0.0-stage → 0.1.0-pre.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/LICENSE.md +9 -0
  2. package/README.md +167 -2
  3. package/cli.mjs +120 -0
  4. package/index.d.ts +49 -0
  5. package/index.mjs +97 -0
  6. package/lib/options.mjs +67 -0
  7. package/lib/repo-docs.mjs +148 -0
  8. package/lib/schema-version.mjs +29 -0
  9. package/lib/sidebar.mjs +47 -0
  10. package/lib/site-options.mjs +38 -0
  11. package/package.json +62 -5
  12. package/src/components/ExportStamp.astro +29 -0
  13. package/src/components/FeatureSummary.astro +160 -0
  14. package/src/components/FeatureTable.astro +64 -0
  15. package/src/components/ItemDetail.astro +16 -0
  16. package/src/components/ItemDialog.astro +16 -0
  17. package/src/components/LinkedFrom.astro +33 -0
  18. package/src/components/LinkedText.astro +12 -0
  19. package/src/components/PlanInteractions.astro +18 -0
  20. package/src/components/RefLink.astro +18 -0
  21. package/src/components/StateBadge.astro +15 -0
  22. package/src/components/lib/KanbanItemCard.astro +264 -0
  23. package/src/components/lib/StatusTimelineFeed.astro +194 -0
  24. package/src/components/lib/TaskKanbanCard.astro +215 -0
  25. package/src/content.config.ts +16 -0
  26. package/src/env.d.ts +7 -0
  27. package/src/lib/planning-types.ts +207 -0
  28. package/src/lib/planning.ts +387 -0
  29. package/src/lib/references.ts +360 -0
  30. package/src/loaders/repo-docs.ts +69 -0
  31. package/src/pages/index.astro +158 -0
  32. package/src/pages/plan/board.astro +140 -0
  33. package/src/pages/plan/log.astro +83 -0
  34. package/src/pages/plan/risks/[id].astro +72 -0
  35. package/src/pages/plan/risks.astro +263 -0
  36. package/src/pages/plan/roadmap.astro +90 -0
  37. package/src/routes/plan/briefs.astro +66 -0
  38. package/src/routes/plan/features/[id].astro +113 -0
  39. package/src/routes/plan/features/index.astro +29 -0
  40. package/src/routes/plan/inbox.astro +78 -0
  41. package/src/routes/plan/milestones/[milestone].astro +113 -0
  42. package/src/routes/plan/milestones/index.astro +56 -0
  43. package/src/routes/plan/now.astro +135 -0
  44. package/src/routes/plan/strategy.astro +194 -0
  45. package/src/scripts/plan.ts +86 -0
  46. package/src/styles/components.css +374 -0
  47. package/src/styles/width.css +4 -0
@@ -0,0 +1,207 @@
1
+ // The part of planning.json (pm-export, schemaVersion 3) the site reads.
2
+ // The full shape is planning.schema.json; only what the pages use is typed.
3
+
4
+ export type Owner = 'agent' | 'user' | 'both';
5
+ export type Size = 'S' | 'M' | 'L';
6
+ export type Level = 'low' | 'medium' | 'high';
7
+ export type Rag = 'red' | 'amber' | 'green';
8
+ export type Stage = 'design' | 'plan' | 'execute' | 'finish';
9
+
10
+ export interface ItemRef {
11
+ id: string;
12
+ title: string;
13
+ }
14
+
15
+ export interface Milestone {
16
+ id: string;
17
+ name: string;
18
+ serves: string[];
19
+ exitCriteria: string | null;
20
+ target: string | null;
21
+ status: string | null;
22
+ }
23
+
24
+ export interface RoadmapItem {
25
+ id: string;
26
+ title: string;
27
+ section: 'next' | 'later';
28
+ position: number;
29
+ label: 'next' | 'later' | 'blocked' | 'waiting';
30
+ serves: string[];
31
+ milestone: string | null;
32
+ owner: Owner;
33
+ doneWhen: string;
34
+ size: Size;
35
+ dependsOn: string[];
36
+ status: { value: 'ready' | 'paused' | 'blocked'; reason: string | null; since: string | null };
37
+ brief: string | null;
38
+ note: string | null;
39
+ revisits: string | null;
40
+ claimable: boolean;
41
+ }
42
+
43
+ export interface Card {
44
+ id: string;
45
+ title: string;
46
+ owner: Owner | null;
47
+ size: Size | null;
48
+ detail: string | null;
49
+ }
50
+
51
+ export interface DoneEntry {
52
+ date: string;
53
+ id: string | null;
54
+ title: string;
55
+ milestone: string | null;
56
+ owner: string | null;
57
+ plan: string | null;
58
+ result: string | null;
59
+ }
60
+
61
+ export interface DroppedEntry {
62
+ date: string;
63
+ id: string | null;
64
+ title: string;
65
+ reason: string | null;
66
+ }
67
+
68
+ export interface Activity {
69
+ date: string;
70
+ kind: 'done' | 'dropped' | 'review';
71
+ id: string | null;
72
+ title: string | null;
73
+ milestone: string | null;
74
+ owner: string | null;
75
+ result: string | null;
76
+ }
77
+
78
+ export interface Checkpoint {
79
+ at: string;
80
+ stoppedAt: string | null;
81
+ nextAction: string | null;
82
+ startWith: string | null;
83
+ decisions: string | null;
84
+ context: string | null;
85
+ openQuestion: string | null;
86
+ }
87
+
88
+ export interface PlanTask {
89
+ number: number;
90
+ title: string;
91
+ checked: number;
92
+ total: number;
93
+ steps: { text: string; checked: boolean }[];
94
+ }
95
+
96
+ export interface InboxEntry {
97
+ file: string;
98
+ title: string;
99
+ captured: string | null;
100
+ source: string | null;
101
+ kind: 'feature' | 'bug' | 'improvement' | 'question' | 'inspiration' | 'tech-debt' | null;
102
+ severity: 'blocker' | 'major' | 'minor' | 'cosmetic' | null;
103
+ affects: string | null;
104
+ context: string | null;
105
+ discuss: 'yes' | 'no';
106
+ related: string[];
107
+ brief: string | null;
108
+ reviewed: string | null;
109
+ idea: string | null;
110
+ }
111
+
112
+ export interface Brief {
113
+ path: string;
114
+ id: string | null;
115
+ title: string;
116
+ status: string | null;
117
+ origin: string | null;
118
+ updated: string | null;
119
+ decision: string | null;
120
+ problem: string | null;
121
+ doneWhen: string | null;
122
+ revisions: { date: string | null; text: string }[];
123
+ }
124
+
125
+ export interface Risk {
126
+ id: string;
127
+ title: string;
128
+ likelihood: Level;
129
+ impact: Level;
130
+ rag: Rag;
131
+ ragOverride: string | null;
132
+ status: 'open' | 'mitigating' | 'accepted' | 'closed';
133
+ owner: Owner;
134
+ affects: string | null;
135
+ trigger: string | null;
136
+ mitigation: string | null;
137
+ raised: string | null;
138
+ reviewed: string | null;
139
+ closed: string | null;
140
+ }
141
+
142
+ export interface RemovedRisk {
143
+ date: string;
144
+ id: string;
145
+ title: string;
146
+ reason: string | null;
147
+ }
148
+
149
+ export interface Planning {
150
+ schemaVersion: 3;
151
+ generatedAt: string;
152
+ source: { branch: string | null; head: string | null };
153
+ vision: {
154
+ problem: string | null;
155
+ customer: string | null;
156
+ outcomes: { id: string; text: string }[];
157
+ outOfScope: string[];
158
+ constraints: { timeAvailable: string | null; budget: string | null; stack: string | null };
159
+ };
160
+ strategy: {
161
+ focus: { milestone: string | null; whyNow: string | null };
162
+ milestones: Milestone[];
163
+ bets: { id: string; statement: string; evidence: string | null; signal: string | null; status: string | null }[];
164
+ assumptions: { id: string; statement: string; test: string | null; status: string | null }[];
165
+ notDoing: { thing: string; why: string | null; revisit: string | null }[];
166
+ decisions: { date: string | null; decision: string; why: string | null; rejected: string | null }[];
167
+ };
168
+ now: {
169
+ status: 'idle' | 'active';
170
+ item: ItemRef | null;
171
+ stage: Stage | null;
172
+ session: string | null;
173
+ brief: string | null;
174
+ milestone: string | null;
175
+ spec: string | null;
176
+ plan: string | null;
177
+ started: string | null;
178
+ doneWhen: string[];
179
+ checkpoint: Checkpoint | null;
180
+ };
181
+ plan: { path: string; checked: number; total: number; tasks: PlanTask[] } | null;
182
+ roadmap: { next: RoadmapItem[]; later: RoadmapItem[] };
183
+ board: {
184
+ columns: { now: Card[]; next: Card[]; foryou: Card[]; waiting: Card[]; done: DoneEntry[] };
185
+ activity: Activity[];
186
+ };
187
+ log: { done: DoneEntry[]; dropped: DroppedEntry[]; reviews: { date: string; summary: string | null }[] };
188
+ inbox: InboxEntry[];
189
+ briefs: Brief[];
190
+ risks: { open: Risk[]; closed: Risk[]; removed: RemovedRisk[] };
191
+ counts: {
192
+ next: number;
193
+ later: number;
194
+ nextMax: number;
195
+ openInbox: number;
196
+ discuss: number;
197
+ shapingBriefs: number;
198
+ done: number;
199
+ dropped: number;
200
+ blockers: number;
201
+ openRisks: number;
202
+ redRisks: number;
203
+ amberRisks: number;
204
+ greenRisks: number;
205
+ };
206
+ checks: { reviewDue: boolean; lastReview: string | null; claimable: string[]; drift: boolean };
207
+ }
@@ -0,0 +1,387 @@
1
+ // The plan, read from planning.json and shaped for the plan pages.
2
+ //
3
+ // planning.json is written by the pm-export skill from the Markdown PM state;
4
+ // it is the only source of plan data on this site. Nothing here parses the PM
5
+ // Markdown, and nothing on a page is typed by hand.
6
+
7
+ import { readFileSync } from 'node:fs';
8
+ import { relative, sep } from 'node:path';
9
+
10
+ import config from 'virtual:pm-docs-site/config';
11
+
12
+ import type { DocsSource } from '../../index';
13
+ import { pagesOf } from '../../lib/repo-docs.mjs';
14
+ import { checkSchemaVersion, PlanningExportError, SUPPORTED_SCHEMA_VERSIONS } from '../../lib/schema-version.mjs';
15
+ import type { Brief, InboxEntry, Level, Milestone, Owner, Planning, Rag, Risk, RoadmapItem, Size, Stage } from './planning-types';
16
+
17
+ export { PlanningExportError, SUPPORTED_SCHEMA_VERSIONS };
18
+
19
+ /** Read and check the export: by default the one the integration's `planning` option names. */
20
+ export function loadPlanning(path: string = config.planning): Planning {
21
+ let text: string;
22
+
23
+ try {
24
+ text = readFileSync(path, 'utf8');
25
+ } catch {
26
+ throw new PlanningExportError(`No plan export at ${path}.`);
27
+ }
28
+
29
+ let planning: { schemaVersion?: unknown };
30
+
31
+ try {
32
+ planning = JSON.parse(text);
33
+ } catch (error) {
34
+ throw new PlanningExportError(`${path} is not valid JSON (${(error as Error).message}).`);
35
+ }
36
+
37
+ checkSchemaVersion(planning.schemaVersion, path);
38
+
39
+ return planning as Planning;
40
+ }
41
+
42
+ /** Board-card priority from item size — the PM state has no priority of its own. */
43
+ export function sizeToPriority(size: Size | null): 'low' | 'medium' | 'high' {
44
+ return size === 'L' ? 'high' : size === 'M' ? 'medium' : 'low';
45
+ }
46
+
47
+ /** The owner as a card's initials. A missing owner means `agent` (PM rules). */
48
+ export function initials(owner: Owner | string | null): string {
49
+ return owner === 'user' ? 'YOU' : owner === 'both' ? 'AG+U' : 'AG';
50
+ }
51
+
52
+ export interface TimelineEvent {
53
+ /** The item's ID, or `null` for a log line without one. */
54
+ id: string | null;
55
+ title: string;
56
+ desc: string;
57
+ time: string;
58
+ status: 'done' | 'active' | 'pending';
59
+ }
60
+
61
+ export interface RoadmapGroup {
62
+ milestone: {
63
+ id: string;
64
+ name: string;
65
+ status: string | null;
66
+ exitCriteria: string | null;
67
+ isFocus: boolean;
68
+ } | null;
69
+ events: TimelineEvent[];
70
+ /** Done items against every item in the group (done, in progress and queued). */
71
+ progress: { done: number; total: number };
72
+ }
73
+
74
+ /**
75
+ * One group per milestone in strategy order, then "no milestone": the Done log
76
+ * (newest first), the Now item, then Next and Later in roadmap order.
77
+ */
78
+ export function roadmapGroups(planning: Planning): RoadmapGroup[] {
79
+ const groupOf = (milestone: string | null) => milestoneId(milestone, planning.strategy.milestones);
80
+ const focus = planning.strategy.focus.milestone ?? '';
81
+
82
+ const eventsFor = (id: string | null): TimelineEvent[] => [
83
+ ...planning.log.done
84
+ .filter((entry) => groupOf(entry.milestone) === id)
85
+ .map((entry) => ({
86
+ id: entry.id,
87
+ title: label(entry.id, entry.title),
88
+ desc: entry.result ?? '',
89
+ time: entry.date,
90
+ status: 'done' as const,
91
+ })),
92
+ ...(planning.now.item && groupOf(planning.now.milestone) === id
93
+ ? [
94
+ {
95
+ id: planning.now.item.id,
96
+ title: label(planning.now.item.id, planning.now.item.title),
97
+ desc: planning.now.stage ? `In progress: ${planning.now.stage}` : 'In progress',
98
+ time: 'Now',
99
+ status: 'active' as const,
100
+ },
101
+ ]
102
+ : []),
103
+ ...[...planning.roadmap.next, ...planning.roadmap.later]
104
+ .filter((item) => groupOf(item.milestone) === id)
105
+ .map((item) => ({
106
+ id: item.id,
107
+ title: label(item.id, item.title),
108
+ desc: item.doneWhen,
109
+ time: item.section === 'next' ? 'Next' : 'Later',
110
+ status: 'pending' as const,
111
+ })),
112
+ ];
113
+
114
+ const groups: RoadmapGroup[] = planning.strategy.milestones.map((milestone) => ({
115
+ milestone: {
116
+ id: milestone.id,
117
+ name: milestone.name,
118
+ status: milestone.status,
119
+ exitCriteria: milestone.exitCriteria,
120
+ isFocus: milestoneId(focus, [milestone]) !== null,
121
+ },
122
+ ...withProgress(eventsFor(milestone.id)),
123
+ }));
124
+
125
+ const unassigned = eventsFor(null);
126
+
127
+ return unassigned.length > 0 ? [...groups, { milestone: null, ...withProgress(unassigned) }] : groups;
128
+ }
129
+
130
+ function withProgress(events: TimelineEvent[]): Pick<RoadmapGroup, 'events' | 'progress'> {
131
+ return { events, progress: { done: events.filter((event) => event.status === 'done').length, total: events.length } };
132
+ }
133
+
134
+ const LEVELS: Level[] = ['low', 'medium', 'high'];
135
+
136
+ /**
137
+ * The RAG the PM rules derive from likelihood and impact (low 1, medium 2,
138
+ * high 3; a product of 6 or more is red, 3 or 4 amber, otherwise green).
139
+ * A risk's own `rag` may differ when it carries an override; it colours the
140
+ * risk, and this colours a matrix cell.
141
+ */
142
+ export function derivedRag(likelihood: Level, impact: Level): Rag {
143
+ const score = (LEVELS.indexOf(likelihood) + 1) * (LEVELS.indexOf(impact) + 1);
144
+
145
+ return score >= 6 ? 'red' : score >= 3 ? 'amber' : 'green';
146
+ }
147
+
148
+ export interface MatrixCell {
149
+ likelihood: Level;
150
+ impact: Level;
151
+ rag: Rag;
152
+ risks: Risk[];
153
+ }
154
+
155
+ /** The likelihood × impact grid: rows from high impact down, columns from low likelihood up. */
156
+ export function riskMatrix(risks: Risk[]): MatrixCell[][] {
157
+ return [...LEVELS].reverse().map((impact) =>
158
+ LEVELS.map((likelihood) => ({
159
+ likelihood,
160
+ impact,
161
+ rag: derivedRag(likelihood, impact),
162
+ risks: risks.filter((risk) => risk.likelihood === likelihood && risk.impact === impact),
163
+ })),
164
+ );
165
+ }
166
+
167
+ /**
168
+ * Every repository docs page this site builds, keyed by its file relative to
169
+ * the docs root (`/`-separated). The first source to claim a file wins, as in
170
+ * the repo-docs loader.
171
+ */
172
+ export function docsPages(docs: { root: string; sources: DocsSource[] } | null = config.docs): Map<string, string> {
173
+ const pages = new Map<string, string>();
174
+ const ids = new Set<string>();
175
+
176
+ for (const source of docs?.sources ?? []) {
177
+ for (const page of pagesOf(source, docs!.root)) {
178
+ const file = relative(docs!.root, page.file).split(sep).join('/');
179
+
180
+ if (pages.has(file) || ids.has(page.id)) continue;
181
+ ids.add(page.id);
182
+ pages.set(file, page.id === 'index' ? '/' : `/${page.id}/`);
183
+ }
184
+ }
185
+
186
+ return pages;
187
+ }
188
+
189
+ let sitePages: Map<string, string> | undefined;
190
+
191
+ /** The site URL of a repository file named in the plan, or `null` when this site does not build it as a page. */
192
+ export function docsHref(path: string | null, pages: Map<string, string> = (sitePages ??= docsPages())): string | null {
193
+ const file = path?.trim().replace(/^\.\//, '') ?? '';
194
+
195
+ return pages.get(file) ?? null;
196
+ }
197
+
198
+ function label(id: string | null, title: string): string {
199
+ return id ? `${id} ${title}` : title;
200
+ }
201
+
202
+ /**
203
+ * The known milestone a value names: its ID (`M2`) or its ID and name
204
+ * (`M2 Billing`). Anything else (`none`, an unknown ID, `null`) is no milestone.
205
+ */
206
+ export function milestoneId(value: string | null, milestones: Pick<Milestone, 'id'>[]): string | null {
207
+ const text = value?.trim() ?? '';
208
+
209
+ return milestones.find((milestone) => text === milestone.id || text.startsWith(`${milestone.id} `))?.id ?? null;
210
+ }
211
+
212
+ /** A plan's completion as a whole percentage; `0` when there is no plan or it has no steps. */
213
+ export function planProgress(plan: { checked: number; total: number } | null): number {
214
+ return plan && plan.total > 0 ? Math.round((plan.checked / plan.total) * 100) : 0;
215
+ }
216
+
217
+ /** Inbox severity as a card priority: the inbox has no priority of its own. */
218
+ export function severityToPriority(severity: InboxEntry['severity']): 'low' | 'medium' | 'high' | 'urgent' {
219
+ return severity === 'blocker' ? 'urgent' : severity === 'major' ? 'high' : severity === 'minor' ? 'medium' : 'low';
220
+ }
221
+
222
+ export type FeatureState = 'now' | 'next' | 'later' | 'done' | 'dropped';
223
+
224
+ /** The words each state is shown with, in the order the Features page lists them. */
225
+ export const FEATURE_STATES: Record<FeatureState, string> = {
226
+ now: 'In progress',
227
+ next: 'Next',
228
+ later: 'Later',
229
+ done: 'Done',
230
+ dropped: 'Dropped',
231
+ };
232
+
233
+ /**
234
+ * One roadmap item wherever the export holds it — the Now item, Next, Later,
235
+ * the Done log, or the Dropped log — with the fields that place holds.
236
+ */
237
+ export interface Feature {
238
+ id: string;
239
+ title: string;
240
+ state: FeatureState;
241
+ /** A known milestone ID (`milestoneId`), or `null`. */
242
+ milestone: string | null;
243
+ owner: string | null;
244
+ size: Size | null;
245
+ serves: string[];
246
+ doneWhen: string[];
247
+ dependsOn: string[];
248
+ label: RoadmapItem['label'] | null;
249
+ status: RoadmapItem['status'] | null;
250
+ position: number | null;
251
+ brief: string | null;
252
+ note: string | null;
253
+ revisits: string | null;
254
+ stage: Stage | null;
255
+ started: string | null;
256
+ /** Done or dropped: the log date. */
257
+ date: string | null;
258
+ result: string | null;
259
+ plan: string | null;
260
+ reason: string | null;
261
+ }
262
+
263
+ /** Every item with an ID, in this order: Now, Next, Later, Done (newest first), Dropped (newest first). */
264
+ export function features(planning: Planning): Feature[] {
265
+ const known = planning.strategy.milestones;
266
+ const blank = { serves: [], doneWhen: [], dependsOn: [], label: null, status: null, position: null, brief: null, note: null, revisits: null, stage: null, started: null, date: null, result: null, plan: null, reason: null };
267
+ const now = planning.now.item
268
+ ? [
269
+ {
270
+ ...blank,
271
+ id: planning.now.item.id,
272
+ title: planning.now.item.title,
273
+ state: 'now' as const,
274
+ milestone: milestoneId(planning.now.milestone, known),
275
+ owner: planning.board.columns.now[0]?.owner ?? null,
276
+ size: planning.board.columns.now[0]?.size ?? null,
277
+ doneWhen: planning.now.doneWhen,
278
+ brief: planning.now.brief,
279
+ stage: planning.now.stage,
280
+ started: planning.now.started,
281
+ plan: planning.now.plan,
282
+ },
283
+ ]
284
+ : [];
285
+ const queued = [...planning.roadmap.next, ...planning.roadmap.later].map((item) => ({
286
+ ...blank,
287
+ id: item.id,
288
+ title: item.title,
289
+ state: item.section,
290
+ milestone: milestoneId(item.milestone, known),
291
+ owner: item.owner,
292
+ size: item.size,
293
+ serves: item.serves,
294
+ doneWhen: item.doneWhen ? [item.doneWhen] : [],
295
+ dependsOn: item.dependsOn,
296
+ label: item.label,
297
+ status: item.status,
298
+ position: item.position,
299
+ brief: item.brief,
300
+ note: item.note,
301
+ revisits: item.revisits,
302
+ }));
303
+ const done = planning.log.done.flatMap((entry) =>
304
+ entry.id
305
+ ? [{ ...blank, id: entry.id, title: entry.title, state: 'done' as const, milestone: milestoneId(entry.milestone, known), owner: entry.owner, size: null, date: entry.date, result: entry.result, plan: entry.plan }]
306
+ : [],
307
+ );
308
+ const dropped = planning.log.dropped.flatMap((entry) =>
309
+ entry.id ? [{ ...blank, id: entry.id, title: entry.title, state: 'dropped' as const, milestone: null, owner: null, size: null, date: entry.date, reason: entry.reason }] : [],
310
+ );
311
+
312
+ const seen = new Set<string>();
313
+
314
+ return [...now, ...queued, ...done, ...dropped].filter((feature) => !seen.has(feature.id) && seen.add(feature.id));
315
+ }
316
+
317
+ /** The items whose `Depends on` names `id`. */
318
+ export function dependents(all: Feature[], id: string): Feature[] {
319
+ return all.filter((feature) => feature.dependsOn.includes(id));
320
+ }
321
+
322
+ /** The brief a feature links to, by its `Brief` path, else by the brief's own ID. */
323
+ export function briefOf(planning: Planning, feature: Pick<Feature, 'id' | 'brief'>): Brief | null {
324
+ return planning.briefs.find((brief) => brief.path === feature.brief) ?? planning.briefs.find((brief) => brief.id === feature.id) ?? null;
325
+ }
326
+
327
+ export interface MilestoneSummary {
328
+ /** `null` for the items with no milestone. */
329
+ id: string | null;
330
+ /** The page slug: the lower-case ID, or `none`. */
331
+ slug: string;
332
+ name: string;
333
+ status: string | null;
334
+ target: string | null;
335
+ exitCriteria: string | null;
336
+ serves: string[];
337
+ isFocus: boolean;
338
+ features: Feature[];
339
+ /** Done items against every item that is not dropped. */
340
+ progress: { done: number; total: number };
341
+ }
342
+
343
+ /** One summary per milestone in strategy order, then `No milestone` when an item has none. */
344
+ export function milestoneSummaries(planning: Planning, all: Feature[] = features(planning)): MilestoneSummary[] {
345
+ const focus = planning.strategy.focus.milestone;
346
+ const summary = (milestone: Milestone | null): MilestoneSummary => {
347
+ const members = all.filter((feature) => feature.milestone === (milestone?.id ?? null));
348
+ const counted = members.filter((feature) => feature.state !== 'dropped');
349
+
350
+ return {
351
+ id: milestone?.id ?? null,
352
+ slug: milestone ? milestone.id.toLowerCase() : 'none',
353
+ name: milestone?.name ?? 'No milestone',
354
+ status: milestone?.status ?? null,
355
+ target: milestone?.target ?? null,
356
+ exitCriteria: milestone?.exitCriteria ?? null,
357
+ serves: milestone?.serves ?? [],
358
+ isFocus: milestone ? milestoneId(focus, [milestone]) !== null : false,
359
+ features: members,
360
+ progress: { done: counted.filter((feature) => feature.state === 'done').length, total: counted.length },
361
+ };
362
+ };
363
+ const groups = planning.strategy.milestones.map(summary);
364
+ const unassigned = summary(null);
365
+
366
+ return unassigned.features.length > 0 ? [...groups, unassigned] : groups;
367
+ }
368
+
369
+ /** An inbox file's source as a card's initials: `agent (…)` → `AG`, anything else (the user) → `YOU`. */
370
+ export function sourceInitials(source: string | null): string {
371
+ return /^agent\b/i.test(source?.trim() ?? '') ? 'AG' : 'YOU';
372
+ }
373
+
374
+ /** The anchor of a brief's row on the Briefs page: its file name without `.md`, lower-case. */
375
+ export function briefAnchor(path: string): string {
376
+ return (path.split('/').at(-1) ?? path).replace(/\.md$/i, '').toLowerCase();
377
+ }
378
+
379
+ /** The page of one item on this site. */
380
+ export function featureHref(id: string): string {
381
+ return `/plan/features/${id.toLowerCase()}/`;
382
+ }
383
+
384
+ /** The page of one milestone on this site; `null` is the `No milestone` page. */
385
+ export function milestoneHref(id: string | null): string {
386
+ return `/plan/milestones/${id ? id.toLowerCase() : 'none'}/`;
387
+ }