dflow-sdd-ddd 0.13.0 → 0.15.0

package/lib/render.js

@@ -1,8 +1,8 @@
 // dflow render — specs Markdown -> human-readable static HTML (PROPOSAL-073).
 //
 // Markdown stays the AI-facing source of truth; this command projects it into
-// a mirrored .html tree plus a root index.html file-tree for human reading.
-// Every run is a full rebuild (the index tree and in-tree autolinks depend on
+// a mirrored .html tree plus a root index.html for human reading.
+// Every run is a full rebuild (the index and in-tree autolinks depend on
 // the whole file set, so partial rebuilds would leave stale links).
 //
 // Rendering parity baseline: the retired dev prototype
@@ -12,6 +12,37 @@
 // highlighting, .md link rewriting with GFM-style heading ids (CJK-safe), and
 // in-tree autolinking of inline-code .md mentions.
 //
+// PROPOSAL-077 A1 extends that baseline with long-field readability: cards
+// holding a long field span the full grid row, long fields get prose spacing,
+// and wall-length fields are clamped behind a pure-CSS expand toggle (print
+// always fully expands). Layout-only — cell content is never split or
+// reworded, and the page stays JavaScript-free.
+//
+// PROPOSAL-079: features/completed/ (append-only archive) is not inlined in
+// the root index — it renders as one physical index page per year (grouped
+// by the SPEC-YYYYMMDD directory-name prefix; non-conforming entries in an
+// 'other' bucket), with the root tree carrying year links only. Every
+// generated index page is a reserved output in the projection-collision
+// guard.
+//
+// PROPOSAL-100: in a file named analysis.md, each filled `### LC-nn` /
+// `### FL-nn` subsection also gets its lifecycle or flow drawn as inline SVG
+// above its unchanged cards, or a one-line note saying why not
+// (lib/render-diagrams.js). Every other page, and every analysis.md whose
+// LC/FL tables are still the template's (placeholder rows only), renders
+// exactly as before.
+//
+// PROPOSAL-101: on a recognised specs root (shared/_conventions.md is
+// present) the root index is a grouped directory instead of the file tree —
+// Features, Domain, architecture and migration, shared, everything else —
+// each group a native <details> closed on first open (a lone group opens),
+// with a purpose line, a collapsed reading guide and a few path-scoped role
+// labels; year pages gain one orientation line and list each feature
+// directory as a row (the same rows active/ gets). Any other --src keeps the
+// file tree. On both sides, index and year-page hrefs percent-encode `%`,
+// `#` and `?`. Mirror pages are untouched, and the page stays
+// JavaScript-free.
+//
 // marked ships as ESM-only and `require(esm)` is not on by default until Node
 // 22.12 (engines allows >=22.0.0), so this CommonJS module MUST load it via
 // dynamic import('marked') — never via a require() call.
@@ -19,6 +50,8 @@
 const fs = require('node:fs/promises');
 const path = require('node:path');
 
+const diagrams = require('./render-diagrams.js');
+
 const DEFAULT_SRC = 'dflow/specs';
 const DEFAULT_OUT = 'dflow-specs-html';
 const DEFAULT_TITLE = 'dflow specs';
@@ -53,7 +86,110 @@ const STATUS_PILL = {
   draft: 'neutral'
 };
 
-const GHERKIN_KEYWORDS = /^(\s*)(Scenario(?: Outline)?:|Background:|Examples:|Given|When|Then|And|But)(?=[ \t]|$)/gm;
+// Gherkin keyword highlighting reaches three contexts: ```gherkin/feature
+// fences, untagged fences that LOOK like scenario blocks, and plain prose
+// paragraphs whose lines are all keyword-led (the dominant OBTS behavior.md
+// style — steps as ordinary text with two-space line breaks). The prose and
+// untagged-fence paths require >= 2 keyword-led lines: a lone English prose
+// paragraph starting with "When the …" must never light up.
+const GHERKIN_KW_SRC = '(Scenario(?: Outline)?:|Background:|Examples:|Given|When|Then|And|But)';
+const GHERKIN_KEYWORDS = new RegExp(`^(\\s*)${GHERKIN_KW_SRC}(?=[ \\t]|$)`, 'gm');
+const GHERKIN_PROSE_LINE = new RegExp(`^(\\s*)${GHERKIN_KW_SRC}(?=[ \\t])`);
+// Step keywords carry per-keyword classes (Given=setup, When=action,
+// Then=assertion, And/But=continuation); block headers share kw-s.
+const GHERKIN_KW_CLASS = { Given: 'kw-g', When: 'kw-w', Then: 'kw-t', And: 'kw-a', But: 'kw-a' };
+
+function gherkinKwSpan(kw) {
+  const cls = kw.endsWith(':') ? 'kw-s' : GHERKIN_KW_CLASS[kw];
+  return `<span class="kw ${cls}">${kw}</span>`;
+}
+
+function highlightGherkin(escapedText) {
+  return escapedText.replace(GHERKIN_KEYWORDS, (m, lead, kw) => `${lead}${gherkinKwSpan(kw)}`);
+}
+
+// >= 2 keyword-led lines -> treat an untagged fence as a scenario block.
+function looksLikeGherkin(text) {
+  const hits = String(text).match(GHERKIN_KEYWORDS);
+  return hits !== null && hits.length >= 2;
+}
+
+// Raw inline HTML can carry a newline or a literal <br> inside an attribute
+// value, and the string-level line split below would then inject a keyword
+// span into the middle of a tag (review visual-r1 F1). Any html token in
+// the paragraph's inline tree disqualifies it from prose highlighting —
+// codespans, links, and em/strong stay eligible (their rendered tags can
+// never begin a split line without also failing the keyword-led test).
+function hasRawHtmlToken(tokens) {
+  for (const token of tokens || []) {
+    if (token.type === 'html' || (token.tokens && hasRawHtmlToken(token.tokens))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Split rendered inline HTML into [line, delim, line, …] at hard-break
+// <br> tags and soft-break newlines that sit OUTSIDE any tag. Markdown
+// link/image titles may span lines, so a newline can legally live inside
+// a rendered title="…" attribute — splitting there would let the keyword
+// wrapper inject a span mid-tag (review visual-r2 F1). Marked-rendered
+// attributes are entity-escaped, so tag extents are exactly the unescaped
+// '<'…'>' pairs; raw html tokens (where that guarantee fails) are already
+// excluded by hasRawHtmlToken before this runs.
+function splitProseLines(innerHtml) {
+  const html = String(innerHtml);
+  const parts = [];
+  let cur = '';
+  let inTag = false;
+  for (let i = 0; i < html.length; i++) {
+    const ch = html[i];
+    if (inTag) {
+      cur += ch;
+      if (ch === '>') {
+        inTag = false;
+      }
+      continue;
+    }
+    if (ch === '<') {
+      const br = /^<br\s*\/?>/i.exec(html.slice(i));
+      if (br) {
+        parts.push(cur, br[0]);
+        cur = '';
+        i += br[0].length - 1;
+      } else {
+        inTag = true;
+        cur += ch;
+      }
+      continue;
+    }
+    if (ch === '\n') {
+      parts.push(cur, '\n');
+      cur = '';
+      continue;
+    }
+    cur += ch;
+  }
+  parts.push(cur);
+  return parts;
+}
+
+// Prose steps: a paragraph qualifies when it holds >= 2 non-empty lines
+// (tag-aware split, see above) and EVERY one starts with a step/header
+// keyword; then each line's keyword is wrapped — always at tag depth zero,
+// because every segment starts outside a tag by construction. The
+// every-line rule keeps hard-wrapped ordinary prose (where one wrapped
+// line may start with "When …") from ever qualifying.
+function highlightProseSteps(innerHtml) {
+  const parts = splitProseLines(innerHtml);
+  const lines = parts.filter((p, i) => i % 2 === 0 && p.trim() !== '');
+  if (lines.length < 2 || !lines.every((line) => GHERKIN_PROSE_LINE.test(line))) {
+    return innerHtml;
+  }
+  return parts
+    .map((p, i) => (i % 2 === 0 ? p.replace(GHERKIN_PROSE_LINE, (m, lead, kw) => `${lead}${gherkinKwSpan(kw)}`) : p))
+    .join('');
+}
 
 // All multi-column tables render as cards (user decision 2026-07-09 after two
 // prototype demo rounds; no per-table heuristic). Degenerate single-column
@@ -64,6 +200,21 @@ const CAT_HEADERS = new Set([
   'status', 'subdomain type', 'layer', 'severity', 'owner / team', 'producer'
 ]);
 
+// PROPOSAL-077 A1 long-field thresholds, in plain-text code points of the
+// cell (tags stripped; CJK counts 1 per character). LONG promotes the card
+// to a full grid row plus prose line spacing — at ~24 CJK chars per line in
+// a 330px card, 200 chars is 8+ rendered lines, beyond any convention-
+// compliant summary. CLAMP additionally caps the field at CLAMP_LINES with
+// a CSS-only expand toggle; 400 chars still exceeds CLAMP_LINES at full
+// content width (~59 CJK chars per line), so the toggle only appears where
+// clipping is near-certain. Latin text runs narrower per char, so a wide
+// latin field can show a toggle whose expansion reveals little — accepted
+// noise; thresholds are not script-aware by design. The row title and chip
+// columns are exempt: titles are names by design, chips are ≤40 chars.
+const LONG_FIELD_CHARS = 200;
+const CLAMP_FIELD_CHARS = 400;
+const CLAMP_LINES = 6;
+
 const CSS = `
 :root {
   --bg:#f6f8f9; --surface:#ffffff; --frame:#eef2f4; --deep:#e7edef;
@@ -72,6 +223,7 @@ const CSS = `
   --ok-fg:#1e6b34; --ok-bg:#e2f2e6; --ok-line:#bfe0c7;
   --warn-fg:#8a5600; --warn-bg:#f7ecd7; --warn-line:#e8d5ac;
   --del-fg:#9c3838; --del-bg:#f9e9e9; --del-line:#e8c4c4;
+  --head-strong:#0a4f47; --kw-then:#6d4fc2;
 }
 @media (prefers-color-scheme: dark) {
   :root {
@@ -81,6 +233,7 @@ const CSS = `
     --ok-fg:#7bd397; --ok-bg:#142d1b; --ok-line:#235c33;
     --warn-fg:#e2b269; --warn-bg:#2f2510; --warn-line:#59461d;
     --del-fg:#e08f8f; --del-bg:#331a1a; --del-line:#5c2727;
+    --head-strong:#7fd8ca; --kw-then:#b6a0f0;
   }
 }
 * { box-sizing: border-box; }
@@ -102,13 +255,13 @@ pre {
   padding: 0.85rem 1.1rem; overflow-x: auto; font-size: 12.8px; line-height: 1.85;
 }
 pre code { background: none; border: none; padding: 0; font-size: inherit; }
-h1 { font-size: 25px; line-height: 1.35; margin: 0.2rem 0 1rem; }
+h1 { font-size: 25px; line-height: 1.35; margin: 0.2rem 0 1rem; color: var(--head-strong); }
 h2 {
   font-size: 19px; margin: 2.2rem 0 0.6rem; padding-top: 1.2rem;
-  border-top: 1px solid var(--line);
+  border-top: 1px solid var(--line); color: var(--head-strong);
 }
-h3 { font-size: 16.5px; margin: 1.6rem 0 0.4rem; }
-h4 { font-size: 15px; margin: 1.2rem 0 0.3rem; }
+h3 { font-size: 16.5px; margin: 1.6rem 0 0.4rem; color: var(--accent); }
+h4 { font-size: 15px; margin: 1.2rem 0 0.3rem; color: var(--accent); }
 blockquote {
   margin: 0.8rem 0; padding: 0.55rem 1rem;
   background: var(--accent-soft); border-left: 3px solid var(--accent);
@@ -149,7 +302,12 @@ tr:last-child td { border-bottom: none; }
   content: ""; position: absolute; left: 4px; top: 1px; width: 3px; height: 7px;
   border: solid var(--bg); border-width: 0 2px 2px 0; transform: rotate(45deg);
 }
-.kw { color: var(--accent); font-weight: 700; }
+.kw { font-weight: 700; }
+.kw-s { color: var(--accent); }
+.kw-g { color: var(--ok-fg); }
+.kw-w { color: var(--warn-fg); }
+.kw-t { color: var(--kw-then); }
+.kw-a { color: var(--soft); }
 .cards {
   display: grid; grid-template-columns: repeat(auto-fill, minmax(330px, 1fr));
   gap: 0.9rem; align-items: start; margin: 0.8rem 0 1.4rem;
@@ -176,6 +334,30 @@ tr:last-child td { border-bottom: none; }
   margin-bottom: 0.05rem;
 }
 .fld-v { font-size: 14px; line-height: 1.7; overflow-wrap: anywhere; }
+.card.wide { grid-column: 1 / -1; }
+.fld-v.prose { line-height: 1.85; position: relative; }
+.fxt { position: absolute; opacity: 0; width: 1px; height: 1px; margin: 0; pointer-events: none; }
+.fxc { max-height: calc(${CLAMP_LINES} * 1.85em); overflow: hidden; position: relative; }
+.fxc::after {
+  content: ""; position: absolute; left: 0; right: 0; bottom: 0; height: 2.4em;
+  background: linear-gradient(to bottom, transparent, var(--surface));
+}
+.fxt:checked ~ .fxc { max-height: none; }
+.fxt:checked ~ .fxc::after { display: none; }
+.fxl {
+  display: inline-block; margin: 0.35rem 0 0.1rem; padding: 2px 10px;
+  font-size: 11.5px; font-weight: 600; color: var(--accent);
+  background: var(--accent-soft); border: 1px solid var(--accent-line);
+  border-radius: 999px; cursor: pointer; user-select: none;
+}
+.fxl .fxs { display: none; }
+.fxt:checked ~ .fxl .fxm { display: none; }
+.fxt:checked ~ .fxl .fxs { display: inline; }
+.fxt:focus-visible ~ .fxl { outline: 2px solid var(--accent); outline-offset: 2px; }
+@media print {
+  .fxc { max-height: none; }
+  .fxc::after, .fxl, .fxt { display: none; }
+}
 .crumb { font-size: 12px; color: var(--faint); font-family: Consolas, monospace; margin: 0 0 1rem; }
 .crumb a { color: var(--faint); }
 .meta-card {
@@ -190,11 +372,39 @@ tr:last-child td { border-bottom: none; }
   margin-top: 3rem; padding-top: 0.9rem; border-top: 1px solid var(--line);
   color: var(--faint); font-size: 12px; font-family: Consolas, monospace;
 }
-ul.tree, ul.tree ul { list-style: none; padding-left: 1.1rem; line-height: 2; }
+ul.tree, ul.tree ul { list-style: none; line-height: 2; font-size: 13.5px; }
 ul.tree { padding-left: 0; }
-ul.tree .dir { color: var(--faint); font-weight: 600; font-size: 13.5px; }
-ul.tree a { text-decoration: none; font-family: Consolas, monospace; font-size: 13.5px; }
+ul.tree ul { padding-left: 1.35rem; margin: 0; }
+ul.tree .dir { color: var(--faint); font-weight: 600; }
+ul.tree .years { font-size: 13px; color: var(--faint); }
+ul.tree .years a { font-weight: 600; }
+.yearnav { font-size: 13.5px; color: var(--faint); margin: -0.3rem 0 1.1rem; font-family: Consolas, monospace; }
+.yearnav a { text-decoration: none; font-weight: 600; }
+.yearnav strong { color: var(--ink); }
+ul.tree a { text-decoration: none; font-family: Consolas, monospace; }
 ul.tree a:hover { text-decoration: underline; }
+ul.tree li { position: relative; }
+ul.tree ul li::before {
+  content: ""; position: absolute; left: -0.85rem; top: 0; height: 100%;
+  border-left: 1px solid var(--line);
+}
+ul.tree ul li:last-child::before { height: 1em; }
+ul.tree ul li::after {
+  content: ""; position: absolute; left: -0.85rem; top: 1em; width: 0.6rem;
+  border-top: 1px solid var(--line);
+}
+ul.tree .dir::before, ul.tree li > a::before {
+  content: ""; display: inline-block; width: 15px; height: 15px;
+  margin-right: 0.45em; vertical-align: -0.2em; background: currentColor;
+}
+ul.tree .dir::before {
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M1.5 4A1.5 1.5 0 0 1 3 2.5h3.1l1.6 2H13A1.5 1.5 0 0 1 14.5 6v6.5A1.5 1.5 0 0 1 13 14H3a1.5 1.5 0 0 1-1.5-1.5z'/%3E%3C/svg%3E") center/contain no-repeat;
+          mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M1.5 4A1.5 1.5 0 0 1 3 2.5h3.1l1.6 2H13A1.5 1.5 0 0 1 14.5 6v6.5A1.5 1.5 0 0 1 13 14H3a1.5 1.5 0 0 1-1.5-1.5z'/%3E%3C/svg%3E") center/contain no-repeat;
+}
+ul.tree li > a::before {
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill-rule='evenodd' d='M4 1.5h5.4L13.5 5.6V13A1.5 1.5 0 0 1 12 14.5H4A1.5 1.5 0 0 1 2.5 13V3A1.5 1.5 0 0 1 4 1.5zm5.4 0v4.1h4.1z'/%3E%3C/svg%3E") center/contain no-repeat;
+          mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill-rule='evenodd' d='M4 1.5h5.4L13.5 5.6V13A1.5 1.5 0 0 1 12 14.5H4A1.5 1.5 0 0 1 2.5 13V3A1.5 1.5 0 0 1 4 1.5zm5.4 0v4.1h4.1z'/%3E%3C/svg%3E") center/contain no-repeat;
+}
 `;
 
 // ------------------------------------------------------------------ file IO
@@ -342,12 +552,21 @@ function plainTableHtml(headerCells, rows) {
 // pill styling); remaining columns -> stacked label+value fields, with in-cell
 // <br> line breaks preserved verbatim. Empty cells are omitted. Degenerate
 // single-column tables keep the plain-table rendering.
-function cardsHtml(headerCells, rows) {
+//
+// Long fields (PROPOSAL-077 A1): a field at LONG_FIELD_CHARS+ makes its card
+// span the full grid row and gets prose spacing; at CLAMP_FIELD_CHARS+ the
+// field is additionally clamped behind a checkbox-driven CSS toggle (the
+// checkbox stays focusable for keyboard use; print CSS removes the clamp).
+// The field's HTML is emitted unmodified inside the clamp wrapper — never
+// split, reflowed, or reworded. nextToggleId mints document-unique ids for
+// the checkbox/label pairs.
+function cardsHtml(headerCells, rows, nextToggleId) {
   const cards = rows.map((cells) => {
     const plains = cells.map(stripTags);
     const title = plains[0] ? cells[0] : '（未命名）';
     const chips = [];
     const fields = [];
+    let hasLongField = false;
     for (let i = 1; i < headerCells.length; i++) {
       const cell = cells[i] ?? '';
       const text = plains[i] ?? '';
@@ -363,22 +582,41 @@ function cardsHtml(headerCells, rows) {
           chips.push(`<span class="chip cat">${headerCells[i]}: ${cell}</span>`);
         }
       } else {
+        const chars = [...text].length;
+        let valueHtml = cell;
+        let valueClass = 'fld-v';
+        if (chars >= LONG_FIELD_CHARS) {
+          hasLongField = true;
+          valueClass = 'fld-v prose';
+          if (chars >= CLAMP_FIELD_CHARS) {
+            const id = nextToggleId();
+            valueHtml =
+              `<input type="checkbox" class="fxt" id="${id}">` +
+              `<div class="fxc">${cell}</div>` +
+              `<label class="fxl" for="${id}">` +
+              '<span class="fxm">展開全文 ▾</span><span class="fxs">收合 ▴</span></label>';
+          }
+        }
         fields.push(
           `<div class="fld"><span class="fld-k">${headerCells[i]}</span>` +
-          `<div class="fld-v">${cell}</div></div>`
+          `<div class="${valueClass}">${valueHtml}</div></div>`
         );
       }
     }
     const chipsHtml = chips.length ? `<div class="card-chips">${chips.join('')}</div>` : '';
-    return `<article class="card"><div class="card-title">${title}</div>` +
+    return `<article class="card${hasLongField ? ' wide' : ''}"><div class="card-title">${title}</div>` +
       `${chipsHtml}<div class="card-fields">${fields.join('')}</div></article>`;
   });
   return `<div class="cards">${cards.join('')}</div>\n`;
 }
 
 // Per-file renderer overrides. `seen` carries the per-document heading slug
-// dedup state, so a fresh renderer is built for every file.
+// dedup state, so a fresh renderer is built for every file. toggleSeq mints
+// the per-document ids for long-field clamp toggles; the `fldx-` prefix
+// keeps them out of the heading-slug namespace (slugs never contain a
+// hyphenated `fldx-N` unless a heading literally says so).
 function buildRenderer(seen) {
+  let toggleSeq = 0;
   return {
     heading(token) {
       const inner = this.parser.parseInline(token.tokens);
@@ -401,17 +639,27 @@ function buildRenderer(seen) {
       return `<a href="${escapeHtml(href)}"${title}>${inner}</a>`;
     },
 
-    // Fenced code; gherkin/feature blocks get keyword highlighting.
+    // Fenced code; gherkin/feature blocks get keyword highlighting, and an
+    // untagged fence that reads as a scenario block (>= 2 keyword-led lines)
+    // is highlighted the same way — other-language fences never are.
     code(token) {
       const lang = String(token.lang || '').trim().split(/\s+/)[0];
       let escaped = escapeHtml(token.text);
-      if (lang === 'gherkin' || lang === 'feature') {
-        escaped = escaped.replace(GHERKIN_KEYWORDS, '$1<span class="kw">$2</span>');
+      if (lang === 'gherkin' || lang === 'feature' || (!lang && looksLikeGherkin(token.text))) {
+        escaped = highlightGherkin(escaped);
       }
       const cls = lang ? ` class="language-${escapeHtml(lang)}"` : '';
       return `<pre><code${cls}>${escaped}\n</code></pre>\n`;
     },
 
+    // Prose scenario steps (keyword-led <br>-separated lines) get the same
+    // keyword colors; ordinary paragraphs pass through marked's default
+    // shape, and paragraphs holding raw inline HTML are never rewritten.
+    paragraph(token) {
+      const inner = this.parser.parseInline(token.tokens);
+      return `<p>${hasRawHtmlToken(token.tokens) ? inner : highlightProseSteps(inner)}</p>\n`;
+    },
+
     // Task-list checkboxes -> styled spans (same look as the prototype; the
     // trailing space restores the gap marked v18 no longer inserts itself).
     checkbox(token) {
@@ -427,7 +675,7 @@ function buildRenderer(seen) {
       if (headerCells.length < 2 || rows.length === 0) {
         return plainTableHtml(headerCells, rows);
       }
-      return cardsHtml(headerCells, rows);
+      return cardsHtml(headerCells, rows, () => `fldx-${toggleSeq++}`);
     }
   };
 }
@@ -540,7 +788,7 @@ function metaCardHtml(meta, fallbackTitle) {
 
 // ----------------------------------------------------------------- rendering
 
-function pageHtml({ title, crumb, metaCard, body, footer }) {
+function pageHtml({ title, crumb, metaCard, body, footer, extraCss = '' }) {
   return `<!DOCTYPE html>
 ${GENERATED_MARK}
 <html lang="zh-Hant">
@@ -548,7 +796,7 @@ ${GENERATED_MARK}
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${title}</title>
-<style>${CSS}</style>
+<style>${CSS}${extraCss}</style>
 </head>
 <body>
 <main>
@@ -562,18 +810,33 @@ ${body}
 `;
 }
 
-async function renderFile({ MarkedCtor, srcRoot, outRoot, relPosix, stamp, tree, basenames }) {
+async function renderFile({ MarkedCtor, srcRoot, outRoot, relPosix, stamp, tree, basenames, diagramStats }) {
   const relHtml = `${relPosix.slice(0, -'.md'.length)}.html`;
   const mdPath = path.join(srcRoot, ...relPosix.split('/'));
   const outPath = path.join(outRoot, ...relHtml.split('/'));
+  const parts = relPosix.split('/');
 
   const { meta, body } = splitFrontmatter(await readText(mdPath));
   const seen = new Map();
-  const marked = new MarkedCtor({ gfm: true, renderer: buildRenderer(seen) });
+  const options = { gfm: true, renderer: buildRenderer(seen) };
+  // PROPOSAL-100: only analysis.md is searched for LC-/FL- subsections; the
+  // hook inserts each picture or note as its own block before the
+  // subsection's first recognised table, so the cards are built exactly as
+  // on every other page.
+  const diagramPage = parts[parts.length - 1] === 'analysis.md' ? diagrams.newPageState() : null;
+  if (diagramPage) {
+    options.hooks = { processAllTokens: (tokens) => diagrams.insertDiagrams(tokens, diagramPage) };
+  }
+  const marked = new MarkedCtor(options);
   let bodyHtml = marked.parse(preprocess(body));
   bodyHtml = autolinkCodeMentions(bodyHtml, relPosix, tree, basenames);
 
-  const parts = relPosix.split('/');
+  const hasDiagramBlock = diagramPage !== null && diagramPage.drawn + diagramPage.notDrawn > 0;
+  if (hasDiagramBlock) {
+    diagramStats.drawn += diagramPage.drawn;
+    diagramStats.notDrawn += diagramPage.notDrawn;
+  }
+
   const stem = parts[parts.length - 1].slice(0, -'.md'.length);
   const indexHref = '../'.repeat(parts.length - 1) + 'index.html';
   const crumb = `<a href="${indexHref}">specs</a> / ` + parts.map(escapeHtml).join(' / ');
@@ -584,55 +847,567 @@ async function renderFile({ MarkedCtor, srcRoot, outRoot, relPosix, stamp, tree,
     crumb,
     metaCard: metaCardHtml(meta, stem),
     body: bodyHtml,
-    footer
+    footer,
+    extraCss: hasDiagramBlock ? diagrams.DIAGRAM_CSS : ''
   }));
   return relHtml;
 }
 
+// PROPOSAL-079: features/completed/ is a monotonically growing archive, so
+// the root index must not inline it. Entries under the prefix group by the
+// year in their SPEC directory name; anything non-conforming lands in the
+// 'other' bucket (still reachable, never dropped). Grouping is mechanical —
+// directory names only, no frontmatter parsing. Returns null when the tree
+// holds nothing under the prefix (then no pagination happens at all).
+const COMPLETED_PREFIX = 'features/completed/';
+const SPEC_YEAR_RE = /^SPEC-(\d{4})\d{4,}-/;
+
+function completedIndexRel(key) {
+  return `${COMPLETED_PREFIX}index-${key}.html`;
+}
+
+function completedKeyLabel(key) {
+  return key === 'other' ? '未分年' : key;
+}
+
+// Sort keys: years newest-first, the 'other' bucket always last.
+function completedKeyOrder(keys) {
+  return [...keys].sort((a, b) => {
+    if (a === 'other') return 1;
+    if (b === 'other') return -1;
+    return b.localeCompare(a);
+  });
+}
+
+function groupCompletedByYear(relFiles) {
+  const groups = new Map(); // key -> { files: [rel…], units: Set<top-level name> }
+  for (const rel of relFiles) {
+    if (!rel.startsWith(COMPLETED_PREFIX)) {
+      continue;
+    }
+    const rest = rel.slice(COMPLETED_PREFIX.length);
+    const top = rest.split('/')[0];
+    const match = rest.includes('/') ? SPEC_YEAR_RE.exec(top) : null;
+    const key = match ? match[1] : 'other';
+    if (!groups.has(key)) {
+      groups.set(key, { files: [], units: new Set() });
+    }
+    groups.get(key).files.push(rel);
+    groups.get(key).units.add(top);
+  }
+  return groups.size ? groups : null;
+}
+
+// PROPOSAL-101: every href on the root index and the year pages goes
+// through here. Inside a relative path only `%` (escape), `#` (fragment)
+// and `?` (query) change what a browser resolves — `a#b.html` points at
+// `a` — so those three are percent-encoded; everything else (CJK, spaces,
+// `&`) stays literal, and a path holding none of the three comes out
+// byte-identical. Callers still escapeHtml() the result for the attribute.
+const HREF_ESCAPES = { '%': '%25', '#': '%23', '?': '%3F' };
+
+function indexHref(relPath) {
+  return relPath.replace(/[%#?]/g, (ch) => HREF_ESCAPES[ch]);
+}
+
+// Root-index year links for the completed/ stub line. Hrefs are root-
+// relative; the surrounding <span> keeps them out of the `li > a` file-icon
+// selector.
+function completedYearLinksHtml(groups) {
+  const links = completedKeyOrder(groups.keys()).map((key) => {
+    const g = groups.get(key);
+    return `<a href="${escapeHtml(indexHref(completedIndexRel(key)))}">${escapeHtml(completedKeyLabel(key))} (${g.units.size})</a>`;
+  });
+  return `<span class="years">${links.join(' · ')}</span>`;
+}
+
 // Nested <ul> file tree with links to the mirrored .html files.
-function buildTreeHtml(relFiles) {
-  const root = { dirs: new Map(), files: [] };
+// opts.stubs: [{ dirParts, html }] — pseudo-directory lines injected among
+// a node's subdirectories (used for the completed/ year-links line; the
+// node is created even when no other file implies it). opts.topDirsDesc:
+// sort depth-0 directories newest-first (completed year pages).
+function buildTreeHtml(relFiles, opts = {}) {
+  const stubs = opts.stubs || [];
+  const root = { dirs: new Map(), files: [], stubs: new Map() };
+  const ensure = (node, part) => {
+    if (!node.dirs.has(part)) {
+      node.dirs.set(part, { dirs: new Map(), files: [], stubs: new Map() });
+    }
+    return node.dirs.get(part);
+  };
   for (const rel of [...relFiles].sort()) {
     const parts = rel.split('/');
     let node = root;
     for (const part of parts.slice(0, -1)) {
-      if (!node.dirs.has(part)) {
-        node.dirs.set(part, { dirs: new Map(), files: [] });
-      }
-      node = node.dirs.get(part);
+      node = ensure(node, part);
     }
     node.files.push(rel);
   }
+  for (const stub of stubs) {
+    let node = root;
+    for (const part of stub.dirParts.slice(0, -1)) {
+      node = ensure(node, part);
+    }
+    node.stubs.set(stub.dirParts[stub.dirParts.length - 1], stub.html);
+  }
 
-  function emit(node) {
+  function emit(node, depth) {
     let out = '<ul class="tree">';
-    for (const name of [...node.dirs.keys()].sort()) {
-      out += `<li><span class="dir">${escapeHtml(name)}/</span>${emit(node.dirs.get(name))}</li>`;
+    const names = [...new Set([...node.dirs.keys(), ...node.stubs.keys()])].sort();
+    if (depth === 0 && opts.topDirsDesc) {
+      names.reverse();
+    }
+    for (const name of names) {
+      if (node.stubs.has(name)) {
+        out += `<li><span class="dir">${escapeHtml(name)}/</span> ${node.stubs.get(name)}</li>`;
+      } else {
+        out += `<li><span class="dir">${escapeHtml(name)}/</span>${emit(node.dirs.get(name), depth + 1)}</li>`;
+      }
     }
     for (const rel of node.files) {
-      const href = `${rel.slice(0, -'.md'.length)}.html`;
+      const href = indexHref(`${rel.slice(0, -'.md'.length)}.html`);
       const name = rel.split('/').pop();
       out += `<li><a href="${escapeHtml(href)}">${escapeHtml(name)}</a></li>`;
     }
     return `${out}</ul>`;
   }
 
-  return emit(root);
+  return emit(root, 0);
 }
 
-async function renderIndex({ outRoot, relFiles, title, stamp }) {
-  const body = `<h1>${escapeHtml(title)}</h1>${buildTreeHtml(relFiles)}`;
+// ---------------------------------------------------------- grouped index
+// PROPOSAL-101: when --src is recognisably a Dflow specs root — it holds
+// shared/_conventions.md, which dflow init always creates; presence only,
+// the content is never read — the root index becomes a grouped directory:
+// a header, jump links, and one native <details> per group, all closed on
+// first open (an only group opens). Grouping, order, role labels and guide
+// text come from paths alone, never from document content, and all live in
+// the registry below. Any other --src keeps the pre-P101 file tree and year
+// pages, changed only by indexHref(): a top-level directory that merely
+// happens to be called `features` or `shared` is no evidence that Dflow's
+// conventions hold there.
+const SPECS_ROOT_MARKER = 'shared/_conventions.md';
+const OVERVIEW_REL = 'shared/_overview.md';
+
+// The groups, in page order. `dirs: null` collects root files and every
+// top-level directory no other group claims. A guide line with a `when`
+// test shows only when that test finds what the line talks about.
+const hasFile = (target) => (rels) => rels.includes(target);
+const hasMatch = (re) => (rels) => rels.some((rel) => re.test(rel));
+
+const INDEX_GROUPS = [
+  {
+    id: 'features',
+    name: 'Features',
+    dirs: ['features'],
+    purpose: '每一次變更的規格與紀錄：進行中、backlog 與已完成',
+    guide: [
+      { html: '一個目錄是一個 feature：<code>_index.md</code> 是它的總覽（目標、範圍、各階段規格與目前的業務規則快照），<code>phase-spec-*.md</code> 是一個階段的完整規格，<code>lightweight-*.md</code> 與 <code>BUG-*.md</code> 是小改動的規格。', when: hasMatch(/^features\/(active|completed)\/[^/]+\//) },
+      { html: '<code>active/</code> 慣例上放還在進行的 feature。', when: hasMatch(/^features\/active\//) },
+      { html: '<code>backlog/</code> 放先記下來的想法或筆記；放在這裡不代表已經排定或核准，要打開看內容才知道還適不適用。', when: hasMatch(/^features\/backlog\//) },
+      { html: '<code>completed/</code> 是已完成 feature 的歷史紀錄，依年份分頁；系統現在的行為以 Domain 那一組的文件為準。', when: hasMatch(/^features\/completed\//) }
+    ]
+  },
+  {
+    id: 'domain',
+    name: 'Domain',
+    dirs: ['domain'],
+    purpose: '系統知識：各 context 的模型、規則、行為與分析',
+    guide: [
+      { html: '「跨 context」那一列是 <code>domain/</code> 直接底下的文件：<code>context-map.md</code> 看各 context 的分工與關係，<code>glossary.md</code> 看用語的定義，<code>analysis.md</code> 記跨 context 的流程、功能與角色的對照，以及不只屬於一個 context 的機制。', when: hasMatch(/^domain\/[^/]+$/) },
+      { html: '其後每一列是 <code>domain/</code> 底下的一個目錄，慣例上一個目錄是一個 bounded context：<code>context-definition.md</code>（或 <code>context.md</code>）講它負責什麼、不負責什麼，<code>models.md</code> 列它的模型，<code>rules.md</code> 是業務規則的索引（BR-ID），<code>behavior.md</code> 用情境寫出目前的行為，<code>events.md</code> 列領域事件，<code>analysis.md</code> 記這個 context 自己的狀態怎麼流轉、數字怎麼算、機制怎麼運作。', when: hasMatch(/^domain\/[^/]+\//) }
+    ]
+  },
+  {
+    id: 'arch',
+    name: '架構與遷移',
+    dirs: ['architecture', 'migration'],
+    purpose: '技術債、架構決策與遷移的紀錄',
+    guide: [
+      { html: '<code>tech-debt.md</code> 記開發途中發現、留待之後處理的技術債。', when: hasMatch(/^(architecture|migration)\/tech-debt\.md$/) },
+      { html: '<code>migration/</code> 底下記的是往目標架構遷移的事。', when: hasMatch(/^migration\//) },
+      { html: '<code>architecture/decisions/</code> 放架構決策紀錄（ADR），一份文件記一個決定。', when: hasMatch(/^architecture\/decisions\//) }
+    ]
+  },
+  {
+    id: 'shared',
+    name: '共用文件',
+    dirs: ['shared'],
+    purpose: '專案層級的總覽、撰寫慣例與 AI 協作指引',
+    guide: [
+      { html: '<code>_overview.md</code> 是這個系統的總覽，第一次讀從它開始。', when: hasFile('shared/_overview.md') },
+      { html: '<code>_conventions.md</code> 記這個專案寫規格的慣例。', when: hasFile('shared/_conventions.md') },
+      { html: '<code>Git-principles-*.md</code> 記這個專案的 Git 分支與提交慣例。', when: hasMatch(/^shared\/Git-principles-[^/]*\.md$/) },
+      { html: '<code>AI-AGENT-GUIDE.md</code> 是給 AI 助手的工作指引。', when: hasFile('shared/AI-AGENT-GUIDE.md') },
+      { html: '<code>dflow-workflows/</code> 是 Dflow 放進來的流程文件與空白範本，由 Dflow 更新，不是這個專案自己寫的文件。', when: hasMatch(/^shared\/dflow-workflows\//) }
+    ]
+  },
+  {
+    id: 'other',
+    name: '其他',
+    dirs: null,
+    purpose: '根目錄的文件與其他頂層目錄，照目錄層級列出',
+    guide: null
+  }
+];
+
+// Recognised filenames list first, in this order; every other file follows
+// by name. Absent files leave no gap and no hint.
+const DOMAIN_ROOT_ORDER = ['context-map.md', 'glossary.md', 'analysis.md'];
+const CONTEXT_ORDER = [
+  'context-definition.md', 'context.md', 'analysis.md', 'models.md', 'rules.md', 'behavior.md', 'events.md'
+];
+
+// Role labels by exact path shape (`*` = any one segment). A path matching
+// no shape shows its filename alone — the index never guesses, so a
+// template analysis.md under shared/ is never labelled as this project's.
+const ROLE_LABELS = [
+  { shape: ['domain', 'analysis.md'], label: '跨 context 分析' },
+  { shape: ['domain', '*', 'analysis.md'], label: 'context 分析' },
+  { shape: ['features', 'active', '*', '_index.md'], label: 'feature 總覽' }
+];
+// Same idea for a directory's disclosure summary.
+const DIR_LABELS = [
+  { shape: ['shared', 'dflow-workflows'], label: 'Dflow 放進來的流程文件與範本' }
+];
+
+const INDEX_CSS = `
+.ix-head { color: var(--soft); font-size: 14px; margin: -0.4rem 0 0.7rem; }
+.ix-jump { color: var(--faint); font-size: 14px; margin: 0 0 1.2rem; }
+.ix-jump a { font-weight: 600; text-decoration: none; }
+.ix-group {
+  background: var(--surface); border: 1px solid var(--line);
+  border-radius: 10px; margin: 0 0 0.7rem;
+}
+.ix-group > summary { cursor: pointer; padding: 0.6rem 1rem; line-height: 1.55; }
+.ix-group[open] > summary { border-bottom: 1px solid var(--line); }
+.ix-name { font-size: 17px; font-weight: 700; color: var(--head-strong); }
+.ix-dirs { font-family: Consolas, monospace; font-size: 12.5px; color: var(--faint); margin-left: 0.25em; }
+.ix-count { font-size: 12.5px; color: var(--soft); margin-left: 0.25em; white-space: nowrap; }
+.ix-purpose { display: block; font-size: 13.5px; color: var(--soft); }
+.ix-body { padding: 0.55rem 1rem 0.85rem; }
+.ix-body, .ix-year { font-size: 13.5px; }
+.ix-body a, .ix-head a, .ix-year a { font-family: Consolas, monospace; text-decoration: none; overflow-wrap: anywhere; }
+.ix-body a:hover, .ix-head a:hover, .ix-year a:hover { text-decoration: underline; }
+.ix-guide {
+  background: var(--accent-soft); border: 1px solid var(--accent-line);
+  border-radius: 8px; padding: 0.3rem 0.8rem; margin: 0 0 0.7rem;
+}
+.ix-guide > summary { cursor: pointer; color: var(--accent); font-weight: 600; }
+.ix-guide ul { margin: 0.35rem 0 0.3rem; padding-left: 1.2rem; }
+.ix-body h3 {
+  font-family: Consolas, monospace; font-size: 13.5px; color: var(--soft);
+  margin: 0.9rem 0 0.2rem;
+}
+.ix-list { list-style: none; padding-left: 0; margin: 0.15rem 0 0.3rem; line-height: 1.9; }
+.ix-rows { border-top: 1px solid var(--line); margin: 0.3rem 0; }
+.ix-row {
+  display: grid; grid-template-columns: minmax(7rem, 15rem) 1fr; gap: 0.1rem 1rem;
+  padding: 0.4rem 0; border-bottom: 1px solid var(--line);
+}
+.ix-rowname { font-weight: 600; overflow-wrap: anywhere; }
+.ix-rowname.path { font-family: Consolas, monospace; }
+.ix-docs { display: flex; flex-wrap: wrap; align-items: baseline; gap: 0.1rem 1.1rem; }
+.ix-docs > details { flex-basis: 100%; }
+.ix-docs.stack { display: block; }
+.ix-docs.stack > .ix-list { margin: 0; line-height: 1.75; }
+.ix-role {
+  font-size: 11px; color: var(--soft); border: 1px solid var(--line);
+  border-radius: 999px; padding: 0 0.45em; margin-left: 0.1em; white-space: nowrap;
+}
+.ix-sub { margin: 0.1rem 0; }
+.ix-sub > summary { cursor: pointer; }
+.ix-sub > :not(summary) { margin-left: 1.2rem; }
+.ix-dname { font-family: Consolas, monospace; font-weight: 600; color: var(--soft); }
+.ix-years a { font-weight: 600; }
+.ix-note { font-size: 13.5px; color: var(--soft); margin: -0.4rem 0 1rem; }
+.ix-year .ix-row { grid-template-columns: minmax(7rem, 20rem) 1fr; }
+@media (max-width: 40rem) {
+  .ix-row, .ix-year .ix-row { grid-template-columns: 1fr; }
+}
+`;
+
+function matchesShape(parts, shape) {
+  return shape.length === parts.length && shape.every((seg, i) => seg === '*' || seg === parts[i]);
+}
+
+function pathLabel(table, parts) {
+  const hit = table.find(({ shape }) => matchesShape(parts, shape));
+  return hit ? hit.label : null;
+}
+
+// A directory node: `path` is its slash-terminated tree path ('' = root).
+function buildDirTree(relFiles) {
+  const root = { path: '', dirs: new Map(), files: [] };
+  for (const rel of relFiles) {
+    const parts = rel.split('/');
+    let node = root;
+    for (const part of parts.slice(0, -1)) {
+      if (!node.dirs.has(part)) {
+        node.dirs.set(part, { path: `${node.path}${part}/`, dirs: new Map(), files: [] });
+      }
+      node = node.dirs.get(part);
+    }
+    node.files.push(rel);
+  }
+  return root;
+}
+
+function countDocs(node) {
+  let n = node.files.length;
+  for (const child of node.dirs.values()) {
+    n += countDocs(child);
+  }
+  return n;
+}
+
+function sortedDirNames(node, skip = []) {
+  return [...node.dirs.keys()].filter((name) => !skip.includes(name)).sort();
+}
+
+function orderedFiles(files, fixedOrder = []) {
+  const base = (rel) => rel.split('/').pop();
+  const fixed = fixedOrder.flatMap((name) => files.filter((rel) => base(rel) === name));
+  const rest = files.filter((rel) => !fixedOrder.includes(base(rel))).sort();
+  return [...fixed, ...rest];
+}
+
+// A feature directory's files: _index.md first, then every file whose name
+// carries a date — Dflow names phase specs and lightweight specs
+// `{kind}-YYYY-MM-DD-{slug}.md` on the day they are created, so date order
+// is roughly phase order — by that date, then the rest (BUG-{NUMBER}-*,
+// anything the project named itself) by name. Names only: file contents
+// and filesystem times never decide the order.
+const FILE_DATE_RE = /(?:^|[-_])(\d{4}-\d{2}-\d{2})(?=[-_.])/;
+
+function featureFileOrder(files) {
+  const base = (rel) => rel.split('/').pop();
+  const dateOf = (rel) => {
+    const match = FILE_DATE_RE.exec(base(rel));
+    return match ? match[1] : null;
+  };
+  const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+  const rest = files.filter((rel) => base(rel) !== '_index.md');
+  return [
+    ...files.filter((rel) => base(rel) === '_index.md'),
+    ...rest.filter((rel) => dateOf(rel)).sort((a, b) => byName(dateOf(a), dateOf(b)) || byName(a, b)),
+    ...rest.filter((rel) => !dateOf(rel)).sort()
+  ];
+}
+
+// `base` is the directory the page itself sits in: hrefs are relative to
+// it, while labels always read the full path.
+function docLinkHtml(rel, base = '') {
+  const href = indexHref(`${rel.slice(base.length, -'.md'.length)}.html`);
+  const role = pathLabel(ROLE_LABELS, rel.split('/'));
+  const roleHtml = role ? ` <span class="ix-role">${escapeHtml(role)}</span>` : '';
+  return `<a href="${escapeHtml(href)}">${escapeHtml(rel.split('/').pop())}</a>${roleHtml}`;
+}
+
+function docListHtml(files, base = '') {
+  return files.length ? `<ul class="ix-list">${files.map((rel) => `<li>${docLinkHtml(rel, base)}</li>`).join('')}</ul>` : '';
+}
+
+function docInlineHtml(files) {
+  return files.map((rel) => `<span>${docLinkHtml(rel)}</span>`).join('');
+}
+
+// The generic listing every part without a layout of its own uses: files
+// first by name, then each subdirectory as a named disclosure with its
+// document count, recursively — every document keeps its own link.
+function dirListingHtml(node, base = '') {
+  return docListHtml(orderedFiles(node.files), base) +
+    sortedDirNames(node).map((name) => subdirHtml(name, node.dirs.get(name), base)).join('');
+}
+
+function subdirHtml(name, node, base = '') {
+  const label = pathLabel(DIR_LABELS, node.path.slice(0, -1).split('/'));
+  return `<details class="ix-sub"><summary><span class="ix-dname">${escapeHtml(name)}/</span> ` +
+    `<span class="ix-count">${countDocs(node)} 份</span>${label ? ` <span class="ix-role">${escapeHtml(label)}</span>` : ''}` +
+    `</summary>${dirListingHtml(node, base)}</details>`;
+}
+
+// A row's documents sit side by side (`stacked` false: short conventional
+// names, as in Domain) or one per line (feature rows: long names whose
+// order matters).
+function rowHtml(name, isPath, docsHtml, stacked = false) {
+  return `<div class="ix-row"><div class="ix-rowname${isPath ? ' path' : ''}">${name}</div>` +
+    `<div class="ix-docs${stacked ? ' stack' : ''}">${docsHtml}</div></div>`;
+}
+
+// (D) One feature directory as a row: its files one per line in
+// featureFileOrder, deeper directories as disclosures after them.
+function featureRowHtml(name, node, base = '') {
+  return rowHtml(`${escapeHtml(name)}/`, true, docListHtml(featureFileOrder(node.files), base) +
+    sortedDirNames(node).map((sub) => subdirHtml(sub, node.dirs.get(sub), base)).join(''), true);
+}
+
+// (B) One row for domain/'s own files, then one per subdirectory: its
+// direct files inline, deeper directories as disclosures.
+function domainBodyHtml(node) {
+  const rows = [];
+  if (node.files.length) {
+    rows.push(rowHtml('跨 context', false, docInlineHtml(orderedFiles(node.files, DOMAIN_ROOT_ORDER))));
+  }
+  for (const name of sortedDirNames(node)) {
+    const dir = node.dirs.get(name);
+    const nested = sortedDirNames(dir).map((sub) => subdirHtml(sub, dir.dirs.get(sub))).join('');
+    rows.push(rowHtml(`${escapeHtml(name)}/`, true, docInlineHtml(orderedFiles(dir.files, CONTEXT_ORDER)) + nested));
+  }
+  return rows.length ? `<div class="ix-rows">${rows.join('')}</div>` : '';
+}
+
+// (D) active/: one feature row per directory. backlog/ lists generically;
+// completed/ keeps the PROPOSAL-079 year links (its year pages use the same
+// feature rows, completedRowsHtml).
+function featuresBodyHtml(node, completedGroups) {
+  let out = docListHtml(orderedFiles(node.files));
+  const active = node.dirs.get('active');
+  if (active) {
+    const rows = sortedDirNames(active).map((name) => featureRowHtml(name, active.dirs.get(name)));
+    out += '<h3>active/</h3>' + docListHtml(orderedFiles(active.files)) +
+      (rows.length ? `<div class="ix-rows">${rows.join('')}</div>` : '');
+  }
+  const backlog = node.dirs.get('backlog');
+  if (backlog) {
+    out += `<h3>backlog/</h3>${dirListingHtml(backlog)}`;
+  }
+  if (completedGroups) {
+    out += `<h3>completed/</h3><p class="ix-years">${completedYearLinksHtml(completedGroups)}</p>`;
+  }
+  return out + sortedDirNames(node, ['active', 'backlog', 'completed'])
+    .map((name) => subdirHtml(name, node.dirs.get(name))).join('');
+}
+
+// Everything without a layout of its own: root files first, then one small
+// heading per top-level directory.
+function topLevelBodyHtml(rootFiles, dirEntries) {
+  return docListHtml(orderedFiles(rootFiles)) +
+    dirEntries.map(([name, node]) => `<h3>${escapeHtml(name)}/</h3>${dirListingHtml(node)}`).join('');
+}
+
+// The grouped index's <h1>..groups body. Pure, and every listing sorts at
+// output, so the same relFiles in any order give the same HTML.
+function groupedIndexHtml({ relFiles, title, completedGroups }) {
+  const tree = buildDirTree(relFiles);
+  const claimed = INDEX_GROUPS.flatMap((group) => group.dirs || []);
+  const groups = [];
+  for (const group of INDEX_GROUPS) {
+    const rootFiles = group.dirs === null ? tree.files : [];
+    const dirEntries = (group.dirs || sortedDirNames(tree, claimed))
+      .filter((name) => tree.dirs.has(name))
+      .map((name) => [name, tree.dirs.get(name)]);
+    const count = rootFiles.length + dirEntries.reduce((n, [, node]) => n + countDocs(node), 0);
+    if (count === 0) {
+      continue;
+    }
+    let body;
+    if (group.id === 'features') {
+      body = featuresBodyHtml(dirEntries[0][1], completedGroups);
+    } else if (group.id === 'domain') {
+      body = domainBodyHtml(dirEntries[0][1]);
+    } else {
+      body = topLevelBodyHtml(rootFiles, dirEntries);
+    }
+    const guideLines = (group.guide || []).filter((line) => !line.when || line.when(relFiles));
+    const guide = guideLines.length
+      ? `<details class="ix-guide"><summary>怎麼讀這些文件</summary><ul>${guideLines.map((line) => `<li>${line.html}</li>`).join('')}</ul></details>`
+      : '';
+    const dirs = [...(rootFiles.length ? ['根目錄'] : []), ...dirEntries.map(([name]) => `${escapeHtml(name)}/`)];
+    groups.push({
+      group,
+      html: (open) => `<details class="ix-group" id="g-${group.id}"${open ? ' open' : ''}><summary>` +
+        `<span class="ix-name">${escapeHtml(group.name)}</span> <span class="ix-dirs">${dirs.join(' · ')}</span> ` +
+        `<span class="ix-count">${count} 份</span> <span class="ix-purpose">${escapeHtml(group.purpose)}</span>` +
+        `</summary><div class="ix-body">${guide}${body}</div></details>`
+    });
+  }
+  const start = relFiles.includes(OVERVIEW_REL)
+    ? ` · 從這裡開始：<a href="${escapeHtml(indexHref(`${OVERVIEW_REL.slice(0, -'.md'.length)}.html`))}">${escapeHtml(OVERVIEW_REL)}</a>`
+    : '';
+  const jump = groups.length > 1
+    ? `<p class="ix-jump">跳到：${groups.map(({ group }) => `<a href="#g-${group.id}">${escapeHtml(group.name)}</a>`).join(' · ')}</p>`
+    : '';
+  return `<h1>${escapeHtml(title)}</h1><p class="ix-head">共 ${relFiles.length} 份文件${start}</p>${jump}` +
+    groups.map(({ html }) => html(groups.length === 1)).join('');
+}
+
+// (D) A year page on a recognised specs root: one feature row per
+// directory, newest-first as the PROPOSAL-079 tree lists them, then the
+// loose files. Hrefs stay relative to the year page.
+function completedRowsHtml(files) {
+  const node = buildDirTree(files).dirs.get('features').dirs.get('completed');
+  const rows = sortedDirNames(node).reverse()
+    .map((name) => featureRowHtml(name, node.dirs.get(name), COMPLETED_PREFIX));
+  return '<div class="ix-year">' + (rows.length ? `<div class="ix-rows">${rows.join('')}</div>` : '') +
+    docListHtml(orderedFiles(node.files), COMPLETED_PREFIX) + '</div>';
+}
+
+// Year-page orientation line (E): only on a recognised specs root.
+const COMPLETED_NOTE =
+  '這一頁是已完成 feature 的歷史紀錄，依目錄名 SPEC 編號裡的年份分頁，認不出年份的放在「未分年」；' +
+  '系統現在的行為以 <code>domain/</code> 底下的文件為準。';
+
+async function renderIndex({ outRoot, relFiles, title, stamp, completedGroups, specsRoot }) {
+  let body;
+  if (specsRoot) {
+    body = groupedIndexHtml({ relFiles, title, completedGroups });
+  } else {
+    let tree;
+    if (completedGroups) {
+      const mainFiles = relFiles.filter((rel) => !rel.startsWith(COMPLETED_PREFIX));
+      tree = buildTreeHtml(mainFiles, {
+        stubs: [{ dirParts: ['features', 'completed'], html: completedYearLinksHtml(completedGroups) }]
+      });
+    } else {
+      tree = buildTreeHtml(relFiles);
+    }
+    body = `<h1>${escapeHtml(title)}</h1>${tree}`;
+  }
   const footer = `共 ${relFiles.length} 份文件 · ${stamp} · 來源檔較新時請重新執行 dflow render`;
   await writeText(path.join(outRoot, 'index.html'), pageHtml({
     title: escapeHtml(title),
     crumb: 'specs /',
     metaCard: '',
     body,
-    footer
+    footer,
+    extraCss: specsRoot ? INDEX_CSS : ''
   }));
   return 'index.html';
 }
 
+// PROPOSAL-079: one physical page per completed year (user requirement:
+// real files, not visual collapsing — ten years of archive must not pile
+// into one page). SPEC directories list newest-first inside the page.
+async function renderCompletedIndex({ outRoot, key, groups, title, stamp, specsRoot }) {
+  const relHtml = completedIndexRel(key);
+  const group = groups.get(key);
+  const stripped = group.files.map((rel) => rel.slice(COMPLETED_PREFIX.length));
+  const label = completedKeyLabel(key);
+  const nav = completedKeyOrder(groups.keys())
+    .map((k) => (k === key
+      ? `<strong>${escapeHtml(completedKeyLabel(k))}</strong>`
+      : `<a href="${escapeHtml(indexHref(`index-${k}.html`))}">${escapeHtml(completedKeyLabel(k))}</a>`))
+    .join(' · ');
+  const body =
+    `<h1>completed / ${escapeHtml(label)}</h1>` +
+    `<p class="yearnav">${nav}</p>` +
+    (specsRoot
+      ? `<p class="ix-note">${COMPLETED_NOTE}</p>${completedRowsHtml(group.files)}`
+      : buildTreeHtml(stripped, { topDirsDesc: true }));
+  const crumb = '<a href="../../index.html">specs</a> / features / completed / ' + escapeHtml(label);
+  const footer = `completed ${escapeHtml(label)} · 共 ${group.units.size} 項 · ${stamp} · 來源檔較新時請重新執行 dflow render`;
+  await writeText(path.join(outRoot, ...relHtml.split('/')), pageHtml({
+    title: escapeHtml(`${title} · completed ${label}`),
+    crumb,
+    metaCard: '',
+    body,
+    footer,
+    extraCss: specsRoot ? INDEX_CSS : ''
+  }));
+  return relHtml;
+}
+
 // ----------------------------------------------------- output-dir ownership
 
 // Validate a parsed-or-raw manifest. Returns { ok: true, files } or
@@ -748,7 +1523,13 @@ function pathContains(parent, child) {
 // a raw EISDIR/ENOTDIR mid-write — after the ownership stamp — so this is
 // checked before any output mutation. Returns null, or a human-readable
 // description of the first collision found.
-function findProjectionCollision(relFiles) {
+//
+// reservedPages lists every generated (non-mirror) page THIS run will write
+// — the root file tree plus any completed year indexes (PROPOSAL-079). Each
+// is checked against mirror outputs AND against source directories needing
+// the same path. Defaults to the root index alone so unit callers predate
+// pagination unchanged.
+function findProjectionCollision(relFiles, reservedPages = [{ out: 'index.html', what: 'the generated file tree' }]) {
   const toOut = (rel) => `${rel.slice(0, -'.md'.length)}.html`;
   for (const rel of relFiles) {
     // The ledger stores out-relative posix paths and parseManifest rejects
@@ -761,7 +1542,7 @@ function findProjectionCollision(relFiles) {
       return `source path ${rel} cannot be represented in the render manifest`;
     }
   }
-  const byOut = new Map([['index.html', 'the generated file tree']]);
+  const byOut = new Map(reservedPages.map(({ out, what }) => [out.toLowerCase(), what]));
   for (const rel of relFiles) {
     const out = toOut(rel);
     const prior = byOut.get(out.toLowerCase());
@@ -780,9 +1561,11 @@ function findProjectionCollision(relFiles) {
       }
     }
   }
-  const indexDir = neededDirs.get('index.html');
-  if (indexDir) {
-    return `${indexDir.source} needs ${indexDir.prefix}/ as a directory, but render generates index.html there`;
+  for (const { out } of reservedPages) {
+    const hit = neededDirs.get(out.toLowerCase());
+    if (hit) {
+      return `${hit.source} needs ${hit.prefix}/ as a directory, but render generates ${out} there`;
+    }
   }
   for (const reserved of [MANIFEST_NAME, MANIFEST_TMP_NAME]) {
     const hit = neededDirs.get(reserved);
@@ -1048,7 +1831,17 @@ async function runRender({ cwd, args = [], stdout, stderr }) {
   // all: a colliding projection must refuse cleanly here, not die on a raw
   // fs error mid-write after the ownership stamp (cold-eye gate G3 F2).
   const relMdFiles = await collectMdFiles(srcRoot);
-  const collision = findProjectionCollision(relMdFiles);
+  const completedGroups = groupCompletedByYear(relMdFiles);
+  const reservedPages = [{ out: 'index.html', what: 'the generated file tree' }];
+  if (completedGroups) {
+    for (const key of completedKeyOrder(completedGroups.keys())) {
+      reservedPages.push({
+        out: completedIndexRel(key),
+        what: `the generated completed index for ${completedKeyLabel(key)}`
+      });
+    }
+  }
+  const collision = findProjectionCollision(relMdFiles, reservedPages);
   if (collision) {
     stderr.write(
       `refusing to run: ${collision}; nothing was written.\n` +
@@ -1183,7 +1976,10 @@ async function runRender({ cwd, args = [], stdout, stderr }) {
 
   // Ownership (manifest) + entry types (scan) still do not prove a given
   // file is render's own work; the generated marker inside the file does.
-  const plannedRels = [...relMdFiles.map((rel) => `${rel.slice(0, -'.md'.length)}.html`), 'index.html'];
+  const plannedRels = [
+    ...relMdFiles.map((rel) => `${rel.slice(0, -'.md'.length)}.html`),
+    ...reservedPages.map(({ out }) => out)
+  ];
   const unproven = await findUnprovenTarget({ outRoot, plannedRels, listedRels: previousFiles });
   if (unproven) {
     stderr.write(
@@ -1209,10 +2005,19 @@ async function runRender({ cwd, args = [], stdout, stderr }) {
 
   const stamp = nowStamp();
   const written = [];
+  const diagramStats = { drawn: 0, notDrawn: 0 };
   for (const relPosix of relMdFiles) {
-    written.push(await renderFile({ MarkedCtor: Marked, srcRoot, outRoot, relPosix, stamp, tree, basenames }));
+    written.push(await renderFile({ MarkedCtor: Marked, srcRoot, outRoot, relPosix, stamp, tree, basenames, diagramStats }));
   }
-  written.push(await renderIndex({ outRoot, relFiles: relMdFiles, title: options.title, stamp }));
+  // PROPOSAL-101: the grouped index, its guide text and the year-page note
+  // only on a recognised specs root.
+  const specsRoot = tree.has(SPECS_ROOT_MARKER);
+  if (completedGroups) {
+    for (const key of completedKeyOrder(completedGroups.keys())) {
+      written.push(await renderCompletedIndex({ outRoot, key, groups: completedGroups, title: options.title, stamp, specsRoot }));
+    }
+  }
+  written.push(await renderIndex({ outRoot, relFiles: relMdFiles, title: options.title, stamp, completedGroups, specsRoot }));
 
   const stale = staleEntries(previousFiles, written);
   const unlinked = [];
@@ -1235,6 +2040,10 @@ async function runRender({ cwd, args = [], stdout, stderr }) {
   await writeManifest(outRoot, written);
 
   stdout.write(`rendered ${relMdFiles.length} md files -> ${outRoot}\n`);
+  // PROPOSAL-100: only when some LC-/FL- subsection got a picture or a note.
+  if (diagramStats.drawn + diagramStats.notDrawn > 0) {
+    stdout.write(`diagrams: ${diagramStats.drawn} drawn, ${diagramStats.notDrawn} not drawn\n`);
+  }
   stdout.write(`open: ${path.join(outRoot, 'index.html')}\n`);
   return 0;
 }
@@ -1259,5 +2068,12 @@ module.exports = {
   findProjectionCollision,
   GENERATED_MARK,
   splitFrontmatter,
-  headingSlug
+  headingSlug,
+  // PROPOSAL-077 A1: exported so tests lock the documented thresholds.
+  LONG_FIELD_CHARS,
+  CLAMP_FIELD_CHARS,
+  // PROPOSAL-079: exported for grouping-edge unit tests.
+  groupCompletedByYear,
+  // PROPOSAL-101: exported so tests can feed shuffled and non-Windows paths.
+  groupedIndexHtml
 };