mulmoterminal 7.3.0 → 8.0.0

package/README.md

@@ -1059,6 +1059,20 @@ they came from. It also names the keys it **dropped** (a color that isn't `#rrgg
 of range) and the keys it doesn't read at all (`badgeColour`, a global-only setting) — which is
 what tells "I never set that" apart from "I set it and it didn't take".
 
+**Changing it there.** Under the values, **Change here** is a form for the name, the seven chrome
+colors, how the header shows a running session (`headerStatusTint`) and its colour per status
+(`headerStatusColors`), the terminal theme and palette (`colors`), font size, font family, grid priority, the model its
+sessions start on (`provider` / `model`), the closing summary (`appendSystemPrompt`) and extra
+directories (`addDirs`), its icon, terminal background, and attention sounds (`sound` / `sounds`), and its header buttons,
+chips and command-palette entries (`buttons` / `chips` / `commands`) with the same editors the global
+lists use, its Skill menu (`skills`, in order), Mulmo menu decks (`decks`) and per-worktree variables
+(`worktreeEnv`) — every key the file can hold. **This checkout only** moves a key into
+`.mulmoterminal.local.json` (and **Share** moves it back). A cell's path menu has **This directory's
+settings**, which opens Settings on that directory. Each change is written to
+the directory's file at once and applies without a restart; **Use global** takes the key out
+again. A key `.mulmoterminal.local.json` already holds is written there. Keys the form doesn't
+show are left as they are, and a file that isn't a JSON object is not touched — fix it in Files.
+
 ---
 
 ## Running
@@ -2083,6 +2097,7 @@ From a shell: `mulmoterminal room read <room>` · `room post <room> <text…> [-
 | -------- | ------- |
 | `GET\|POST /api/config` | User UI config (`cwdPresets`, `soundFile`, `soundKinds`, `sounds`, `prRepos`, `launchers`, `quickCommands`, `userMcpServers`, `providers`). |
 | `GET /api/sound?kind=` · `/api/dir-sound?cwd=&kind=` · `/api/sound-preset/:id` · `/api/dir-config?cwd=` | Custom / per-directory / preset attention sound + per-dir config. `kind` selects a config entry, never a path. |
+| `PUT /api/dir-config` | The Settings form's save: `{ cwd, set: { key: value }, unset: [key] }` for the keys the form edits (`common/dirConfigForm.ts`), each validated like the Files pane's editor. Other keys and their order are kept; a file that isn't a JSON object answers 422 and is not written. Answers with the new `dir-config-detail`. |
 | `GET /api/dir-config-detail?cwd=` | The same per-dir config, **plus** the settings a running terminal doesn't need (`provider`, `model`, `skills`, `addDirs`, header button/chip **labels**), **plus** which keys the file set and how each fared (applied / dropped in validation / not a setting at all). Read-only; backs the Settings modal's **Directory settings** preview. Unlike the other `?cwd=` routes this one does **not** fall back to the default workspace — it reports on the directory it was asked about, so a path that no longer exists comes back as `exists:false`. Sound paths and button commands stay server-side. |
 | `GET /api/launch-options` | The Anthropic-compatible backends this server can reach, each with its models and — when it can't — the reason. Reports the **name** of the env var a key is read from, never the key. |
 | `GET /api/update-status` | What is running and whether anything newer exists: `install` (`npm` / `git`), `version`, `commit` (a checkout's short HEAD sha), `latest` (npm, only when newer) and the one-line `notice`. Backs the header's **Update** badge and the Settings version line. Served from memory, recomputed at startup and every 3 hours — a long-running server started with `npx mulmoterminal@latest` is current when it starts, so only a later check can tell it a release shipped. `ready` is false until the first check lands. |

package/blueprints/adopt/checks/adopt.mjs

@@ -0,0 +1,106 @@
+// The adopt usecase's two checks. `survey`: .blueprint/adopt.json records the genre the person chose and how many
+// findings chaff reports on the places today, measured again here; nothing in the repository has changed yet.
+// `apply`: chaff.yaml names that genre and keeps what it had, .chaff-baseline.json shelves today's findings so chaff
+// now reports none, and the workflow — when asked for — reports only what is new, with no more rights than that.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fromBase } from "./base.mjs";
+import { placesIn, workflowProblems } from "./setup.mjs";
+const { actionable, fail, findingsIn, readJson, runChaff } = await import(fromBase("chaff.mjs"));
+const { lostLines } = await import(fromBase("config.mjs"));
+
+const RECORD = ".blueprint/adopt.json";
+const READABLE = ".blueprint/adopt.txt";
+const CHECKED = ".blueprint/.adopt-checked";
+const CONFIG = "chaff.yaml";
+const BASELINE = ".chaff-baseline.json";
+const WORKFLOW = ".github/workflows/chaff.yml";
+const WITH_CI = "GitHub の PR に指摘を出すワークフローを作る";
+
+const answers = readJson(".blueprint/answers.json", "the interview answers");
+const { places, refused } = placesIn(answers.places);
+if (refused.length > 0) fail(`these places are outside this folder: ${refused.join(", ")}`);
+if (places.length === 0) fail("the answer names no place to check");
+const absent = places.filter((place) => !existsSync(place));
+if (absent.length > 0) fail(`not in this folder: ${absent.join(", ")}`);
+const kinds = JSON.parse(readFileSync(join(process.env.BLUEPRINT_USECASE, "kinds.json"), "utf8")).kinds;
+const genre = kinds.find((kind) => kind.option === answers.kind)?.genre;
+if (!genre) fail(`the answer kind ${JSON.stringify(answers.kind)} is not one of the kinds in kinds.json`);
+
+const textOrNull = (file) => (existsSync(file) ? readFileSync(file, "utf8") : null);
+const findingsNow = (extra) => places.flatMap((place) => findingsIn(place, extra).filter(actionable));
+const byRule = (findings) =>
+  Object.entries(findings.reduce((counts, finding) => ({ ...counts, [finding.rule]: (counts[finding.rule] ?? 0) + 1 }), {})).sort(
+    ([a, x], [b, y]) => y - x || a.localeCompare(b),
+  );
+
+const survey = () => {
+  const record = readJson(RECORD, '{ "genre", "findings" }');
+  const measured = findingsNow(["--genre", genre]);
+  if (record?.genre !== genre) fail(`${RECORD}: "genre" must be ${genre}, the genre of the kind the person chose`);
+  if (record?.findings !== measured.length) fail(`${RECORD}: "findings" is ${record?.findings}, but chaff reports ${measured.length} as ${genre} now`);
+  writeFileSync(
+    READABLE,
+    [`genre: ${genre}`, `findings: ${measured.length}`, ...byRule(measured).map(([rule, count]) => `  ${rule}: ${count}`), ""].join("\n"),
+  );
+  writeFileSync(CHECKED, JSON.stringify({ config: textOrNull(CONFIG), workflow: existsSync(WORKFLOW), findings: measured.length }) + "\n");
+  console.log(`${measured.length} finding(s) today as ${genre}`);
+};
+
+const recorded = () => {
+  try {
+    return JSON.parse(readFileSync(CHECKED, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+const workflowSide = (checked) => {
+  if (answers.ci === WITH_CI) {
+    if (!existsSync(WORKFLOW)) return [`${WORKFLOW} is missing`];
+    const template = readFileSync(join(process.env.BLUEPRINT_USECASE, "templates", "chaff.yml"), "utf8");
+    return workflowProblems(readFileSync(WORKFLOW, "utf8"), template, places).map((problem) => `${WORKFLOW}: ${problem}`);
+  }
+  return !checked.workflow && existsSync(WORKFLOW) ? [`${WORKFLOW} was added, but the person chose no workflow`] : [];
+};
+
+const apply = () => {
+  const checked = existsSync(CHECKED) ? recorded() : null;
+  if (checked === null || typeof checked !== "object") fail("the survey step's record is missing: run that step again");
+  if (!existsSync(CONFIG)) fail(`${CONFIG} is missing`);
+  const run = runChaff(["rules", "--json"]);
+  if (run.code !== 0) fail(`chaff could not load ${CONFIG}:\n${run.stderr}`);
+  const detected = JSON.parse(run.stdout).detected?.genre;
+  const baseline = existsSync(BASELINE) ? readJson(BASELINE, '{ "entries" }') : null;
+  const left = findingsNow([]);
+  // The shelf is the survey's, taken under this chaff.yaml: shown with what it shelves, chaff reports what was measured.
+  const shelved = findingsNow(["--show-baseline"]);
+  const problems = [
+    ...(detected === genre ? [] : [`${CONFIG} gives genre ${detected}, not ${genre}`]),
+    ...lostLines(checked.config, readFileSync(CONFIG, "utf8"), ["genre"]).map((line) => `${CONFIG} lost a line it had: ${line.trim()}`),
+    ...(baseline === null ? [`${BASELINE} is missing: run chaff baseline on the places`] : []),
+    ...(baseline !== null && (baseline.entries?.length ?? 0) < checked.findings
+      ? [`${BASELINE} shelves ${baseline.entries?.length ?? 0} finding(s), fewer than the ${checked.findings} measured`]
+      : []),
+    ...(shelved.length === checked.findings
+      ? []
+      : [
+          `with its baseline shown, chaff reports ${shelved.length} finding(s) under ${CONFIG}, not the ${checked.findings} measured: the settings or the shelf are not the ones the person approved`,
+        ]),
+    ...(left.length === 0
+      ? []
+      : [
+          `chaff still reports ${left.length} finding(s) the baseline does not shelve: ${byRule(left)
+            .map(([rule, count]) => `${rule} ${count}`)
+            .join(", ")}`,
+        ]),
+    ...workflowSide(checked),
+  ];
+  if (problems.length > 0) fail(problems.join("\n"));
+  console.log(`chaff is set up: today's ${checked.findings} finding(s) shelved, only new ones will be reported`);
+};
+
+const mode = process.argv[2];
+if (mode === "survey") survey();
+else if (mode === "apply") apply();
+else fail(`usage: adopt.mjs survey | apply (got ${JSON.stringify(mode)})`);

package/blueprints/adopt/checks/base.mjs

@@ -0,0 +1,12 @@
+// The docs base holds the helpers every usecase on it shares (running chaff, reading Markdown sections).
+// A usecase loads them from BLUEPRINT_BASE, which the executor sets for every check.
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+if (!process.env.BLUEPRINT_BASE) {
+  console.error("BLUEPRINT_BASE is not set: run this check through the blueprint executor");
+  process.exit(1);
+}
+
+/** The URL of a module in the docs base's checks/, for `await import(...)`. */
+export const fromBase = (file) => pathToFileURL(join(process.env.BLUEPRINT_BASE, "checks", file)).href;

package/blueprints/adopt/checks/report.mjs

@@ -0,0 +1,22 @@
+// The report tells the person what was set up and how chaff behaves from now on: it names chaff.yaml, the baseline,
+// and the workflow when one was made.
+import { existsSync, readFileSync } from "node:fs";
+import { fromBase } from "./base.mjs";
+const { fail, readJson } = await import(fromBase("chaff.mjs"));
+const { missingSections } = await import(fromBase("markdown.mjs"));
+
+const REPORT = ".blueprint/adopt-report.md";
+const WITH_CI = "GitHub の PR に指摘を出すワークフローを作る";
+
+if (!existsSync(REPORT)) fail(`${REPORT} is missing`);
+const text = readFileSync(REPORT, "utf8");
+const missing = missingSections(text, [
+  ["入れたもの", "What was set up"],
+  ["棚に上げた指摘", "Shelved findings"],
+  ["これから", "From now on"],
+]);
+if (missing.length > 0) fail(`${REPORT} lacks sections: ${missing.join(", ")}`);
+const ci = readJson(".blueprint/answers.json", "the interview answers").ci === WITH_CI;
+const named = ["chaff.yaml", ".chaff-baseline.json", ...(ci ? [".github/workflows/chaff.yml"] : [])].filter((file) => !text.includes(file));
+if (named.length > 0) fail(`${REPORT} does not name: ${named.join(", ")}`);
+console.log("the report names what was set up");

package/blueprints/adopt/checks/setup.d.mts

@@ -0,0 +1,4 @@
+// Types for setup.mjs, which the pack runs with plain node and the specs import.
+export declare const placesIn: (answer: unknown) => { places: string[]; refused: string[] };
+export declare const workflowFor: (template: string, places: readonly string[]) => string;
+export declare const workflowProblems: (workflow: string, template: string, places: readonly string[]) => string[];

package/blueprints/adopt/checks/setup.mjs

@@ -0,0 +1,47 @@
+// What adopting chaff in a folder of documents has to leave behind: the places chaff watches, and the workflow that
+// reports on them. The workflow is the pack's template filled in with the places, exactly: a workflow is judged
+// by being that one known file, not by reading arbitrary YAML for what might be unsafe in it.
+import { posix } from "node:path";
+
+// A place goes into the workflow's command line unquoted, so only characters with no meaning to a shell are allowed:
+// letters and digits of any script, and . _ - / — never a leading - (it would read as an option).
+const SAFE = /^[\p{L}\p{N}._/-]+$/u;
+
+/** The places the answer names, one a line, as paths inside this folder; a line that leaves it or is unsafe is `refused`. */
+export const placesIn = (answer) => {
+  const lines = String(answer ?? "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+  const inside = (line) => {
+    const path = posix.normalize(line.replaceAll("\\", "/"));
+    if (posix.isAbsolute(path) || /^[A-Za-z]:/u.test(path) || path === ".." || path.startsWith("../")) return null;
+    const trimmed = path.replace(/\/$/u, "") || ".";
+    return SAFE.test(trimmed) && !trimmed.startsWith("-") ? trimmed : null;
+  };
+  return {
+    places: [...new Set(lines.map(inside).filter((path) => path !== null))],
+    refused: lines.filter((line) => inside(line) === null),
+  };
+};
+
+/** The workflow the pack writes for `places`: its template with the places in the chaff run. */
+export const workflowFor = (template, places) => String(template).replace("{{PATHS}}", places.join(" "));
+
+// Line endings and trailing spaces aside (a line's trailing \r goes with its spaces): an editor's habits are not a different workflow.
+const normalized = (text) =>
+  String(text)
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trimEnd();
+
+/** What is wrong with `workflow`: anything but the template filled in with `places`. */
+export const workflowProblems = (workflow, template, places) => {
+  if (normalized(workflow) === normalized(workflowFor(template, places))) return [];
+  const expected = normalized(workflowFor(template, places)).split("\n");
+  const actual = normalized(workflow).split("\n");
+  const at = expected.findIndex((line, index) => actual[index] !== line);
+  const line = at < 0 ? expected.length + 1 : at + 1;
+  return [`it is not the pack's template filled in with the places (first difference at line ${line}): copy the template again`];
+};

package/blueprints/adopt/hearing.json

@@ -0,0 +1,42 @@
+{
+  "questions": [
+    {
+      "id": "places",
+      "label": "chaff に見させる文書（このフォルダの中のフォルダかファイルを 1 行に 1 つ）",
+      "why": "ここにある文書の今の指摘を棚に上げ、以後はここの新しい指摘だけが出る",
+      "kind": "text",
+      "lines": true,
+      "pick": "files"
+    },
+    {
+      "id": "kind",
+      "label": "どんな文書ですか",
+      "why": "文書の種類ごとの物差し（文の長さの上限、どの検査を動かすか）で chaff が測る",
+      "kind": "select",
+      "options": [
+        "手順書・ヘルプ・マニュアル",
+        "README・開発者向けの説明",
+        "仕様書・設計書",
+        "よくある質問",
+        "用語集",
+        "技術ブログ",
+        "会社のサイトの記事（オウンドメディア）",
+        "報告書・社内文書",
+        "提案書・企画書",
+        "議事録",
+        "プレスリリース・お知らせ",
+        "契約書・利用規約",
+        "規程・社内規則",
+        "論文"
+      ]
+    },
+    {
+      "id": "ci",
+      "label": "GitHub の PR に指摘を出しますか",
+      "why": "作ると、PR を出すたびに chaff が動き、新しい指摘がその行に出る",
+      "kind": "select",
+      "options": ["GitHub の PR に指摘を出すワークフローを作る", "作らない（手元で npx chaffjs を動かす）"],
+      "needsPath": { "GitHub の PR に指摘を出すワークフローを作る": ".git" }
+    }
+  ]
+}

package/blueprints/adopt/kinds.json

@@ -0,0 +1,18 @@
+{
+  "kinds": [
+    { "option": "手順書・ヘルプ・マニュアル", "genre": "docs/manual" },
+    { "option": "README・開発者向けの説明", "genre": "technical/readme" },
+    { "option": "仕様書・設計書", "genre": "technical/spec" },
+    { "option": "よくある質問", "genre": "docs/faq" },
+    { "option": "用語集", "genre": "docs/glossary" },
+    { "option": "技術ブログ", "genre": "blog/tech" },
+    { "option": "会社のサイトの記事（オウンドメディア）", "genre": "blog/owned-media" },
+    { "option": "報告書・社内文書", "genre": "business/report" },
+    { "option": "提案書・企画書", "genre": "business/proposal" },
+    { "option": "議事録", "genre": "business/meeting-notes" },
+    { "option": "プレスリリース・お知らせ", "genre": "business/press-release" },
+    { "option": "契約書・利用規約", "genre": "legal/contract" },
+    { "option": "規程・社内規則", "genre": "legal/statute" },
+    { "option": "論文", "genre": "academic/paper" }
+  ]
+}

package/blueprints/adopt/manifest.json

@@ -0,0 +1,9 @@
+{
+  "slug": "adopt",
+  "kind": "usecase",
+  "title": "文書のフォルダに chaff を入れる（今ある指摘は棚に上げて）",
+  "version": "0.1.0",
+  "description": "既にある文書のフォルダに chaff を入れる。文書の種類に合わせた chaff.yaml を置き、今ある指摘は chaff baseline で棚に上げて、新しい指摘だけが出るようにする。望めば、GitHub の PR の行に指摘が出るワークフローも作る。原本は変えない。",
+  "bases": ["docs"],
+  "report": ".blueprint/adopt-report.md"
+}

package/blueprints/adopt/presets/help-pages/export.md

@@ -0,0 +1,9 @@
+# データを書き出す
+
+## CSV で書き出す
+
+一覧の画面の右上にある「書き出し」を押して「CSV」を選ぶと、いま表示している条件で絞り込んだ行だけが、文字コードが UTF-8 のファイルとしてダウンロードされるので、表計算ソフトで開くときは文字コードを指定してください。
+
+## 書き出せないとき
+
+一度に書き出せるのは 10,000 行までです。それより多いときは、期間を分けて書き出してください。

package/blueprints/adopt/presets/help-pages/login.md

@@ -0,0 +1,9 @@
+# ログインできないとき
+
+## パスワードを忘れたとき
+
+ログイン画面の「パスワードを忘れた方」を押し、登録しているメールアドレスを入れると、パスワードを設定し直すためのリンクが届くので、そのリンクを開いて新しいパスワードを二回入れてから「保存」を押してください。
+
+## アカウントがロックされたとき
+
+パスワードを5回続けて間違えると、アカウントが30分ロックされます。30分たってから、もう一度ログインしてください。

package/blueprints/adopt/presets.json

@@ -0,0 +1,15 @@
+{
+  "presets": [
+    {
+      "id": "help-pages",
+      "title": "ヘルプのページに chaff を入れる",
+      "description": "見本のヘルプ（login.md と export.md）を「手順書・ヘルプ・マニュアル」として測り、今ある長すぎる文の指摘を棚に上げて、以後は新しい指摘だけが出るようにする。GitHub の PR に指摘を出すワークフローも作る。原本は変えない。",
+      "base": "docs",
+      "answers": {
+        "places": "login.md\nexport.md",
+        "kind": "手順書・ヘルプ・マニュアル",
+        "ci": "GitHub の PR に指摘を出すワークフローを作る"
+      }
+    }
+  ]
+}

package/blueprints/adopt/skills/apply/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: blueprint-adopt-apply
+description: "Set chaff up in the folder: chaff.yaml for the chosen genre, today's findings shelved in .chaff-baseline.json, and, when asked, a GitHub workflow that puts new findings on the pull request's lines."
+---
+
+# Set chaff up
+
+The person approved the setup in `.blueprint/adopt.json`. The documents stay exactly as they are: fixing what is
+shelved is 「文書を整える」's work, later.
+
+## 1. chaff.yaml
+
+Write the folder's `chaff.yaml` with the genre from `.blueprint/adopt.json` and the documents' `language`
+(`npx chaffjs init --genre <genre>` writes a commented one). If the folder already has one, set its `genre` to the
+chosen one and **keep every other line it has** — the check refuses any other line of the old file that is gone. Add the rule
+levels the person agreed to at the gate, nothing else.
+
+## 2. Shelve today's findings
+
+Run `sh <base pack>/checks/chaff.sh baseline <place> …` with every place. It writes `.chaff-baseline.json` in the
+folder: the findings there today are not reported again; new ones are. Tell the person to commit it with
+`chaff.yaml`.
+
+## 3. The workflow — only when `ci` is 「GitHub の PR に指摘を出すワークフローを作る」
+
+Copy `<usecase pack>/templates/chaff.yml` to `.github/workflows/chaff.yml`, replacing `{{PATHS}}` with the places
+separated by spaces, and change nothing else: the check compares the file with the template filled in that way, line
+for line. Its `permissions:` let the workflow read the documents (`contents: read`) and upload findings
+(`security-events: write`), nothing more. A place whose name has a space or a character a shell reads (`$`, `;`, `*`,
+quotes…) cannot go into the workflow: the interview refuses it, so ask the person to name a folder above it instead. When `ci` is 「作らない」, add nothing under `.github/`.
+
+## 4. The report
+
+Write `.blueprint/adopt-report.md` for the person, in their language and in plain words:
+
+- `## 入れたもの` / `## What was set up` — `chaff.yaml` (the genre, and why), `.chaff-baseline.json`, and the
+  workflow `.github/workflows/chaff.yml` when one was made. The check looks for each file's name.
+- `## 棚に上げた指摘` / `## Shelved findings` — how many were shelved, by rule, in plain words.
+- `## これから` / `## From now on` — only new findings are reported (run `npx chaffjs <places>` by hand, or see them
+  on the pull request's lines); how to lower the shelf later (「文書を整える」, then `chaff baseline` again); that
+  the workflow needs code scanning enabled on the repository (a public repository has it; a private one needs
+  GitHub Advanced Security).
+
+## Done when
+
+`node <usecase pack>/checks/adopt.mjs apply` and then `node <usecase pack>/checks/report.mjs` (with `BLUEPRINT_BASE`
+and `BLUEPRINT_USECASE` set) pass.

package/blueprints/adopt/skills/survey/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: blueprint-adopt-survey
+description: "Measure what chaff reports on the named documents today, as the kind the person chose, and propose the setup — changing nothing yet."
+---
+
+# Measure what is there today
+
+`.blueprint/answers.json` names the places chaff will watch (`places`, a folder or a file a line), what kind of
+documents they are (`kind`) and whether a GitHub workflow is wanted (`ci`). The person may not be an engineer: say
+what you do in plain words.
+
+Change nothing in the repository: this step only measures. The person approves the setup before anything is
+written.
+
+## Measure
+
+The kind maps to a genre in `<usecase pack>/kinds.json`. For each place, run
+`sh <base pack>/checks/chaff.sh <place> --genre <genre> --compact` and count the warnings and errors, by rule. Read a
+few of them: a rule that reports mostly what the documents do on purpose may be worth turning down in `chaff.yaml`
+rather than shelving — say which, and why, for the person to decide at the gate.
+
+## Write `.blueprint/adopt.json`
+
+```json
+{ "genre": "docs/manual", "findings": 2, "proposal": "chaff.yaml に genre と language を書き、今の 2 件を棚に上げる。" }
+```
+
+`findings` is the number of warnings and errors chaff reports on all the places together, as that genre, now; the
+check measures it again. If the folder already has a `chaff.yaml` or a `.chaff-baseline.json`, say so in
+`proposal`: the next step keeps what they hold.
+
+## Done when
+
+`node <usecase pack>/checks/adopt.mjs survey` (with `BLUEPRINT_BASE` and `BLUEPRINT_USECASE` set to the pack folders
+from your prompt) passes. It writes `.blueprint/adopt.txt`, what the person reads before anything changes.

package/blueprints/adopt/steps.json

@@ -0,0 +1,20 @@
+{
+  "steps": [
+    {
+      "id": "survey",
+      "title": "今の指摘を測る",
+      "description": "選んだ種類で、文書に今どれだけ指摘があるかを測り、入れる設定の案を書く。まだ何も変えない。",
+      "skill": "skills/survey",
+      "check": "node \"$BLUEPRINT_USECASE/checks/adopt.mjs\" survey"
+    },
+    {
+      "id": "apply",
+      "title": "chaff を入れる",
+      "description": "chaff.yaml を置き、今の指摘を .chaff-baseline.json に棚上げし、望めば PR に指摘を出すワークフローを足す。以後は新しい指摘だけが出ることを機械で確かめる。",
+      "skill": "skills/apply",
+      "check": "node \"$BLUEPRINT_USECASE/checks/adopt.mjs\" apply && node \"$BLUEPRINT_USECASE/checks/report.mjs\"",
+      "gates": ["review"],
+      "reads": [".blueprint/adopt.txt"]
+    }
+  ]
+}

package/blueprints/adopt/templates/chaff.yml

@@ -0,0 +1,29 @@
+# Checks the documents with chaff on every pull request, and puts each new finding on the line it is about.
+# The findings already in the documents are shelved in .chaff-baseline.json, so only new ones appear.
+name: chaff
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  chaff:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+      - run: npx -y chaffjs@0.16 {{PATHS}} --sarif chaff.sarif
+        continue-on-error: true
+      - uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
+        with:
+          sarif_file: chaff.sarif
+          category: chaff

package/blueprints/docs/checks/chaff.mjs

@@ -14,7 +14,7 @@ export const runChaff = (args) => {
 };
 
 /**
- * Every finding chaff reports for `target`, as { rule, level, file, line }. `extra` adds arguments (such as
+ * Every finding chaff reports for `target`, as { rule, level, file, line, message }. `extra` adds arguments (such as
  * `--experimental`). Throws when chaff did not produce SARIF.
  */
 export const findingsIn = (target, extra = []) => {
@@ -34,6 +34,7 @@ export const findingsIn = (target, extra = []) => {
         level: String(result.level ?? "warning"),
         file: String(result.locations?.[0]?.physicalLocation?.artifactLocation?.uri ?? ""),
         line: Number(result.locations?.[0]?.physicalLocation?.region?.startLine ?? 0),
+        message: String(result.message?.text ?? ""),
       })),
     );
   } finally {

package/blueprints/docs/checks/chaff.sh

@@ -4,4 +4,4 @@
 if [ -n "${CHAFF_BIN:-}" ]; then
   exec sh -c "$CHAFF_BIN \"\$@\"" chaff "$@"
 fi
-exec npx -y chaffjs@0.15 "$@"
+exec npx -y chaffjs@0.16 "$@"

package/blueprints/docs/checks/config.d.mts

@@ -0,0 +1,3 @@
+// Types for config.mjs, which the packs run with plain node and the specs import.
+export declare const settingLines: (text: string) => string[];
+export declare const lostLines: (before: string | null, after: string, replaceable?: readonly string[]) => string[];

package/blueprints/docs/checks/config.mjs

@@ -0,0 +1,18 @@
+// A folder's chaff.yaml as a check reads it without a YAML parser: what a usecase may add to it, and what it must keep.
+
+/** The lines of chaff.yaml that say something (not blank, not a comment), as written. */
+export const settingLines = (text) =>
+  String(text)
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() !== "" && !line.trim().startsWith("#"));
+
+// A top-level `key:` line of chaff.yaml, as its key.
+const topKey = (line) => (/^\S/u.test(line) ? line.split(":")[0].trim() : null);
+
+/**
+ * The lines `before` had that `after` no longer has: a change that was meant to add must lose none — except the
+ * top-level keys in `replaceable`, which the change sets on purpose (adopting a folder sets its `genre`).
+ */
+export const lostLines = (before, after, replaceable = []) =>
+  before === null ? [] : settingLines(before).filter((line) => !replaceable.includes(topKey(line)) && !settingLines(after).includes(line));

package/blueprints/docs/checks/markdown.d.mts

@@ -6,4 +6,5 @@ export declare const sectionsOf: (markdown: string) => Section[];
 export declare const missingSections: (markdown: string, wanted: readonly (readonly string[])[]) => string[];
 export declare const skeletonOf: (markdown: string) => Skeleton;
 export declare const skeletonChanges: (before: string, after: string) => string[];
+export declare const namedIn: (text: string, name: string) => boolean;
 export declare const sectionText: (markdown: string, names: readonly string[]) => string;

package/blueprints/docs/checks/markdown.mjs

@@ -98,3 +98,17 @@ export const sectionText = (markdown, names) => {
   const end = rest.findIndex((line) => headingLevel(line) > 0 && headingLevel(line) <= depth);
   return rest.slice(0, end < 0 ? rest.length : end).join("\n");
 };
+
+// A letter or a digit of any script: a name next to one is part of a longer word (支払い方法, 第4条の2).
+const WORD = /[\p{L}\p{N}]/u;
+
+/** Whether `text` names `name` as a whole: not as the start, end or middle of a longer word. */
+export const namedIn = (text, name) => {
+  const source = String(text);
+  const escaped = String(name).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return [...source.matchAll(new RegExp(escaped, "gu"))].some((match) => {
+    const start = match.index ?? 0;
+    const [before, after] = [source.slice(0, start).slice(-1), source.slice(start + name.length, start + name.length + 1)];
+    return !WORD.test(before) && !WORD.test(after);
+  });
+};

package/blueprints/docs/skills/workspace/SKILL.md

@@ -12,7 +12,7 @@ repository, `.git/info/exclude`) until the person has approved the models.
 1. `.blueprint/` already exists (the build created it). Everything this build records goes there.
 2. Run chaff once through the base pack's wrapper, so its first download happens now and not in the
    middle of a later step: `sh <base pack>/checks/chaff.sh rules --json > /dev/null`. The wrapper runs the
-   pinned chaff (`npx -y chaffjs@0.15`) unless `CHAFF_BIN` names another. If it fails, show the person the
+   pinned chaff (`npx -y chaffjs@0.16`) unless `CHAFF_BIN` names another. If it fails, show the person the
    error and stop — do not work around it.
 3. If the folder is a git repository, add `.blueprint/` to `.git/info/exclude`. That keeps the build's
    working files out of commits without touching `.gitignore`, which belongs to the person.

package/blueprints/glossary/checks/base.mjs

@@ -0,0 +1,12 @@
+// The docs base holds the helpers every usecase on it shares (running chaff, reading Markdown sections).
+// A usecase loads them from BLUEPRINT_BASE, which the executor sets for every check.
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+if (!process.env.BLUEPRINT_BASE) {
+  console.error("BLUEPRINT_BASE is not set: run this check through the blueprint executor");
+  process.exit(1);
+}
+
+/** The URL of a module in the docs base's checks/, for `await import(...)`. */
+export const fromBase = (file) => pathToFileURL(join(process.env.BLUEPRINT_BASE, "checks", file)).href;