litgrok-ai 0.2.0 → 0.2.4

package/.grok/skills/frontend-ui-ux/scripts/strict-json.mjs

@@ -0,0 +1,143 @@
+export class StrictJsonError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "StrictJsonError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+const RESERVED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+function fail(code, message, offset) {
+  throw new StrictJsonError(code, `${message} at byte ${offset}`, { offset });
+}
+
+export function decodeStrictUtf8(bytes) {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    if (text.charCodeAt(0) === 0xfeff) fail("JSON_INVALID_UTF8", "UTF-8 BOM is not permitted", 0);
+    if (text.includes("\0")) fail("JSON_INVALID_UTF8", "NUL is not permitted", text.indexOf("\0"));
+    return text;
+  } catch (error) {
+    if (error instanceof StrictJsonError) throw error;
+    throw new StrictJsonError("JSON_INVALID_UTF8", "input is not valid UTF-8");
+  }
+}
+
+export function parseStrictJson(text) {
+  let index = 0;
+  const whitespace = () => {
+    while (index < text.length && /[\u0009\u000a\u000d\u0020]/u.test(text[index])) index += 1;
+  };
+  const string = () => {
+    const start = index;
+    if (text[index++] !== "\"") fail("JSON_SYNTAX_INVALID", "expected string", index);
+    while (index < text.length) {
+      const character = text[index++];
+      if (character === "\"") {
+        try {
+          return JSON.parse(text.slice(start, index));
+        } catch {
+          fail("JSON_SYNTAX_INVALID", "invalid string escape", start);
+        }
+      }
+      if (character < "\u0020") fail("JSON_SYNTAX_INVALID", "control character in string", index - 1);
+      if (character === "\\") {
+        const escape = text[index++];
+        if (escape === "u") {
+          const hex = text.slice(index, index + 4);
+          if (!/^[0-9a-f]{4}$/iu.test(hex)) fail("JSON_SYNTAX_INVALID", "invalid unicode escape", index);
+          index += 4;
+        } else if (!"\"\\/bfnrt".includes(escape ?? "")) {
+          fail("JSON_SYNTAX_INVALID", "invalid string escape", index - 1);
+        }
+      }
+    }
+    fail("JSON_SYNTAX_INVALID", "unterminated string", start);
+  };
+  const number = () => {
+    const match = text.slice(index).match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/u);
+    if (!match) fail("JSON_SYNTAX_INVALID", "invalid number", index);
+    index += match[0].length;
+    const value = Number(match[0]);
+    if (!Number.isFinite(value)) fail("JSON_SYNTAX_INVALID", "non-finite number", index);
+    return value;
+  };
+  const value = () => {
+    whitespace();
+    if (text[index] === "\"") return string();
+    if (text[index] === "{") return object();
+    if (text[index] === "[") return array();
+    for (const [literal, parsed] of [["true", true], ["false", false], ["null", null]]) {
+      if (text.startsWith(literal, index)) {
+        index += literal.length;
+        return parsed;
+      }
+    }
+    return number();
+  };
+  const array = () => {
+    index += 1;
+    const result = [];
+    whitespace();
+    if (text[index] === "]") {
+      index += 1;
+      return result;
+    }
+    while (index < text.length) {
+      result.push(value());
+      whitespace();
+      if (text[index] === "]") {
+        index += 1;
+        return result;
+      }
+      if (text[index++] !== ",") fail("JSON_SYNTAX_INVALID", "expected comma", index - 1);
+      whitespace();
+    }
+    fail("JSON_SYNTAX_INVALID", "unterminated array", index);
+  };
+  const object = () => {
+    index += 1;
+    const result = {};
+    const keys = new Set();
+    whitespace();
+    if (text[index] === "}") {
+      index += 1;
+      return result;
+    }
+    while (index < text.length) {
+      whitespace();
+      const keyOffset = index;
+      const key = string();
+      if (RESERVED_KEYS.has(key)) {
+        fail("JSON_RESERVED_KEY", `reserved object key ${JSON.stringify(key)}`, keyOffset);
+      }
+      if (keys.has(key)) fail("JSON_DUPLICATE_KEY", `duplicate object key ${JSON.stringify(key)}`, keyOffset);
+      keys.add(key);
+      whitespace();
+      if (text[index++] !== ":") fail("JSON_SYNTAX_INVALID", "expected colon", index - 1);
+      result[key] = value();
+      whitespace();
+      if (text[index] === "}") {
+        index += 1;
+        return result;
+      }
+      if (text[index++] !== ",") fail("JSON_SYNTAX_INVALID", "expected comma", index - 1);
+    }
+    fail("JSON_SYNTAX_INVALID", "unterminated object", index);
+  };
+  const parsed = value();
+  whitespace();
+  if (index !== text.length) fail("JSON_SYNTAX_INVALID", "unexpected trailing data", index);
+  return parsed;
+}
+
+export function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) =>
+      `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/.grok/skills/frontend-ui-ux/scripts/validate-design-contract.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// Validate one litfamily.design-contract/v1alpha1 artifact.
+//
+// Exit-code contract:
+//   0  the contract is valid. stdout carries exactly one line of JSON with the keys
+//      valid, schema, and issues (an empty array). stderr stays empty.
+//   1  the bytes parsed but the contract is invalid. stdout carries the same one-line
+//      envelope with valid false and a populated issues array, so a caller can machine-read
+//      every defect from a single run.
+//   2  the input could not be trusted at all: missing, non-regular, oversize, non-UTF-8,
+//      malformed JSON, or carrying duplicate object keys. A human-readable line goes to
+//      stderr and stdout stays empty, because there is nothing trustworthy to report.
+//
+// The code is always assigned to process.exitCode and never passed to process.exit(). An
+// immediate exit can discard a buffered stdout write when stdout is a pipe, which would turn
+// a populated exit-1 envelope into silence. Assigning the code lets Node flush and then exit.
+import { realpathSync } from "node:fs";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import { errorMessage, UiuxContractError } from "./errors.mjs";
+import { readDesignContract } from "./design-contract-format.mjs";
+import { designContractReport } from "./design-contract-rules.mjs";
+
+const USAGE = "usage: validate-design-contract <design-contract.json>";
+
+export function validateDesignContract(path) {
+  const { value } = readDesignContract(path);
+  return designContractReport(value);
+}
+
+function main() {
+  const [path, ...extra] = process.argv.slice(2);
+  if (typeof path !== "string" || path.length === 0 || extra.length > 0) {
+    process.stderr.write(`INVALID_ARGUMENT: ${USAGE}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  let report;
+  try {
+    report = validateDesignContract(path);
+  } catch (error) {
+    const code = error instanceof UiuxContractError ? error.code : "DESIGN_CONTRACT_UNTRUSTED_INPUT";
+    process.stderr.write(`${code}: ${errorMessage(error)}\n`);
+    process.exitCode = 2;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(report)}\n`);
+  process.exitCode = report.valid ? 0 : 1;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === realpathSync(process.argv[1])) main();

package/.grok/skills/frontend-ui-ux/scripts/verify-canonical-corpus.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const CORPUS_ROOTS = Object.freeze(['design', 'designpowers', 'perfection', 'ui-ux-db']);
+const MANIFEST_RELATIVE = '_canonical-corpus/manifest.json';
+const EXPECTED = Object.freeze({
+  schemaVersion: ['lit', 'claude'].join('') + '.canonical-frontend-corpus/v1',
+  source: Object.freeze({
+    commit: '8ec16c5129df7b9778959e8367657d0e79c2c3bb',
+    reference_tree: '9188410be0af35f2421ba300d91a0d7a7341caf0',
+    reference_subtree: 'frontend/references',
+  }),
+  fileCount: 167,
+  byteCount: 2_596_349,
+  aggregateSha256: 'f6959eeae02685102df9fbedafb2c437be4d51df8e102f9fcf32298f7674e7d7',
+  legalTreeSha256: '2b7174f0662a5e41259b922fd1d94c24670df66894c7b9f81c9595ebd35fbc52',
+  datasetBytes: 1_023_482,
+  datasetSha256: 'a89011236a6ff14e12ec55fccbfab1bbd40ae34614cea5710c022121aa841bb8',
+});
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function expectedKeys(value, keys, label, failures) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    failures.push(`${label} is not an object`);
+    return false;
+  }
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    failures.push(`${label} keys mismatch`);
+    return false;
+  }
+  return true;
+}
+
+function safeRelativePath(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && !value.startsWith('/')
+    && !value.includes('\\')
+    && value.split('/').every((part) => part !== '' && part !== '.' && part !== '..');
+}
+
+function listFiles(directory, prefix = '') {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const child = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const childPath = join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(childPath, child));
+    else if (entry.isFile()) files.push(child);
+    else throw new Error(`non-regular entry: ${child}`);
+  }
+  return files;
+}
+
+function readBytes(referencesRoot, relativePath) {
+  return readFileSync(join(referencesRoot, ...relativePath.split('/')));
+}
+
+function parseRoot(argv) {
+  if (argv.length === 0) return SKILL_ROOT;
+  if (argv.length === 2 && argv[0] === '--root' && argv[1] && !argv[1].startsWith('-')) return resolve(argv[1]);
+  throw new Error('usage: verify-canonical-corpus.mjs [--root <skill-directory>]');
+}
+
+function verify(skillRoot) {
+  const failures = [];
+  const referencesRoot = join(skillRoot, 'references');
+  const manifestPath = join(referencesRoot, ...MANIFEST_RELATIVE.split('/'));
+  if (!existsSync(manifestPath)) return ['missing _canonical-corpus/manifest.json'];
+
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    return [`manifest unreadable: ${error instanceof Error ? error.message : String(error)}`];
+  }
+
+  if (expectedKeys(manifest, [
+    'aggregate_sha256',
+    'byte_count',
+    'file_count',
+    'files',
+    'independent_normalized_dataset',
+    'legal',
+    'schema_version',
+    'source',
+  ], 'manifest', failures)) {
+    if (manifest.schema_version !== EXPECTED.schemaVersion) failures.push('schema_version mismatch');
+    if (JSON.stringify(manifest.source) !== JSON.stringify(EXPECTED.source)) failures.push('source metadata mismatch');
+    if (manifest.file_count !== EXPECTED.fileCount) failures.push(`file_count expected ${EXPECTED.fileCount}, got ${manifest.file_count}`);
+    if (manifest.byte_count !== EXPECTED.byteCount) failures.push(`byte_count expected ${EXPECTED.byteCount}, got ${manifest.byte_count}`);
+    if (manifest.aggregate_sha256 !== EXPECTED.aggregateSha256) failures.push('aggregate_sha256 metadata mismatch');
+  }
+  const filesAreValid = Array.isArray(manifest.files);
+  const legalIsValid = Array.isArray(manifest.legal);
+  if (!filesAreValid) failures.push('manifest.files is not an array');
+  if (!legalIsValid) failures.push('manifest.legal is not an array');
+  if (filesAreValid && manifest.files.length !== EXPECTED.fileCount) failures.push(`manifest.files length expected ${EXPECTED.fileCount}, got ${manifest.files.length}`);
+  if (legalIsValid && manifest.legal.length !== 3) failures.push(`manifest.legal length expected 3, got ${manifest.legal.length}`);
+
+  if (expectedKeys(manifest.independent_normalized_dataset, ['record_count', 'sha256', 'source_count'], 'dataset metadata', failures)) {
+    if (manifest.independent_normalized_dataset.source_count !== 34) failures.push('dataset source_count mismatch');
+    if (manifest.independent_normalized_dataset.record_count !== 2277) failures.push('dataset record_count mismatch');
+    if (manifest.independent_normalized_dataset.sha256 !== EXPECTED.datasetSha256) failures.push('dataset sha256 metadata mismatch');
+  }
+
+  const entries = [];
+  const paths = new Set();
+  for (const [index, entry] of (filesAreValid ? manifest.files : []).entries()) {
+    if (!expectedKeys(entry, ['path', 'sha256', 'size'], `files[${index}]`, failures)) continue;
+    if (!safeRelativePath(entry.path) || !CORPUS_ROOTS.some((root) => entry.path.startsWith(`${root}/`))) {
+      failures.push(`files[${index}] path is outside the canonical roots: ${entry.path}`);
+      continue;
+    }
+    if (paths.has(entry.path)) failures.push(`duplicate manifest path: ${entry.path}`);
+    paths.add(entry.path);
+    entries.push({ kind: 'corpus', ...entry });
+  }
+  for (const [index, entry] of (legalIsValid ? manifest.legal : []).entries()) {
+    if (!expectedKeys(entry, ['path', 'sha256', 'size', 'source_path'], `legal[${index}]`, failures)) continue;
+    if (!safeRelativePath(entry.path) || !entry.path.startsWith('_canonical-corpus/legal/')) {
+      failures.push(`legal[${index}] path is outside the legal root: ${entry.path}`);
+      continue;
+    }
+    if (!safeRelativePath(entry.source_path)) failures.push(`legal[${index}] source_path is unsafe: ${entry.source_path}`);
+    if (paths.has(entry.path)) failures.push(`duplicate manifest path: ${entry.path}`);
+    paths.add(entry.path);
+    entries.push({ kind: 'legal', ...entry });
+  }
+
+  const expectedCorpusPaths = entries.filter(({ kind }) => kind === 'corpus').map(({ path }) => path).sort();
+  const expectedLegalPaths = [MANIFEST_RELATIVE, ...entries.filter(({ kind }) => kind === 'legal').map(({ path }) => path)].sort();
+  try {
+    const actualCorpusPaths = CORPUS_ROOTS.flatMap((root) => listFiles(join(referencesRoot, root), '')
+      .map((path) => `${root}/${path}`)).sort();
+    if (JSON.stringify(actualCorpusPaths) !== JSON.stringify(expectedCorpusPaths)) failures.push('corpus file set mismatch');
+  } catch (error) {
+    failures.push(`corpus inventory failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  try {
+    const actualLegalPaths = listFiles(join(referencesRoot, '_canonical-corpus'), '_canonical-corpus').sort();
+    if (JSON.stringify(actualLegalPaths) !== JSON.stringify(expectedLegalPaths)) failures.push('legal file set mismatch');
+  } catch (error) {
+    failures.push(`legal inventory failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const actualHashes = new Map();
+  let corpusBytes = 0;
+  for (const entry of entries) {
+    let bytes;
+    try {
+      bytes = readBytes(referencesRoot, entry.path);
+    } catch (error) {
+      failures.push(`missing ${entry.path}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const actualHash = digest(bytes);
+    actualHashes.set(entry.path, actualHash);
+    if (bytes.byteLength !== entry.size) failures.push(`size mismatch: ${entry.path}`);
+    if (actualHash !== entry.sha256) failures.push(`sha256 mismatch: ${entry.path}`);
+    if (entry.kind === 'corpus') corpusBytes += bytes.byteLength;
+  }
+  if (corpusBytes !== EXPECTED.byteCount) failures.push(`corpus byte count expected ${EXPECTED.byteCount}, got ${corpusBytes}`);
+  const aggregate = entries.filter(({ kind }) => kind === 'corpus').every(({ path }) => actualHashes.has(path))
+    ? digest(entries.filter(({ kind }) => kind === 'corpus').map(({ path }) => `${actualHashes.get(path)}  ${path}\n`).join(''))
+    : null;
+  if (aggregate !== EXPECTED.aggregateSha256) failures.push(`aggregate sha256 expected ${EXPECTED.aggregateSha256}, got ${aggregate}`);
+
+  if (legalIsValid) {
+    const legalRows = manifest.legal
+      .map(({ path, source_path: sourcePath, size, sha256: sha }) => ({ path, sourcePath, size, sha256: sha }))
+      .sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0)
+      .map(({ path, sourcePath, size, sha256: sha }) => `${JSON.stringify([path, sourcePath, size, sha])}\n`)
+      .join('');
+    const legalTree = digest(legalRows);
+    if (legalTree !== EXPECTED.legalTreeSha256) failures.push(`legal tree sha256 expected ${EXPECTED.legalTreeSha256}, got ${legalTree}`);
+  }
+
+  const datasetPath = join(skillRoot, 'data', 'design-intelligence.json');
+  try {
+    const dataset = readFileSync(datasetPath);
+    if (dataset.byteLength !== EXPECTED.datasetBytes) failures.push(`dataset byte count expected ${EXPECTED.datasetBytes}, got ${dataset.byteLength}`);
+    if (digest(dataset) !== EXPECTED.datasetSha256) failures.push('dataset sha256 mismatch');
+  } catch (error) {
+    failures.push(`dataset unreadable: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  return failures;
+}
+
+let skillRoot;
+try {
+  skillRoot = parseRoot(process.argv.slice(2));
+  if (!existsSync(skillRoot) || !lstatSync(skillRoot).isDirectory()) throw new Error(`skill root is not a directory: ${skillRoot}`);
+  const failures = verify(skillRoot);
+  if (failures.length > 0) {
+    console.error(`FAIL ${failures.join('; ')}`);
+    process.exitCode = 1;
+  } else {
+    console.log(`PASS canonical-frontend-corpus files=${EXPECTED.fileCount} bytes=${EXPECTED.byteCount} sha256=${EXPECTED.aggregateSha256}`);
+  }
+} catch (error) {
+  console.error(`FAIL ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}

package/.grok/skills/lit-comprehend/SKILL.md

@@ -25,6 +25,8 @@ limitations_channel: designated_section
 Load `references/artifact-format.md` when the explanation must be written outside the repository or survive beyond the current session.
 Load `references/honesty-ledger-contract.md` when classifying claim strength, conflicts, stale evidence, or missing probes.
 Load `references/worked-explainer.md` when the requested explanation resembles an install boundary, failure trace, configuration-scope conflict, or stale test receipt.
+Load `references/artifact-template.md` when composing the portable explainer sections, diagrams, quiz markup, or Markdown fallback.
+Load `references/micro-worlds.md` when the explanation benefits from a small faithful miniature, slider, step-through, or old/new interaction.
 
 ## Establish the question
 

package/.grok/skills/lit-comprehend/references/artifact-template.md

@@ -0,0 +1,219 @@
+# Artifact template — sections, diagrams, quiz markup
+
+Read this when composing the explainer. It pairs with
+`assets/explainer-scaffold.html`, which already contains the CSS, the quiz
+engine, and the diagram classes referenced below. Copy the scaffold, replace
+`__TITLE__`, `__SUBTITLE__`, `__TOC__`, and `__CONTENT__`, and write only the
+content — reinventing the boilerplate per invocation wastes tokens and produces
+a different-looking artifact every time.
+
+```bash
+SKILL_DIR="$(dirname "$0")/.."            # or the resolved skill path
+OUTPUT_DIR="/path/approved-by-user"
+OUT="$OUTPUT_DIR/$(date +%F)-<slug>.html"
+mkdir -p "$OUTPUT_DIR"
+cp "$SKILL_DIR/assets/explainer-scaffold.html" "$OUT"
+# then edit $OUT, replacing the four placeholders
+```
+
+The TOC is an `<ol>` of `<li><a href="#s1">한눈에</a></li>` entries; give each
+`<h2>` a matching `id`.
+
+## Section contract
+
+Headers are byte-identical across every LitFamily harness. Keep the Korean
+header text exactly as written even when the body is English.
+
+### 1. 한눈에
+
+One tight paragraph, then a confidence line. The reader should be able to stop
+here and still be better off. Say what changed, why it was done, and what to
+look at first. Then a `.note` callout stating how much of this is verified:
+
+```html
+<div class="note ok">
+  <span class="label">신뢰도</span>
+  <p>동작 확인: 테스트 3건 통과 · 실제 실행 1건. 코드만 읽고 추론한 부분: 2건 (아래 확인 안 된 것 참고).</p>
+</div>
+```
+
+### 2. 이미 알고 있던 것
+
+The delta anchor. Restate, in the reader's own terms, the objective they set and
+the state the system was in when they last had a clear picture. Quote the
+objective from `goals.json` verbatim — it is literally their sentence.
+
+If the change required machinery the reader has genuinely not met, introduce it
+here inside `.skippable`, so someone who already knows it can move past without
+wondering what they missed:
+
+```html
+<div class="skippable">
+  <p><strong>배경 (이미 아는 내용이면 건너뛰세요)</strong> — …</p>
+</div>
+```
+
+### 3. 직관
+
+One subsection per theme. Essence before mechanism: the problem, one concrete
+piece of toy data moving through, and why the obvious alternative fails. Reuse
+the same toy data across the whole document.
+
+### 4. 바뀐 것
+
+The literate walkthrough, in conceptual order. Prose leads; each excerpt lands
+where the reader has just been given a reason to care.
+
+Every code block carries `data-src` so the verifier can confirm the quote is
+real. Add a line anchor when it helps the reader navigate:
+
+```html
+<pre data-src="src/ledger.mjs:88-104">export function appendEvent(event) {
+  const line = JSON.stringify(event) + '\n';
+  <span class="add">const tmp = LEDGER + '.tmp';
+  writeFileSync(tmp, readIfExists(LEDGER) + line);
+  renameSync(tmp, LEDGER);</span>
+}</pre>
+```
+
+`.add` and `.del` shade inserted and removed lines. The verifier skips `.del`
+content when checking quotes against the current file, since deleted lines are
+correctly absent.
+
+### 5. 직접 만져보기
+
+The micro-world. See `micro-worlds.md`. Omit the section for purely structural
+changes rather than inventing a pointless widget.
+
+### 6. 확인 안 된 것
+
+The honesty ledger. Concrete lines, not hedging prose. Use `.note warn` or
+`.note bad` for anything that could bite:
+
+```html
+<div class="note warn">
+  <span class="label">실행되지 않음</span>
+  <p><code>.grok/hooks/user-prompt-submit.mjs</code>의 새 분기는 작성되었지만
+     이번 세션에서 한 번도 실행되지 않았습니다. 라우트가 실제로 닿는지 확인 전.</p>
+</div>
+```
+
+### 7. 증거
+
+A table mapping claim to proof. Wrap it in `.scroll-x` so it never forces the
+page to scroll sideways.
+
+```html
+<div class="scroll-x"><table>
+  <tr><th>주장</th><th>근거</th><th>확인 방법</th><th>결과</th></tr>
+  <tr>
+    <td>원장이 중간 크래시에도 손상되지 않음</td>
+    <td><code>test/ledger-atomic.test.mjs</code></td>
+    <td><code>npm test -- ledger-atomic</code></td>
+    <td>3 pass</td>
+  </tr>
+</table></div>
+```
+
+A row whose 결과 column would be "미확인" belongs in 확인 안 된 것 instead.
+
+### 8. 퀴즈
+
+Five questions (three for a small change). Open with one sentence framing it as
+a throttle, not a grade, and include the score element the engine updates:
+
+```html
+<div class="quiz-q" data-answer="2">
+  <p class="q"><span class="n">1.</span> 원장 쓰기가 rename 기반으로 바뀐 뒤,
+     쓰기 도중 프로세스가 죽으면 <code>ledger.jsonl</code>은 어떤 상태인가?</p>
+  <button class="opt" data-i="0">마지막 줄이 잘린 채 남는다</button>
+  <button class="opt" data-i="1">빈 파일이 된다</button>
+  <button class="opt" data-i="2">직전 상태 그대로 남는다</button>
+  <button class="opt" data-i="3">tmp 파일과 함께 병합된다</button>
+  <div class="fb" data-i="0">이전 구현의 동작입니다. append 중 죽으면 부분 줄이 남았고, 그게 이 변경의 이유입니다.</div>
+  <div class="fb" data-i="1">쓰기는 tmp에서 일어나므로 원본은 비워지지 않습니다.</div>
+  <div class="fb" data-i="2">정답입니다. rename은 원자적이라 성공 아니면 무변경 둘 중 하나입니다.</div>
+  <div class="fb" data-i="3">병합 로직은 없습니다. tmp는 고아로 남고 원본은 그대로입니다.</div>
+</div>
+<p class="quiz-score" id="quiz-score">— 문항을 눌러 확인하세요.</p>
+```
+
+Two tells to design out, both of which readers learn faster than the material:
+
+- **위치** — vary the correct slot; never three in a row in the same position.
+  The verifier fails the artifact for this.
+- **길이** — keep all options within a similar length. If the correct option is
+  the longest every time, that is the answer key. Detail belongs in the
+  feedback, which is where the reader is already looking.
+
+Every option gets feedback, including the correct one, and each explains *why*.
+A wrong click is the only moment in the document where you know exactly what the
+reader misunderstood; spending a sentence there is worth more than a paragraph
+anywhere else.
+
+### 9. 다음
+
+Three concrete entry points — a file to open, a question worth asking, a risk
+worth closing. Not "consider adding tests"; name the test.
+
+## Diagram families
+
+Pick two or three and reuse them. A new visual language per section costs the
+reader more than it teaches.
+
+**Pipeline** — stages and data flow. Always show the example datum changing.
+
+```html
+<figure>
+  <div class="pipe">
+    <div class="box"><span class="t">입력</span><span class="d">{id:7}</span></div>
+    <span class="arrow">→</span>
+    <div class="box hi"><span class="t">정규화</span><span class="d">신규</span></div>
+    <span class="arrow">→</span>
+    <div class="box"><span class="t">원장</span><span class="d">1줄 추가</span></div>
+  </div>
+  <figcaption>이벤트 하나가 원장에 닿기까지. 강조된 단계가 이번에 추가됐습니다.</figcaption>
+</figure>
+```
+
+**Before / after** — usually the right first diagram. Same structure twice, only
+the changed element highlighted.
+
+```html
+<figure>
+  <div class="ba">
+    <div class="side"><h4>이전</h4>
+      <div class="pipe"><div class="box">append</div><span class="arrow">→</span><div class="box ghost">부분 줄</div></div>
+    </div>
+    <div class="side after"><h4>이후</h4>
+      <div class="pipe"><div class="box">tmp 쓰기</div><span class="arrow">→</span><div class="box hi">rename</div></div>
+    </div>
+  </div>
+  <figcaption>실패 지점이 "쓰는 중"에서 "이름 바꾸기 직전"으로 옮겨갔습니다.</figcaption>
+</figure>
+```
+
+**State / timeline** — for anything ordering-sensitive: what is true after each
+step. A table with a step column reads better than boxes here.
+
+**Simplified UI** — a stripped rendering of what the user sees, for surface
+changes. Two or three `.box` elements in a frame beat a screenshot you cannot
+take.
+
+Never ASCII art. It collapses on wrap, cannot carry color or emphasis, and the
+verifier fails on box-drawing characters outside code blocks.
+
+## Language
+
+Korean prose by default; English on `--en` or an English request. Headers stay
+Korean either way. Technical tokens — paths, commands, identifiers, versions,
+error strings — stay verbatim in every mode. Never translate an error message;
+the reader needs to be able to grep for it.
+
+## Markdown fallback
+
+`--md`, or any environment where HTML cannot be opened. Same nine headers as
+`##` sections. Quizzes become `<details>` blocks with the answer and all
+per-option feedback inside. Micro-worlds become a worked example that shows
+every intermediate value, since the reader cannot poke it. Keep `data-src`
+information as a path line above each fenced block so quotes stay traceable.