project-spec 0.8.0 → 0.9.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.
@@ -228,6 +228,10 @@
228
228
  padding-left: 40px;
229
229
  color: var(--muted);
230
230
  }
231
+ .tree-row.part {
232
+ padding-left: 58px;
233
+ font-size: 0.94em;
234
+ }
231
235
 
232
236
  /* Top bar: where you are, and what you can do with the page. */
233
237
  .topbar {
@@ -243,8 +247,8 @@
243
247
  background: var(--paper);
244
248
  }
245
249
  .icon-btn {
246
- width: 44px;
247
- height: 44px;
250
+ width: 36px;
251
+ height: 36px;
248
252
  display: grid;
249
253
  place-items: center;
250
254
  border: 1px solid var(--line-strong);
@@ -306,11 +310,11 @@
306
310
  font-weight: 600;
307
311
  }
308
312
  .btn {
309
- height: 44px;
313
+ height: 36px;
310
314
  display: inline-flex;
311
315
  align-items: center;
312
316
  gap: 8px;
313
- padding: 0 18px;
317
+ padding: 0 14px;
314
318
  border: 1px solid var(--line-strong);
315
319
  border-radius: 999px;
316
320
  background: var(--paper);
@@ -326,9 +330,8 @@
326
330
  background: var(--accent);
327
331
  }
328
332
  .btn.large {
329
- height: 50px;
330
- padding: 0 24px;
331
- font-size: 15px;
333
+ height: 40px;
334
+ padding: 0 18px;
332
335
  }
333
336
  .pillrow {
334
337
  display: flex;
@@ -336,15 +339,15 @@
336
339
  gap: 8px;
337
340
  }
338
341
  .pill {
339
- height: 44px;
342
+ height: 34px;
340
343
  display: inline-flex;
341
344
  align-items: center;
342
- gap: 8px;
343
- padding: 0 16px;
345
+ gap: 7px;
346
+ padding: 0 13px;
344
347
  border: 1px solid var(--line-strong);
345
348
  border-radius: 999px;
346
349
  background: var(--paper);
347
- font: 600 14px/1 var(--sans);
350
+ font: 600 13px/1 var(--sans);
348
351
  }
349
352
  .pill[aria-pressed="true"] {
350
353
  border-color: var(--ink);
@@ -356,12 +359,25 @@
356
359
  opacity: 0.75;
357
360
  }
358
361
  select {
359
- height: 44px;
360
- padding: 0 14px;
362
+ height: 34px;
363
+ padding: 0 12px;
361
364
  border: 1px solid var(--line-strong);
362
365
  border-radius: 999px;
363
366
  background: var(--paper);
364
- font-size: 14px;
367
+ font-size: 13px;
368
+ }
369
+ /* A finger needs more room than a mouse pointer. */
370
+ @media (pointer: coarse) {
371
+ .btn,
372
+ .pill,
373
+ select {
374
+ height: 44px;
375
+ }
376
+ .icon-btn,
377
+ .xbtn {
378
+ width: 44px;
379
+ height: 44px;
380
+ }
365
381
  }
366
382
 
367
383
  /* Page */
@@ -417,6 +433,48 @@
417
433
  gap: 24px;
418
434
  max-width: 860px;
419
435
  }
436
+ .stack.wide {
437
+ max-width: 1100px;
438
+ }
439
+ .area-grid {
440
+ display: grid;
441
+ grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
442
+ gap: 16px;
443
+ }
444
+ .area-card h2 button {
445
+ border: 0;
446
+ padding: 0;
447
+ background: none;
448
+ font: inherit;
449
+ text-align: left;
450
+ }
451
+ .area-card h2 button:hover {
452
+ text-decoration: underline;
453
+ }
454
+ .area-card .names {
455
+ display: flex;
456
+ flex-direction: column;
457
+ gap: 6px;
458
+ margin-top: 4px;
459
+ }
460
+ .area-card .names button {
461
+ border: 0;
462
+ padding: 0;
463
+ background: none;
464
+ font-size: 14px;
465
+ text-align: left;
466
+ overflow: hidden;
467
+ text-overflow: ellipsis;
468
+ white-space: nowrap;
469
+ }
470
+ .area-card .names button:hover {
471
+ color: var(--accent-ink);
472
+ text-decoration: underline;
473
+ }
474
+ .area-card .names button.more {
475
+ color: var(--muted);
476
+ font-size: 13px;
477
+ }
420
478
  .page {
421
479
  display: flex;
422
480
  flex-wrap: wrap;
@@ -486,20 +544,20 @@
486
544
  .badge {
487
545
  display: inline-flex;
488
546
  align-items: center;
489
- gap: 8px;
490
- min-height: 30px;
491
- padding: 0 12px;
547
+ gap: 6px;
548
+ min-height: 24px;
549
+ padding: 0 10px;
492
550
  border-radius: 999px;
493
551
  background: var(--soft);
494
552
  color: var(--ink);
495
- font-size: 13px;
553
+ font-size: 12px;
496
554
  font-weight: 600;
497
555
  white-space: nowrap;
498
556
  }
499
557
  .badge::before {
500
558
  content: "";
501
- width: 8px;
502
- height: 8px;
559
+ width: 6px;
560
+ height: 6px;
503
561
  border-radius: 999px;
504
562
  background: var(--subtle);
505
563
  }
@@ -542,10 +600,10 @@
542
600
  gap: 8px;
543
601
  }
544
602
  .chip {
545
- min-height: 44px;
603
+ min-height: 32px;
546
604
  display: inline-flex;
547
605
  align-items: center;
548
- padding: 6px 16px;
606
+ padding: 4px 13px;
549
607
  border: 1px solid var(--line);
550
608
  border-radius: 999px;
551
609
  background: var(--paper);
@@ -893,8 +951,8 @@
893
951
  }
894
952
  .xbtn {
895
953
  flex: none;
896
- width: 44px;
897
- height: 44px;
954
+ width: 36px;
955
+ height: 36px;
898
956
  display: grid;
899
957
  place-items: center;
900
958
  border: 0;
@@ -1277,7 +1335,7 @@
1277
1335
  min-height: 32px;
1278
1336
  }
1279
1337
  .copy-card .btn {
1280
- height: 40px;
1338
+ height: 36px;
1281
1339
  }
1282
1340
  @media (max-width: 820px) {
1283
1341
  .copy-card {
@@ -1675,6 +1733,20 @@
1675
1733
  const i = STATES.indexOf(stateOf(n));
1676
1734
  return i < 0 ? STATES.length : i;
1677
1735
  };
1736
+ // Priority is free text. The usual words and P0-P4 sort from most to least urgent, any other
1737
+ // value after them, and a gap without a priority last.
1738
+ const PRIORITY_RANKS = { critical: 0, urgent: 0, highest: 0, high: 1, medium: 2, normal: 2, low: 3, lowest: 4 };
1739
+ const priorityOf = (n) => str(n.priority).trim().toLowerCase();
1740
+ const priorityRank = (n) => {
1741
+ const p = priorityOf(n),
1742
+ digit = /^p?([0-4])$/.exec(p);
1743
+ if (!p) return 6;
1744
+ if (digit) return +digit[1];
1745
+ return Object.prototype.hasOwnProperty.call(PRIORITY_RANKS, p) ? PRIORITY_RANKS[p] : 5;
1746
+ };
1747
+ // The order of every list of gaps: by state, then the most urgent first, then by title.
1748
+ const byGapOrder = (a, b) =>
1749
+ stateRank(a) - stateRank(b) || priorityRank(a) - priorityRank(b) || byTitle(a, b);
1678
1750
  const stateClass = (n) =>
1679
1751
  isGap(n)
1680
1752
  ? "st-" + stateOf(n)
@@ -2181,7 +2253,7 @@
2181
2253
  if (g && isGap(g)) out.set(g.id, g);
2182
2254
  });
2183
2255
  return [...out.values()].sort(
2184
- (a, b) => stateRank(a) - stateRank(b) || byTitle(a, b),
2256
+ byGapOrder,
2185
2257
  );
2186
2258
  }
2187
2259
  const planOf = (g) => nodes.find((p) => isPlan(p) && p.gap === g.id);
@@ -2256,11 +2328,18 @@
2256
2328
  }
2257
2329
  const primaryArea = (n) => (n.areas || [])[0] || "";
2258
2330
  const isFeature = (n) => n.type === "note" && n.status !== "superseded";
2331
+ // A part of a feature: a note whose `parent` names another note. One level only, so the tree is
2332
+ // area, feature, part; a parent that is missing or is itself a part is ignored.
2333
+ const parentOf = (n) => {
2334
+ const p = n.type === "note" && str(n.parent) ? byId.get(n.parent) : null;
2335
+ return p && p !== n && isFeature(p) && !str(p.parent) ? p : null;
2336
+ };
2337
+ const partsOf = (n) => nodes.filter((p) => isFeature(p) && parentOf(p) === n).sort(byTitle);
2259
2338
  const featuresOf = (area) =>
2260
- nodes.filter((n) => isFeature(n) && primaryArea(n) === area.id).sort(byTitle);
2339
+ nodes.filter((n) => isFeature(n) && primaryArea(n) === area.id && !parentOf(n)).sort(byTitle);
2261
2340
  const looseFeatures = () =>
2262
2341
  nodes
2263
- .filter((n) => isFeature(n) && byId.get(primaryArea(n))?.type !== "area")
2342
+ .filter((n) => isFeature(n) && byId.get(primaryArea(n))?.type !== "area" && !parentOf(n))
2264
2343
  .sort(byTitle);
2265
2344
  const waiting = (n) =>
2266
2345
  gapsAbout(n).filter((g) =>
@@ -2374,15 +2453,23 @@
2374
2453
  });
2375
2454
  const tree = $("#tree");
2376
2455
  tree.replaceChildren();
2377
- const noteRow = (f) => {
2378
- const b = button(null, "tree-row note", () => openNode(f)),
2379
- open = waiting(f).length;
2456
+ const noteRow = (f, cls, folded) => {
2457
+ const b = button(null, "tree-row note" + (cls ? " " + cls : ""), () => openNode(f)),
2458
+ open = waiting(f).length,
2459
+ meta = [open && open + " open", folded && plural(folded, "part")].filter(Boolean).join(" · ");
2380
2460
  b.append(el("span", f.title, "label"));
2381
2461
  b.title = f.title; // the row shows one line; the full name is a hover away
2382
- if (open) b.append(el("span", open + " open", "meta"));
2462
+ if (meta) b.append(el("span", meta, "meta"));
2383
2463
  b.setAttribute("aria-current", selected === f ? "page" : "false");
2384
2464
  return b;
2385
2465
  };
2466
+ // A feature's parts are listed under it while the reader is on the feature or on one of them.
2467
+ const featureRows = (f) => {
2468
+ const parts = partsOf(f),
2469
+ unfolded = parts.length && (selected === f || parts.includes(selected));
2470
+ tree.append(noteRow(f, "", unfolded ? 0 : parts.length));
2471
+ if (unfolded) parts.forEach((p) => tree.append(noteRow(p, "part")));
2472
+ };
2386
2473
  areas.forEach((a) => {
2387
2474
  const open = openAreas.has(a.id),
2388
2475
  line = el("div", null, "tree-area"),
@@ -2403,12 +2490,12 @@
2403
2490
  name.setAttribute("aria-current", selected === a ? "page" : "false");
2404
2491
  line.append(twist, name);
2405
2492
  tree.append(line);
2406
- if (open) featuresOf(a).forEach((f) => tree.append(noteRow(f)));
2493
+ if (open) featuresOf(a).forEach(featureRows);
2407
2494
  });
2408
2495
  const loose = looseFeatures();
2409
2496
  if (loose.length) {
2410
2497
  tree.append(el("div", "Other", "eyebrow"));
2411
- loose.forEach((f) => tree.append(noteRow(f)));
2498
+ loose.forEach(featureRows);
2412
2499
  }
2413
2500
  if (!areas.length && !loose.length) tree.append(el("p", "No pages yet.", "empty"));
2414
2501
  }
@@ -2424,6 +2511,7 @@
2424
2511
  if (n) {
2425
2512
  const parent = n.type === "note" ? byId.get(primaryArea(n)) : null;
2426
2513
  if (parent && parent.type === "area") parts.push([parent.title, { name: "page", id: parent.id }]);
2514
+ if (parentOf(n)) parts.push([parentOf(n).title, { name: "page", id: parentOf(n).id }]);
2427
2515
  if (isGap(n) || isPlan(n)) parts.push(["Gaps", { name: "gaps", id: "" }]);
2428
2516
  if (isPlan(n) && byId.get(n.gap)) parts.push([byId.get(n.gap).title, { name: "page", id: n.gap }]);
2429
2517
  parts.push([n.title, null]);
@@ -2478,6 +2566,16 @@
2478
2566
  open = waiting(f).length;
2479
2567
  item.append(button(f.title, "rowlink", () => openNode(f)));
2480
2568
  if (str(f.summary).trim()) item.append(el("p", f.summary, "muted"));
2569
+ const parts = partsOf(f);
2570
+ if (parts.length) {
2571
+ const line = el("p", null, "muted small parts");
2572
+ line.append(el("span", plural(parts.length, "part") + ": "));
2573
+ parts.forEach((part, i) => {
2574
+ if (i) line.append(document.createTextNode(", "));
2575
+ line.append(button(part.title, "wiki", () => openNode(part)));
2576
+ });
2577
+ item.append(line);
2578
+ }
2481
2579
  if (open) item.append(el("span", plural(open, "open question"), "muted small"));
2482
2580
  box.append(item);
2483
2581
  });
@@ -2510,18 +2608,38 @@
2510
2608
  };
2511
2609
 
2512
2610
  // --- Views ---------------------------------------------------------------------------------------
2611
+ // The overview is a map of the areas, not every feature of every area: a card says what the area
2612
+ // covers, how much is in it and names a few features; the area's own page has the full list.
2613
+ const HOME_NAMES = 5;
2614
+ function areaCard(a) {
2615
+ const card = el("section", null, "card pad area-card"),
2616
+ h = el("h2", null, "h2"),
2617
+ features = featuresOf(a),
2618
+ count = nodes.filter((n) => isFeature(n) && primaryArea(n) === a.id).length,
2619
+ open = nodes.filter((g) => isGap(g) && inArea(g, a.id) && ["needs-recheck", "needs-decision"].includes(stateOf(g))).length;
2620
+ h.append(button(a.title, null, () => openNode(a)));
2621
+ card.append(h);
2622
+ if (str(a.summary).trim()) card.append(el("p", a.summary, "muted"));
2623
+ card.append(el("p", [plural(count, "page"), open && plural(open, "open question")].filter(Boolean).join(" · "), "muted small"));
2624
+ const names = el("div", null, "names");
2625
+ features.slice(0, HOME_NAMES).forEach((f) => {
2626
+ const b = button(f.title, null, () => openNode(f));
2627
+ b.title = f.title;
2628
+ names.append(b);
2629
+ });
2630
+ if (features.length > HOME_NAMES)
2631
+ names.append(button("All " + features.length + " features", "more", () => openNode(a)));
2632
+ if (features.length) card.append(names);
2633
+ return card;
2634
+ }
2513
2635
  function viewHome(view) {
2514
- const box = el("div", null, "stack");
2636
+ const box = el("div", null, "stack wide");
2515
2637
  box.append(header("Overview", projectTitle, "What the product does today, area by area."));
2516
- areas.forEach((a) => {
2517
- const section = el("section"),
2518
- h = el("h2", null, "h2");
2519
- h.append(button(a.title, null, () => openNode(a)));
2520
- section.append(h);
2521
- if (str(a.summary).trim()) section.append(el("p", a.summary, "muted"));
2522
- section.append(featureList(featuresOf(a)));
2523
- box.append(section);
2524
- });
2638
+ if (areas.length) {
2639
+ const grid = el("div", null, "area-grid");
2640
+ areas.forEach((a) => grid.append(areaCard(a)));
2641
+ box.append(grid);
2642
+ }
2525
2643
  const loose = looseFeatures();
2526
2644
  if (loose.length) {
2527
2645
  const section = el("section");
@@ -2541,6 +2659,8 @@
2541
2659
  path.append(button(projectTitle, null, () => go({ name: "home", id: "" })));
2542
2660
  const parent = n.type === "note" ? byId.get(primaryArea(n)) : null;
2543
2661
  if (parent && parent.type === "area") path.append(button(parent.title, null, () => openNode(parent)));
2662
+ const feature = parentOf(n);
2663
+ if (feature) path.append(button(feature.title, null, () => openNode(feature)));
2544
2664
  if (isGap(n) || isPlan(n)) path.append(button("Gaps", null, () => go({ name: "gaps", id: "" })));
2545
2665
  path.append(el("span", n.title, "now"));
2546
2666
  card.append(path);
@@ -2551,7 +2671,7 @@
2551
2671
  // Pages this one links to or is linked from: a short list beside the text, not a block inside it.
2552
2672
  if (layerOf(n) === "spec") {
2553
2673
  const related = neighbours(n, "spec").filter(
2554
- (r) => r.id !== parent?.id && !(n.type === "area" && primaryArea(r) === n.id),
2674
+ (r) => r.id !== parent?.id && r !== feature && !(n.type === "area" && primaryArea(r) === n.id),
2555
2675
  );
2556
2676
  if (related.length) {
2557
2677
  const list = el("div", null, "recent"),
@@ -2572,6 +2692,22 @@
2572
2692
  box.append(list);
2573
2693
  }
2574
2694
  }
2695
+ // A gap is a question about something: the features it links to, then its areas.
2696
+ if (isGap(n)) {
2697
+ const about = neighbours(n, "spec"),
2698
+ own = (n.areas || []).map((id) => byId.get(id)).filter((a) => a && a.type === "area"),
2699
+ pages = [...new Set([...about.filter((r) => r.type === "note"), ...about.filter((r) => r.type !== "note"), ...own])];
2700
+ if (pages.length) {
2701
+ const list = el("div", null, "recent");
2702
+ list.append(el("div", "This gap is about", "mono-label"));
2703
+ pages.forEach((r) => {
2704
+ const b = button(r.title, null, () => openNode(r));
2705
+ if (r.type !== "note") b.append(el("span", " · area", "muted"));
2706
+ list.append(b);
2707
+ });
2708
+ box.append(list);
2709
+ }
2710
+ }
2575
2711
  const others = recent.filter((id) => id !== n.id).slice(0, 5);
2576
2712
  if (others.length) {
2577
2713
  const list = el("div", null, "recent");
@@ -2614,13 +2750,8 @@
2614
2750
 
2615
2751
  if (isGap(n)) {
2616
2752
  main.append(gapHeader(n));
2617
- const refs = neighbours(n, "spec"),
2618
- plan = planOf(n);
2619
- if (refs.length) {
2620
- const chips = el("div", null, "chips");
2621
- refs.forEach((r) => chips.append(button(r.title, "chip", () => openNode(r))));
2622
- main.append(el("div", "Refers to", "mono-label"), chips);
2623
- }
2753
+ // The pages the gap is about are listed beside the text ("This gap is about"), as on spec pages.
2754
+ const plan = planOf(n);
2624
2755
  if (plan)
2625
2756
  main.append(
2626
2757
  linkBlock("Plan", [
@@ -2686,7 +2817,8 @@
2686
2817
 
2687
2818
  let gapState = "all",
2688
2819
  gapArea = "",
2689
- gapKind = "";
2820
+ gapKind = "",
2821
+ gapPriority = ""; // "" for all, "none" for gaps without one, otherwise the value
2690
2822
  const selectOf = (label, options, value, pick) => {
2691
2823
  const s = el("select");
2692
2824
  s.setAttribute("aria-label", label);
@@ -2708,7 +2840,11 @@
2708
2840
  head.title = "Questions about what is missing, unverified or could be added. Each one is rechecked and then decided by a person.";
2709
2841
  box.append(head);
2710
2842
  const pool = nodes.filter(
2711
- (n) => isGap(n) && inArea(n, gapArea) && (!gapKind || n.kind === gapKind),
2843
+ (n) =>
2844
+ isGap(n) &&
2845
+ inArea(n, gapArea) &&
2846
+ (!gapKind || n.kind === gapKind) &&
2847
+ (!gapPriority || (priorityOf(n) || "none") === gapPriority),
2712
2848
  ),
2713
2849
  again = () => show();
2714
2850
  head.append(
@@ -2743,9 +2879,29 @@
2743
2879
  again();
2744
2880
  }),
2745
2881
  );
2882
+ // Only the priorities the queue has, most urgent first; nothing to pick when no gap has one.
2883
+ const priorities = [...new Set(nodes.filter(isGap).map(priorityOf).filter(Boolean))].sort(
2884
+ (a, b) => priorityRank({ priority: a }) - priorityRank({ priority: b }) || a.localeCompare(b),
2885
+ );
2886
+ if (priorities.length || gapPriority)
2887
+ head.append(
2888
+ selectOf(
2889
+ "Priority",
2890
+ [
2891
+ ["", "All priorities"],
2892
+ ...priorities.map((p) => [p, p[0].toUpperCase() + p.slice(1) + " priority"]),
2893
+ ["none", "No priority"],
2894
+ ],
2895
+ gapPriority,
2896
+ (v) => {
2897
+ gapPriority = v;
2898
+ again();
2899
+ },
2900
+ ),
2901
+ );
2746
2902
  const shown = pool
2747
2903
  .filter((g) => gapState === "all" || stateOf(g) === gapState)
2748
- .sort((a, b) => stateRank(a) - stateRank(b) || byTitle(a, b));
2904
+ .sort(byGapOrder);
2749
2905
  if (shown.length) {
2750
2906
  const card = el("section", null, "card");
2751
2907
  card.id = "gap-list";
@@ -2777,7 +2933,7 @@
2777
2933
  }),
2778
2934
  );
2779
2935
  const shown = gaps
2780
- ? nodes.filter((n) => isGap(n) && inArea(n, mapArea)).sort((a, b) => stateRank(a) - stateRank(b) || byTitle(a, b))
2936
+ ? nodes.filter((n) => isGap(n) && inArea(n, mapArea)).sort(byGapOrder)
2781
2937
  : nodes.filter((n) => layerOf(n) === "spec" && inArea(n, mapArea));
2782
2938
  draw(graphModel(shown), false);
2783
2939
  }
@@ -3411,7 +3567,7 @@
3411
3567
  ? model.context.has(x.id)
3412
3568
  ? 1
3413
3569
  : -1
3414
- : stateRank(x) - stateRank(y) || byTitle(x, y),
3570
+ : byGapOrder(x, y),
3415
3571
  );
3416
3572
  const cols = Math.max(
3417
3573
  1,
@@ -3576,15 +3732,33 @@
3576
3732
  function applyBox() {
3577
3733
  graph.setAttribute("viewBox", `${box.x} ${box.y} ${box.w} ${box.h}`);
3578
3734
  }
3579
- function zoom(f) {
3580
- const w = box.w * f,
3581
- h = box.h * f;
3582
- box.x += (box.w - w) / 2;
3583
- box.y += (box.h - h) / 2;
3735
+ // f below 1 zooms in. (cx, cy) is the point of the map that stays where it is, as a share of the
3736
+ // view: the middle for the buttons, the pointer for the wheel. Zoom stops at 8x in and 4x out.
3737
+ function zoom(f, cx = 0.5, cy = 0.5) {
3738
+ const w = Math.min(Math.max(box.w * f, initialBox.w / 8), initialBox.w * 4),
3739
+ k = w / box.w,
3740
+ h = box.h * k;
3741
+ box.x += (box.w - w) * cx;
3742
+ box.y += (box.h - h) * cy;
3584
3743
  box.w = w;
3585
3744
  box.h = h;
3586
3745
  applyBox();
3587
3746
  }
3747
+ graph.addEventListener(
3748
+ "wheel",
3749
+ (e) => {
3750
+ if (!e.deltaY) return;
3751
+ e.preventDefault(); // the map takes the wheel; the page beside it still scrolls
3752
+ const rect = graph.getBoundingClientRect(),
3753
+ share = (v, size) => (size ? Math.min(Math.max(v / size, 0), 1) : 0.5);
3754
+ zoom(
3755
+ Math.exp(Math.max(-60, Math.min(60, e.deltaY)) * 0.004),
3756
+ share(e.clientX - rect.left, rect.width),
3757
+ share(e.clientY - rect.top, rect.height),
3758
+ );
3759
+ },
3760
+ { passive: false },
3761
+ );
3588
3762
  $("#zoom-in").addEventListener("click", () => zoom(0.8));
3589
3763
  $("#zoom-out").addEventListener("click", () => zoom(1.25));
3590
3764
  $("#reset").addEventListener("click", () => {
@@ -54,8 +54,8 @@ Required on every page: `id`, `title`, `type`, `areas`, `sources`, `updated`. `s
54
54
 
55
55
  - `id`: unique stable ASCII slug (`[a-z0-9-]+`).
56
56
  - `status` on `area` and `note`: `current`, `partial`, `stale`, `superseded`. On `index`, `run` and `plan` additionally `planned`.
57
- - `current`: checked against the current sources. This is not a runtime test or a deployment claim; say in prose which version and environment you checked.
58
- - `partial`: sampled; some of the area or behavior was not read.
57
+ - `current`: the whole feature was read and the page checked against the current sources. This is not a runtime test or a deployment claim; say in prose which version and environment you checked.
58
+ - `partial`: some of the feature or area was not read. The page ends with a line saying what is left, and stays `partial` until the feature is finished.
59
59
  - `stale`: its sources changed or disappeared and it has not been re-read.
60
60
  - `superseded`: replaced by another page, kept as a pointer.
61
61
  - `planned` (index, run, plan): describes intent not yet carried out.
@@ -63,6 +63,7 @@ Required on every page: `id`, `title`, `type`, `areas`, `sources`, `updated`. `s
63
63
  - `areas`: existing **area IDs**. Each `note`, `gap` and `plan` needs at least one. Area pages may list themselves or leave empty; index and run pages may be empty.
64
64
  - `sources`: existing files read as evidence, repository-relative; no directories, credentials, absolute paths or paths escaping the repo. A `current` note needs evidence; gaps, plans and maps may have none.
65
65
  - `updated`: last substantive review date (`YYYY-MM-DD`).
66
+ - Optional `parent`, on a `note` only: the `id` of the feature note this note is a part of. The vault has three levels: area, feature, part. The parent is a note of the same first area that has no `parent` itself, and its body links to each of its parts; `check` rejects anything else. The viewer lists a part under its feature.
66
67
  - Optional `tags`, `aliases`, `task_ids`: string arrays. Optional `summary` and `verification`: strings. An area's `summary` introduces it in the viewer; a note's `summary` is its plain-language statement of what the product does, shown first in the viewer's Read view (write one for every note; `check` does not require it, so older vaults still open).
67
68
 
68
69
  Gap-only properties are errors on any other page type, `gap` is an error on a page that is not a plan, and `priority` and `confidence` are allowed only on gap and plan pages. String properties (and strings inside arrays) may not contain control characters, including line separators. Gap-only properties (`kind`, `recheck`, `rechecked_by`, `rechecked_on`, `decision`, `decided_by`, `decided_on`, `duplicate_of`, optional `priority`, `confidence`) and the plan-only `gap` property are defined in [gaps.md](gaps.md), with the rules for who may set each. Gap state (`needs-recheck`, `needs-decision`, or the decision value) is derived from them and never written into Markdown. A recheck has one meaning for every gap kind: does the `Current behavior` section still describe the code? `confirmed` means it does (confirmed, still holds; for a proposal, the capability is still absent) and `not-reproduced` means it no longer does; neither judges whether a proposal is worth doing, which is a person's decision (see [what a recheck means](gaps.md#what-a-recheck-means)). `recheck: "outdated"` means the cited sources changed after the last recorded recheck; `rechecked_by` and `rechecked_on` stay, the `Recheck` section must have text, and an open gap with it is `needs-recheck`.
@@ -81,8 +82,10 @@ A **feature note** is the one page for one screen, feature, flow or rule, and al
81
82
  | Flow | `## How it works` | What a person does and what happens, in order. Left out when there is no flow. |
82
83
  | Fields | `## Fields` | One row per field of the feature's form: `Field`, `Required`, `Rule`, `Message when refused`. |
83
84
  | Rules | `## Business rules` | One numbered rule per row: `ID`, `Rule`. Who may do it, when an action is available, limits, defaults, what is kept, sent or deleted, and when. |
85
+ | Clients | `## Where the apps differ` | Only when the product has several clients: one row per difference, `What` and a column per client (`Web`, `Mobile`). One sentence instead when they were compared and do not differ. |
86
+ | Parts | `## Parts` | Only on a feature that has parts: a link to each part and one line saying what it covers. |
84
87
 
85
- The headings are written exactly so and come in this order; a section the feature does not have is left out. A field's rule is in `Fields` and is not repeated in `Business rules`. Usually 150-400 words; when its rules need more, split the note by feature or flow, never by kind of fact, so that everything about one feature stays on one page.
88
+ The headings are written exactly so and come in this order; a section the feature does not have is left out. A field's rule is in `Fields` and is not repeated in `Business rules`. Usually 150-400 words and up to about twenty rules. A feature that needs more gets parts: notes with `parent` set to the feature note, each about one flow or one kind of use, never one kind of fact, and each written in this same shape. The feature note then holds what the feature is for, how the parts fit, the rules that hold in every part, and `## Parts`.
86
89
 
87
90
  A rule is numbered `BR-<FEATURE>-<NN>` (`BR-INVITE-03`): `BR`, a short upper-case word for the feature that is the same in all rules of the note and used by no other note, and a number from 01. The number is the rule's name, quoted in tickets, tests and gaps. A rule keeps it when its text changes; a new rule takes the next free number; the number of a removed rule is not used again; rules are never renumbered. One rule per row, one or two sentences, with the value.
88
91
 
@@ -164,7 +167,9 @@ The validator enforces these body rules:
164
167
 
165
168
  ## Helper
166
169
 
167
- Three scripts in `$SKILL_DIR/scripts/`; see [SKILL.md](../SKILL.md) for the variables.
170
+ Four scripts in `$SKILL_DIR/scripts/`; see [SKILL.md](../SKILL.md) for the variables.
171
+
172
+ `coverage.py --repo PATH [--vault PATH] [--path FOLDER]... [--all]` reads the repository's code files and the spec pages (`area` and `note`) and prints what the code has that no page mentions. It writes nothing and always exits 0. Code files are the tracked and the untracked-but-not-ignored files with a source-code extension, outside the vault, without tests, fixtures, stories, mocks, migrations, dependencies and build output. For each folder it prints the number of files and lines, how many of the files a page cites in `sources`, how many **sentences a person can see** the folder has and how many are on no page, and the same for **named numbers**. A sentence is a string or text between tags of 12 to 200 characters that starts with a capital letter and has at least three words, outside log calls; it is on a page when a page contains it, ignoring case, curly quotes and spacing. A named number is an upper-case constant set to a number (`MAX_FILES = 10`); it is on a page when a page contains its name. A file with 40 or more sentences is an article or a template and counts as a file only. A folder in which no page cites any file is one line however deep it goes; folders are ordered by how much they have that no page mentions. With `--path` only those folders are read and every unmentioned sentence and number is listed with its file, then the largest files no page cites. The first 40 folders and 60 items are printed unless `--all` is given. The report finds places to read; it cannot find a rule that has neither a message nor a named number.
168
173
 
169
174
  `knowledge.py {check,snapshot,serve,build} --repo PATH [--vault PATH]`
170
175
 
@@ -204,7 +209,7 @@ Canonical Markdown must not contain raw merge conflicts. Validation rejects comp
204
209
 
205
210
  `serve` shows the vault in a browser: `knowledge.py serve --repo REPO [--vault VAULT] [--port N] [--open]`. Without `--vault`, this and every other command use the single vault under `knowledge/` (`knowledge/00-index.md` or `knowledge/*/00-index.md`) and stop with a message when there is none or several. It listens on `127.0.0.1` only (port 8757, or a free one when that is taken), answers only `/` and only when addressed as this machine, never writes, and builds the page again from disk on every request, so a reload shows the current files. When the vault has errors the page lists them. The page data is the graph above plus `live: true`, `vaultPath` (the vault's path relative to the repository), `history`, `pending` and `files`. `history` is the last 30 commits that touched vault pages (not `.knowledge/`), newest first, each `{"sha", "date", "subject", "pages", "more"}`; a page entry is `{"path", "status"}` with `status` `added`, `changed` or `removed`, plus `was` and `now` when the commit changed the page's `summary` (or, failing that, its `title`); at most 80 pages are listed per commit and `more` counts the rest. `pending` lists vault pages with uncommitted changes in the same `{"path", "status"}` shape. Both are empty outside a Git work tree. `files` is the text of the repository files that pages cite in `sources` or link to, keyed by repository-relative path, each `{"text", "truncated"}`. A file is included only when it is inside the repository and outside the vault, is not a credential path, and is UTF-8 text; one file is cut at 300,000 characters and all files together at 4,000,000, after which the rest stay ordinary links. The viewer opens a link to an included file in place: Markdown rendered, anything else as numbered lines, with the lines of a `#L10` or `#L10-L20` fragment marked.
206
211
 
207
- `build` writes the same viewer as one file, for a server that shows the spec to people who do not have the repository: `knowledge.py build --repo REPO [--vault VAULT] --out FILE [--source-url URL] [--with-sources]`. `--out` must be a file outside the vault. The command stops with the `check` errors when the vault has any, and writes nothing then; freshness warnings do not stop it. The page data is the graph plus `built: true`, `commit` (the full `HEAD`, empty outside Git), `sourceUrl`, `vaultPath`, `history`, `pending` and `files`. `files` is empty unless `--with-sources` is given, because the text of cited files is source code. `--source-url` must be an `http(s)` address; `{commit}` in it is replaced by `HEAD`, and it is an error to name `{commit}` outside a Git work tree. On a built page a cited file whose text is not included is a link to `sourceUrl/<repository path>` (with `#L10-L20` when lines are named) in a new tab, or plain text when there is no `sourceUrl`; it is never a relative link, which would lead into the site that hosts the page. In a shallow clone the commit whose parents were not fetched is left out of `history` (by `serve` too), since Git would show every page as added there, and `build` says that the history is short.
212
+ `build` writes the same viewer as one file, for a server that shows the spec to people who do not have the repository: `knowledge.py build --repo REPO [--vault VAULT] --out FILE [--source-url URL] [--with-sources]`. `--out` must be a file outside the vault. The command stops with the `check` errors when the vault has any, and writes nothing then; freshness warnings do not stop it. The page data is the graph plus `built: true`, `commit` (the full `HEAD`, empty outside Git), `sourceUrl`, `vaultPath`, `history`, `pending` and `files`. `files` is empty unless `--with-sources` is given, because the text of cited files is source code. `--source-url` must be an `http(s)` address; `{commit}` in it is replaced by `HEAD`, and it is an error to name `{commit}` outside a Git work tree. `--allow-missing-sources` is for a build that sees only part of the repository (a Docker build context): a cited path where nothing exists is not an error and does not mark its page as changed, and the command lists those files; `check` and `snapshot` never accept it. On a built page a cited file whose text is not included is a link to `sourceUrl/<repository path>` (with `#L10-L20` when lines are named) in a new tab, or plain text when there is no `sourceUrl`; it is never a relative link, which would lead into the site that hosts the page. In a shallow clone the commit whose parents were not fetched is left out of `history` (by `serve` too), since Git would show every page as added there, and `build` says that the history is short.
208
213
 
209
214
  `assets/viewer.html` has exactly one `__KNOWLEDGE_DATA__` placeholder for script-safe JSON. Treat contents as untrusted text: no raw Markdown HTML execution, unsafe URL schemes, external scripts, fonts, analytics or fetches. Render readable basic Markdown, pipe tables and wikilinks; leave unsupported syntax as text. The viewer has a tree of areas with their notes (a note is listed under its first area; superseded notes are not listed), a search over pages, gaps and the cited files, and five places: the overview, a page, the gap queue, the map and recent changes. A note shows its title, `summary`, the page text and the gaps about it that are not closed, then its source files folded; an area shows its notes with their summaries and folds its own text. The pages linked to or from the page are a short list beside it. Navigation keeps a trail for Back and Forward and writes the place into the address (`#/page/notes/example`, `#/gaps`), so a reload or a copied link returns to it. The map draws one frame per primary area (the area page, or the first entry of `areas`) with its pages inside; an edge between a page and its primary area is not drawn because the frame says it, links inside one area are solid and links across areas dashed; `nav` pages are not drawn. Recent changes reads `history`, `pending` and the "changed source" lines of `warnings`. "Copy for AI" only composes text from the page, a choice of what the agent should do and the reader's own words, and copies it to the clipboard. The reader's name, the recently viewed pages and the last commit seen are kept in the browser's `localStorage`, and the viewer works without it.
210
215
 
@@ -27,7 +27,7 @@ A gap must not have `status`; its progress is carried by `recheck` and `decision
27
27
  | `decided_by` | when `decision` is `accepted`, `rejected` or `deferred` | a person's name; the value `agent` is an error |
28
28
  | `decided_on` | when `decision` is `accepted`, `rejected` or `deferred` | `YYYY-MM-DD` |
29
29
  | `duplicate_of` | when `decision` is `duplicate` | id of another existing gap (not itself) |
30
- | `priority`, `confidence` | optional, gap and plan pages only | short strings, e.g. `"high"` |
30
+ | `priority`, `confidence` | optional, gap and plan pages only | short strings, e.g. `"high"`. Use `high`, `medium` or `low` for `priority` (or `P0` to `P4`): the viewer lists the most urgent gap of each state first and can show one priority only. |
31
31
 
32
32
  `decided_by` and `decided_on` are also allowed on `done` and `duplicate` but not required. With `outdated`, `rechecked_by` and `rechecked_on` stay in place as the record of the last recheck actually done. A fresh recheck replaces all three fields and adds a new dated entry to the `Recheck` section; keep the older entries.
33
33