docs(keycloak-session-store): remake all 28 diagrams through the techviz pipeline

The originating repository's SVGs were drawn by hand and every one of them
put a title, a subtitle and an explanation band inside the canvas. This
repository forbids both, so they could not be carried over — the whole set
was rebuilt through the skill's pipeline instead.

Each diagram went through prepare, references, prompt, a VizSpec 1.1 citing
document line ranges, lint, and render. All 28 pass lint and produce the
same eight formats the existing keycloak project has. Sentences moved out of
the canvas into <desc> and the paragraph beside each figure; the drawings
carry names only.

Two lint rules did real work rather than formatting work:

  edge-through-node                  caught arrows crossing an unrelated
                                     node and implying an adjacency that
                                     does not exist — four diagrams had to
                                     be restructured, not just relaid out
  evidence-outside-prepared-context  caught a diagram citing another
                                     section; its anchor moved from B-0 to
                                     B-1 so all three sections it draws on
                                     are inside the prepared context

lab-topology also had to change profile: its context offers a different
candidate set, and query-fanout with shard roles is what the section
actually shows — one entry point spreading to two Keycloak nodes.

The document now carries all 28 inline, one per claim that needed one, and
the section recording what was still missing is updated: the diagram gap is
closed, Studio records remain.

verify-pipeline.py passes. audit-records.py reports no issues.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.agents/skills/rewriting-technical-prose-naturally/references/article-shape.md

@@ -7,18 +7,22 @@
 
 ## 잰 값
 
-`scripts/density.mjs`로 잰 것이다.
+`scripts/density.mjs`로 잰 것이다. **글 한 편과 기록 본문은 다른 잣대로 본다.** 기록은 문제·결론·
+검증 환경·재현 조건을 Studio 칸이 따로 들고 있고, 본문의 `##`는 「본문」 칸 아래라 층이 한 단
+낮다. 그래서 본문은 절대값이 아니라 밀도로 잰다 — 절 하나가 몇 낱말인가, 1,000 낱말에 수치가
+몇 개인가.
 
-| | 여섯 편 | 이 저장소의 잘 쓴 기록 (AP4) |
+| | 여섯 편 (글 한 편) | 기록 본문 기준 |
 |---|---|---|
-| 낱말 | 1,480 ~ 3,164 (중앙값 2,508) | 1,726 |
-| 문장 평균 낱말 | 17.8 | 17.3 |
-| 코드블록 | 1 ~ 13 | 8 |
-| **본문 속 수치** | **10 ~ 32개** | **1개** |
-| **`##` 절** | **4 ~ 9개** | **18개** |
-| 표 줄 | 0 ~ 15 | 37 |
+| 낱말 | 1,277 ~ 2,871 | — |
+| 문장 평균 낱말 | 14.2 ~ 18.3 | 14.2 ~ 18.3 |
+| 코드블록 | 1 ~ 13 | 1 ~ 13 |
+| 표 줄 | 0 ~ 15 | 0 ~ 15 |
+| 절당 낱말 | 160 ~ 718 | 160 ~ 718 |
+| 1,000 낱말당 수치 | 측정 글 10.2 ~ 13.8 · 구조 글 0.9 ~ 1.7 | 측정 9 ~ 45 · 구조 0.8 ~ 8 |
 
-문장 길이도 코드블록 수도 이미 맞다. 갈리는 것은 셋이다.
+고치기 전 AP4 본문은 절 하나가 68 낱말, 수치는 본문 전체에 1개, 표 37줄이었다. 손대지 않은
+`clean-architecture-backend-template` 기록들은 지금도 **절 하나가 31 낱말**이다. 갈리는 것은 셋이다.
 
 ## 1. 수치 — 크기를 말하지 않으면 독자는 판단할 수 없다
 

.agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs

@@ -134,6 +134,24 @@ function positiveChecks(text, lines, docMode, rulesMode) {
     if (/까요\??$/.test(st) || /\?$/.test(st)) kinds.add('물음');
     if (/(봅시다|보자|맙시다|주세요)[.!]?$/.test(st)) kinds.add('청유');
   }
+  // 3-1. 문장을 「~것이 ~이다」로 닫는 버릇
+  //
+  // 사건을 서술하는 대신 그것이 무엇인지 이름 붙이고 끝낸다. 「확인한 자리다」·「~하는 실례다」·
+  // 「~라는 점이다」. 참고 여섯 편은 이 어미를 통틀어 세 번 쓴다(17386 1 · 22396 2). 한 문서에
+  // 이것이 몰려 있으면 사건을 적지 않고 분류만 한 것이다.
+  const namingEnd = [...text.matchAll(/[가-힣)\]`]\s*(자리|실례|경우|출발점|사실|이유|점|것|뿐|셈)(이다|입니다)[.!]?(?=\s|$)/g)];
+  const alwaysBad = namingEnd.filter((m) => /(자리|실례|출발점)/.test(m[1]));
+  for (const m of alwaysBad) {
+    out.push({ id: 'naming-instead-of-telling', sev: ERR, index: m.index,
+      excerpt: text.slice(Math.max(0, m.index - 30), m.index + m[0].length),
+      msg: '무슨 일이 있었는지 적는 대신 그것이 무엇인지 이름 붙이고 닫았습니다. 그 자리에서 실제로 일어나는 일을 동사로 적으세요.' });
+  }
+  if (!rulesMode && namingEnd.length >= 4) {
+    out.push({ id: 'naming-instead-of-telling', sev: ERR,
+      msg: `문장을 「~것이 ~이다」로 닫은 자리가 ${namingEnd.length}곳입니다(참고 여섯 편은 글 하나에 0~2회). `
+         + `분류하지 말고 그 자리에서 무엇이 일어나는지 적으세요.` });
+  }
+
   if (!rulesMode && sentences.length >= 8 && kinds.size <= 1) {
     out.push({ id: 'monotone-endings', sev: ERR,
       msg: `문장 ${sentences.length}개가 모두 같은 종결어미입니다. 문장이 하는 일이 다르면 어미도 달라집니다 — `

.agents/skills/rewriting-technical-prose-naturally/scripts/density.mjs

@@ -16,6 +16,17 @@ const BASE = {
   sections: [4, 9], tableLines: [0, 15],
 };
 
+// Tech Log 기록의 본문은 글 한 편이 아니라 그 가운데 토막이다. 문제·결론·검증 환경·재현 조건은
+// Studio 칸이 따로 들고 있고, 본문의 `##` 는 「본문」 칸 아래라 층이 한 단 낮다. 그래서 절 수와
+// 낱말 수를 절대값으로 재면 잘 쓴 본문이 「절이 모자람」으로 잡힌다.
+// 대신 밀도로 본다 — 절 하나가 몇 낱말인가, 1,000 낱말에 수치가 몇 개인가.
+//   여섯 편: 절당 160 ~ 718 낱말 · 측정 글은 1,000 낱말에 10.2 ~ 13.8 개
+const BODY = {
+  sentWords: [14.2, 18.3], code: [1, 13], tableLines: [0, 15],
+  wordsPerSection: [160, 718],
+};
+const BODY_NUM_RATE = { 측정: [9, 45], 구조: [0.8, 8] };
+
 // 수치 개수는 장르가 가른다. 잰 것을 쓰는 글과 구조를 쓰는 글의 기준이 다르다.
 //   측정 글 13569(13) · 23625(18) · 20161(24) · 22396(36)
 //   구조 글 17386(2) · 7835(5)
@@ -24,10 +35,11 @@ const NUMBERS = { 측정: [13, 36], 구조: [2, 12] };
 const NUM = /\d[\d,.]*\s*(?:ms|초|분|시간|일|년|개월|주|배|%|건|개|줄|번|회|명|자|KB|MB|GB|TB|Gbps|TPS|QPS|만|천|억)/g;
 
 function measure(text) {
-  // frontmatter 와 주석은 글이 아니다
-  let t = text.replace(/^---\n.*?\n---\n/s, "").replace(/<!--.*?-->/gs, "");
-  const marked = t.match(/<!-- body:start -->([\s\S]*?)<!-- body:end -->/);
-  if (marked) t = marked[1];
+  // 본문 마커부터 찾는다. 주석을 먼저 지우면 마커도 같이 지워진다 — 그러면 Studio 칸까지
+  // 세게 되고, 기록 하나가 절 아홉 개인 것처럼 보인다.
+  const marked = text.match(/<!-- body:start -->([\s\S]*?)<!-- body:end -->/);
+  let t = marked ? marked[1] : text.replace(/^---\n.*?\n---\n/s, "");
+  t = t.replace(/<!--.*?-->/gs, "");
 
   const code = (t.match(/^```/gm) || []).length / 2;
   const tableLines = (t.match(/^\s*\|/gm) || []).length;
@@ -38,8 +50,11 @@ function measure(text) {
   const numbers = (t.match(NUM) || []).length;
   const proseParas = prose.split(/\n\s*\n/).filter((p) => p.trim().length > 40).length;
 
-  return { words, sentWords: +(words / Math.max(sentences.length, 1)).toFixed(1),
-           code, numbers, sections, tableLines, proseParas };
+  return { isBody: Boolean(marked), words,
+           sentWords: +(words / Math.max(sentences.length, 1)).toFixed(1),
+           code, numbers, sections, tableLines, proseParas,
+           wordsPerSection: Math.round(words / Math.max(sections, 1)),
+           numberRate: +((numbers / Math.max(words, 1)) * 1000).toFixed(1) };
 }
 
 const args = process.argv.slice(2);
@@ -59,13 +74,18 @@ if (!files.length) {
 }
 
 const LABEL = { words: "낱말", sentWords: "문장 평균 낱말", code: "코드블록",
-                numbers: "수치", sections: "## 절", tableLines: "표 줄" };
+                numbers: "수치", sections: "## 절", tableLines: "표 줄",
+                wordsPerSection: "절당 낱말", numberRate: "1,000 낱말당 수치" };
 
 let bad = 0;
 for (const file of files) {
   const m = measure(readFileSync(file, "utf8"));
-  console.log(`\n${basename(file)}   (${genre} 글 기준)`);
-  for (const [k, [lo, hi]] of Object.entries({ ...BASE, numbers: NUMBERS[genre] })) {
+  const where = m.isBody ? "기록 본문" : "글 한 편";
+  console.log(`\n${basename(file)}   (${where} · ${genre} 글 기준)`);
+  const bands = m.isBody
+    ? { ...BODY, numberRate: BODY_NUM_RATE[genre] }
+    : { ...BASE, numbers: NUMBERS[genre] };
+  for (const [k, [lo, hi]] of Object.entries(bands)) {
     const v = m[k];
     const ok = v >= lo && v <= hi;
     const note = ok ? "" : v < lo ? "  ← 모자람" : "  ← 넘침";
@@ -74,9 +94,12 @@ for (const file of files) {
   }
   if (m.tableLines > m.proseParas)
     console.log(`  ! 표 ${m.tableLines}줄이 산문 ${m.proseParas}문단보다 많다 — 표가 설명을 대신하고 있다`);
-  if (m.numbers < NUMBERS[genre][0])
+  const rateLo = m.isBody ? BODY_NUM_RATE[genre][0] : null;
+  if (rateLo !== null && m.numberRate < rateLo)
+    console.log(`  ! 1,000 낱말에 수치가 ${m.numberRate}개다 — 자료에 있는 크기를 「여러」·「대부분」으로 뭉갠 자리를 찾는다`);
+  if (!m.isBody && m.numbers < NUMBERS[genre][0])
     console.log(`  ! 수치가 ${m.numbers}개다 — 자료에 있는 크기를 「여러」·「대부분」으로 뭉갠 자리를 찾는다`);
-  if (m.sections > 9)
-    console.log(`  ! 절이 ${m.sections}개다 — 문단 두 개짜리 절을 앞뒤와 합친다`);
+  if (m.wordsPerSection < 160)
+    console.log(`  ! 절 하나가 ${m.wordsPerSection} 낱말이다 — 문단 두세 개짜리 절을 앞뒤와 합친다`);
 }
 process.exit(bad ? 1 : 0);

.agents/skills/rewriting-technical-prose-naturally/scripts/style_profile.mjs

@@ -53,7 +53,13 @@ export function profile(raw) {
   for (const s of sents) {
     if (/(습니다|았습니다|었습니다)[.!]?$/.test(s)) kinds.add('습니다');
     if (/입니다[.!]?$/.test(s)) kinds.add('입니다');
-    if (/(했다|이다|였다|된다|한다)[.!]?$/.test(s)) kinds.add('한다');
+    // 한다체 안에도 어미는 여럿이다. 한 덩어리로 세면 잘 쓴 한다체 글이 1점을 받고,
+    // 점수를 올릴 길이 물음·청유밖에 남지 않아 없던 화자가 생긴다. 실제로 그렇게 됐다.
+    if (/(한다|된다|만든다|넘긴다|받는다)[.!]?$/.test(s)) kinds.add('한다');
+    if (/(했다|였다|됐다|되었다|았다|었다)[.!]?$/.test(s)) kinds.add('했다');
+    if (/(아니다|없다|같다|다르다|이다)[.!]?$/.test(s)) kinds.add('이다');
+    if (/(못한다|않는다|않았다|못했다)[.!]?$/.test(s)) kinds.add('부정');
+    if (/(뿐이다|때문이다|까지다|것이다)[.!]?$/.test(s)) kinds.add('설명');
     if (/(겠습니다|보겠습니다)[.!]?$/.test(s)) kinds.add('겠습니다');
     if (/\?$/.test(s)) kinds.add('물음');
     if (/(봅시다|보자|맙시다|주세요)[.!]?$/.test(s)) kinds.add('청유');