@shinaps/skills 0.48.0 → 0.50.0

package/README.md

@@ -3,7 +3,7 @@
 Claude Code と Codex で使う、開発ワークフローのスキル集です。調査・仕様の整理・実装・レビュー・コミット・PR・リリースの手順を、それぞれのクライアント向けの plugin として配布します。
 
 - 実装は Claude Code が行います。Codex は調査・レビュー・Linear での進行管理と QA を担当します。
-- 導入に Shinaps AI のアカウントは不要です。コーディング規約（rule）の照合・抽出を使うときだけ、[Shinaps AI](https://app.shinaps.ai) でアカウントを作成して MCP を接続します。
+- 導入に Shinaps AI のアカウントは不要です。コーディング規約（rule）の照合・登録を使うときだけ、[Shinaps AI](https://app.shinaps.ai) でアカウントを作成して MCP を接続します。
 
 ## 必要なもの
 
@@ -36,7 +36,7 @@ Claude Code では `/shinaps:<スキル名>`（例 `/shinaps:review`）で呼び
 
 1. `explore` で今の挙動と変更の影響を調べる。要件が曖昧なら `spec` で仕様を詰める。
 2. Claude Code の `dev-claude` で実装する。体制（LITE・BASIC・ULTRA）を選ぶと、実装とは別の担当が計画や実装をレビューします。
-3. `simplify` で不要な構造を削り、`review` で差分を確かめる。
+3. `review` で差分を確かめる。体制（LITE・BASIC・ULTRA）を選べ、規約照合や簡素化だけの依頼もできます。追加修正の後や、実装時と違う体制で確かめたいときにも単独で使えます。指摘の検証と報告までを行い、修正は依頼されたときだけ開発の担当へ引き継ぎます。
 4. `commit`・`create-pr`・`release` で、コミット・PR・公開を行う。これらは依頼されたとき、または Linear で合意した終了地点までの進行を依頼されたときに実行します。操作ごとの許可の一覧は持たず、依頼の範囲とプロジェクトの制約で判断します（[依頼範囲と操作](plugins/shinaps-claude/references/request-scope.md)）。
 
 スキルは、対象プロジェクトの `AGENTS.md`・`CLAUDE.md`・README・CI・既存のスクリプトから、対象の環境・必要な検証・公開の条件を読み取ります。書かれていない条件は、結果を左右するものだけを確認します。Linear と Claude Managed Agents 以外のスキルは、専用の設定ファイル無しで使えます。`linear-execute` での開発の進行には `.shinaps/linear.json`、Managed Agents への依頼には `.shinaps/managed.json` が必要です（下の「機能別の資料」）。
@@ -49,10 +49,7 @@ Claude Code では `/shinaps:<スキル名>`（例 `/shinaps:review`）で呼び
 | `spec` | 目的・仕様・実現方法を詰める |
 | `dev-claude`（Claude のみ） | 選んだ体制で実装し、別の担当が独立にレビューする |
 | `debug` | 不具合の原因を調べて確かめる |
-| `review` | 差分や既存のコードをレビューする |
-| `refine` | Shinaps AI の rule と実際のファイルを照合する |
-| `extract-rules` | PR のレビューから rule を抽出する |
-| `simplify` | 目的から見直して、不要な構造や手順を削る |
+| `review` | 差分や既存のコードを、選んだ体制でレビューする（規約照合・可読性・慣習・簡素化を含む） |
 | `commit` | 変更を単位に分けてコミットする |
 | `create-pr` | リポジトリの規約に合わせて PR を作る |
 | `release` | 公開条件を確かめて公開し、対象の版を使えることを確かめる |
@@ -67,6 +64,7 @@ Claude Code では `/shinaps:<スキル名>`（例 `/shinaps:review`）で呼び
 |---|---|
 | 更新・削除・macOS での Codex の自動更新 | [導入と更新](docs/install.md) |
 | `dev-claude` の体制と工程 | [実装体制の判断](plugins/shinaps-claude/references/dev/staffing.md)・[dev の工程](plugins/shinaps-claude/references/dev/workflow.md) |
+| レビューの担当の構成と指摘の採否・単独起動の手順 | [レビューの共通契約](plugins/shinaps-claude/references/review.md)・[単独レビューの手順](plugins/shinaps-claude/references/review-standalone.md) |
 | Linear での開発進行（`.shinaps/linear.json` の書き方・終了地点と制約・auto と manual） | [プロジェクト設定](plugins/shinaps-claude/references/linear/configuration.md)・[担当と工程](plugins/shinaps-claude/references/linear/workflow.md) |
 | Claude Managed Agents（必要なもの・導入・依頼） | [設定とアカウント](plugins/shinaps-claude/references/managed/configuration.md)・[導入と更新](plugins/shinaps-claude/references/managed/setup.md)・[依頼と観測](plugins/shinaps-claude/references/managed/execute.md) |
 | スキルが使う担当（サブエージェント）の一覧 | [サブエージェント](docs/agents.md) |
@@ -75,9 +73,27 @@ Claude Code では `/shinaps:<スキル名>`（例 `/shinaps:review`）で呼び
 
 旧版の設定は自動では変換しません。Linear は [旧設定の移行](plugins/shinaps-claude/references/linear/configuration.md#旧設定の移行)（0.48.0 から `config_version: 3`。操作ごとの許可の一覧を廃止し `constraints` に置き換え）、Managed Agents は [version 1 からの移行](plugins/shinaps-claude/references/managed/configuration.md#version-1-からの移行)に従ってください。
 
+### 0.50.0 の変更
+
+- 規約の照合は、plugin の hook が保存した応答から作る snapshot を担当と機械検査が読みます。Codex では hook の信頼が要り、plugin の更新のたびに `/hooks` で信頼し直します（[導入と更新](docs/install.md#規約の-hook)）。
+- 確定した規約の適用結果を既定で本人の集計へ記録します。作業ごとに OFF にでき、直近 90 日で集計から外れて削除されます（[導入と更新](docs/install.md#規約の適用結果の記録)）。Shinaps AI 側の配備が先に要ります。
+
+### 0.49.0 の変更
+
+`refine`・`simplify`・`extract-rules` のスキルを廃止しました。規約照合と簡素化は `review` に依頼します（「規約照合だけ」「簡素化だけ」と限定できます）。規約の登録はその場で AI に依頼します。PR からの一括抽出の代わりになるスキルはありません。計画の簡素化だけを単独で起動する手段も無くなり、dev の計画レビューに含まれます。
+
+`review` の名前は同じですが、次の動作が変わります。
+
+- 既定では指摘の検証と報告で終わり、修正や次の操作の質問をしません。修正まで依頼すると、開発の担当が修正と再レビューを行い、未コミットの差分を返します。Codex の `review` は Linear 進行でなくてもローカルの Claude CLI を権限確認を省くモード（`bypassPermissions`）で起動して修正を渡します。操作は依頼の範囲に限り、CLI が無いときは止まります。
+- 指摘の独立検証と外部調査は、毎回ではなく、依頼されたときや判断を左右するときに行います。
+- 変更を対象にしたレビューでは、変更と無関係な既存箇所の規約違反を Critical にせず、別の一覧で報告します。ファイル・ディレクトリを指定した場合は、指定した全体を対象に重要度を下げません。
+- 引数なしの対象は、ベースブランチからのコミット済みの差分と作業ツリーの変更です。
+
+dev の実装後レビューでは、規約に機械検査があるときに配布 CLI の `lint` を使います（使えないときは AI が照合します）。
+
 ## Shinaps AI との接続
 
-`refine`・`extract-rules` など rule を使う工程に必要です。導入とは別に設定し、既存の登録があれば再利用します。同じサーバーを plugin とグローバル設定の両方に登録しないでください。認証情報は各クライアントの認証で管理し、このリポジトリの CLI では扱いません。
+`review` や `dev-claude` の規約照合など rule を使う工程に必要です。確定した規約の適用結果は既定で本人の集計へ記録します（送るのは規約の id、作業の key、結果の別だけで、作業ごとに OFF にでき、90 日で削除されます。[導入と更新](docs/install.md#規約の適用結果の記録)）。規約の全文は plugin の hook が応答をそのまま保存した snapshot から担当へ渡します。Codex では hook の信頼が要り、plugin の更新のたびに信頼し直します（[導入と更新](docs/install.md#規約の-hook)）。規約の登録・更新はその場で AI に依頼します（[規約の書き方](plugins/shinaps-claude/references/rule-writing.md)）。導入とは別に設定し、既存の登録があれば再利用します。同じサーバーを plugin とグローバル設定の両方に登録しないでください。認証情報は各クライアントの認証で管理し、このリポジトリの CLI では扱いません。
 
 ```sh
 # Claude Code（登録後、Claude Code 内の /mcp から認証）

package/dist/bin/skills.js

@@ -8,6 +8,8 @@ import { managed } from "../lib/managed.js";
 import { run } from "../lib/install.js";
 import { autoUpdate } from "../lib/auto-update.js";
 import { lint } from "../lib/lint.js";
+import { ruleCoverage } from "../lib/rule-coverage.js";
+import { ruleSnapshot } from "../lib/rule-snapshot.js";
 import { errorMessage } from "../lib/fs.js";
 const [command, ...rest] = process.argv.slice(2);
 try {
@@ -32,6 +34,10 @@ try {
         await autoUpdate(rest);
     else if (command === 'lint')
         await lint(rest);
+    else if (command === 'rule-snapshot')
+        await ruleSnapshot(rest);
+    else if (command === 'rule-coverage')
+        await ruleCoverage(rest);
     else
         await run(process.argv.slice(2));
 }

package/dist/lib/args.js

@@ -0,0 +1,11 @@
+/** `--` の前の引数と、後ろの対象ファイルに分ける。 */
+export function splitFiles(args) {
+    const separator = args.indexOf('--');
+    return separator === -1
+        ? { flags: args, files: [] }
+        : { flags: args.slice(0, separator), files: args.slice(separator + 1) };
+}
+/** `--name value` を、繰り返しも含めて読む。 */
+export function flagValues(args, name) {
+    return args.flatMap((arg, index) => (arg === name && args[index + 1] ? [args[index + 1]] : []));
+}

package/dist/lib/fs.js

@@ -1,9 +1,28 @@
 import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import { basename, dirname, join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { basename, dirname, join, resolve } from 'node:path';
 /** OS エラーの code (ENOENT など)。Error 以外や code を持たないエラーは undefined。 */
 export const errorCode = (error) => error instanceof Error ? error.code : undefined;
 export const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+export const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+/**
+ * ファイルの内容の sha256。
+ * @param root files の基準のディレクトリ
+ * @param files root からの相対パス。無いファイルは結果に含めない
+ */
+export async function hashFiles(root, files) {
+    const hashes = {};
+    for (const file of files) {
+        try {
+            hashes[file] = sha256(await readFile(resolve(root, file)));
+        }
+        catch (error) {
+            if (errorCode(error) !== 'ENOENT')
+                throw error;
+        }
+    }
+    return hashes;
+}
 export const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));
 /** JSON ファイルを読む。無ければ null。 */
 export async function readJsonIfExists(path) {

package/dist/lib/install.js

@@ -2,9 +2,11 @@ import { readFile, readdir, cp, rm, mkdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { digest, registerPlugin, replaceInstallation, restore, } from "./transaction.js";
+import { registerPlugin, replaceInstallation, restore, } from "./transaction.js";
 import { withLock } from "./lock.js";
-import { readTextIfExists, writeFileAtomic } from "./fs.js";
+import { readTextIfExists, sha256, writeFileAtomic } from "./fs.js";
+import { RULE_COVERAGE_COMMAND } from "./rule-coverage.js";
+import { RULE_SNAPSHOT_COMMAND } from "./rule-snapshot.js";
 import { codexHomeMismatch, codexHomeOf, isRecordedCodexHome, managedAgent, managedRoot, marketplaceName, packageRoot, payloadDir, payloadPaths, pluginDir, pluginId, statePath, } from "./layout.js";
 const actions = ['install', 'update', 'uninstall', 'recover'];
 const isAction = (value) => actions.includes(value);
@@ -15,6 +17,8 @@ const usage = [
     '       shinaps-skills managed <setup|run|status|reply|collect> (see managed --help)',
     '       shinaps-skills auto-update <enable|disable|status|check> codex',
     '       shinaps-skills lint --checks <checks.json> --root <project> --out <result.json> -- <files...>',
+    `       ${RULE_SNAPSHOT_COMMAND}`,
+    `       ${RULE_COVERAGE_COMMAND}`,
     'Claude Code: /plugin marketplace add sh1n4ps/shinaps-skills',
     '             /plugin install shinaps@shinaps-skills',
 ].join('\n');
@@ -173,7 +177,7 @@ async function readVerifiedState(installation) {
         const current = await readTextIfExists(join(agentsDir, name));
         if (current === null)
             continue;
-        const currentHash = digest(current);
+        const currentHash = sha256(current);
         if (currentHash !== hash && currentHash !== state.pending?.[name]) {
             throw new Error(`Modified agent preserved: ${join(agentsDir, name)}. Move the edited file elsewhere or restore its content, then retry.`);
         }
@@ -192,7 +196,7 @@ async function readPackagedAgents(installation, state) {
         if (!(name in state.agents) && (await readTextIfExists(join(agentsDir, name))) !== null) {
             throw new Error(`Unmanaged agent preserved: ${join(agentsDir, name)}. Shinaps did not install this file. Move or rename it, then retry.`);
         }
-        agents[name] = { content, hash: digest(content) };
+        agents[name] = { content, hash: sha256(content) };
     }
     return agents;
 }

package/dist/lib/lint.js

@@ -2,7 +2,8 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { checkKey, classify, parseLintInput, planUnits, } from "./lint-plan.js";
 import { shinapsPlugin } from "./lint-rules.js";
-import { errorMessage } from "./fs.js";
+import { splitFiles } from "./args.js";
+import { errorMessage, hashFiles, sha256 } from "./fs.js";
 const USAGE = 'Usage: shinaps-skills lint --checks <checks.json> --root <project> --out <result.json> -- <files...>';
 /**
  * `shinaps-skills lint`: 規約の検査を、プロジェクトの設定を使わずに ESLint の Node API で実行し、
@@ -12,9 +13,13 @@ const USAGE = 'Usage: shinaps-skills lint --checks <checks.json> --root <project
  */
 export async function lint(args) {
     const options = parseArgs(args);
-    const input = parseLintInput(JSON.parse(await readFile(options.checks, 'utf8')));
+    const checksText = await readFile(options.checks);
+    const input = parseLintInput(JSON.parse(checksText.toString('utf8')));
+    const files = await hashFiles(options.root, options.files.map((file) => toRelative(options.root, file)));
     const result = await runLint(input, options.root, options.files);
-    await writeFile(options.out, `${JSON.stringify(result, null, 2)}\n`);
+    // 結果がどの検査とどの内容のファイルから作られたかを残し、古い結果を機械確認として使わないようにする。
+    const output = { ...result, checksSha256: sha256(checksText), files };
+    await writeFile(options.out, `${JSON.stringify(output, null, 2)}\n`);
     const counts = Object.fromEntries(['covered', 'violation', 'partial', 'not-run'].map((state) => [
         state,
         result.pairs.filter((pair) => pair.state === state).length,
@@ -22,9 +27,7 @@ export async function lint(args) {
     console.log(`Shinaps lint: ${JSON.stringify(counts)} → ${options.out}`);
 }
 function parseArgs(args) {
-    const separator = args.indexOf('--');
-    const flags = separator === -1 ? args : args.slice(0, separator);
-    const files = separator === -1 ? [] : args.slice(separator + 1);
+    const { flags, files } = splitFiles(args);
     const value = (name) => {
         const index = flags.indexOf(name);
         const found = index === -1 ? undefined : flags[index + 1];

package/dist/lib/managed-session.js

@@ -1,7 +1,7 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
-import { readJson, readJsonIfExists, writeFileAtomic } from "./fs.js";
+import { readJson, readJsonIfExists, sha256, writeFileAtomic } from "./fs.js";
 import { withLock } from "./lock.js";
 import { filesBeta, managedBeta } from "./managed-ant.js";
 import { importSnapshot } from "./managed-snapshot.js";
@@ -14,7 +14,6 @@ const permissionLabels = {
     push: 'headへのpush',
     draft_pr: 'draft PRの作成',
 };
-const sha256 = (text) => createHash('sha256').update(text).digest('hex');
 /**
  * `--transform id -r` の出力から ID を取り出す。ant は transform のパスが応答に無いと応答の全体を
  * 出すので、ID の形でない出力を ID として記録しない。

package/dist/lib/rule-coverage.js

@@ -0,0 +1,151 @@
+import { writeFile } from 'node:fs/promises';
+import { isAbsolute, normalize, relative } from 'node:path';
+import { flagValues, splitFiles } from "./args.js";
+import { hashFiles, readJson } from "./fs.js";
+import { verifySnapshot } from "./rule-snapshot.js";
+export const RULE_COVERAGE_COMMAND = 'shinaps-skills rule-coverage --manifest <manifest.json> --target-version <version> [--lint <result.json>] [--report <report.json> ...] --out <coverage.json> -- <files...>';
+const NO_REPORT = 'no report for this snapshot and target version covers this file';
+/**
+ * 規約×ファイルの組を次の優先順でちょうど一つに区分する。機械が保証するのは同じ snapshot と ID・保存データ・対象の版の
+ * 整合までで、reported は担当の申告（読了や理解の証明ではない）。
+ * - machine: lint の covered・violation
+ * - reported: この snapshot と版の報告のどれかが、そのファイルを completedFiles に挙げ、その規約を unchecked に挙げていない
+ * - unconfirmed: それ以外。報告に書かれていないファイルは、省略から自動で reported にならない
+ * @param input.manifest snapshot の manifest
+ * @param input.targetVersion 確認対象の固定版。報告の版と比べる
+ * @param input.files 対象ファイル（lint の結果と同じ基準の相対パス）
+ * @param input.lint 最新の版で実行した lint の結果。実行できなければ null
+ * @param input.reports 担当の報告。分担したときは担当ごとの要素を全部渡す。対象の外のファイルの記述は数えない
+ */
+export function classifyCoverage(input) {
+    const { manifest, targetVersion } = input;
+    const targets = new Set(input.files.map((file) => normalize(file)));
+    const ids = new Set(manifest.ruleIds);
+    const machinePairKeys = new Set((input.lint?.pairs ?? [])
+        .filter((pair) => pair.state === 'covered' || pair.state === 'violation')
+        .map((pair) => `${pair.ruleId}\0${normalize(pair.file)}`));
+    const reports = input.reports
+        .filter((entry) => entry.contentHash === manifest.contentHash && entry.targetVersion === targetVersion)
+        .map((entry) => {
+        const incomplete = new Map(entry.incompleteFiles.map((file) => [normalize(file.path), file.reason]));
+        return {
+            incomplete,
+            completed: new Set(entry.completedFiles
+                .map((file) => normalize(file))
+                .filter((file) => !incomplete.has(file))),
+            unchecked: new Map(entry.unchecked.map((rule) => [rule.id, rule.reason])),
+        };
+    });
+    for (const { unchecked } of reports) {
+        for (const id of unchecked.keys()) {
+            if (!ids.has(id))
+                throw new Error(`The report names a rule outside the snapshot: ${id}`);
+        }
+    }
+    const counts = { machine: 0, reported: 0, unconfirmed: 0 };
+    const unconfirmedRules = new Map();
+    const unconfirmedFiles = new Map();
+    for (const id of manifest.ruleIds) {
+        for (const file of targets) {
+            const covering = reports.filter((report) => report.completed.has(file));
+            if (machinePairKeys.has(`${id}\0${file}`)) {
+                counts.machine++;
+            }
+            else if (covering.some((report) => !report.unchecked.has(id))) {
+                counts.reported++;
+            }
+            else {
+                counts.unconfirmed++;
+                const ruleReason = reports.find((report) => report.unchecked.has(id))?.unchecked.get(id);
+                if (ruleReason !== undefined)
+                    unconfirmedRules.set(id, ruleReason);
+                if (covering.length === 0) {
+                    const fileReason = reports
+                        .find((report) => report.incomplete.has(file))
+                        ?.incomplete.get(file);
+                    unconfirmedFiles.set(file, fileReason ?? NO_REPORT);
+                }
+            }
+        }
+    }
+    return {
+        contentHash: manifest.contentHash,
+        targetVersion,
+        counts,
+        unconfirmedRules: [...unconfirmedRules].map(([id, reason]) => ({ id, reason })),
+        unconfirmedFiles: [...unconfirmedFiles].map(([path, reason]) => ({ path, reason })),
+    };
+}
+const isKeyWithReason = (entry, key) => typeof entry?.[key] === 'string' && typeof entry.reason === 'string';
+const isReport = (entry) => typeof entry?.contentHash === 'string' &&
+    typeof entry.targetVersion === 'string' &&
+    Array.isArray(entry.completedFiles) &&
+    entry.completedFiles.every((file) => typeof file === 'string') &&
+    Array.isArray(entry.unchecked) &&
+    entry.unchecked.every((item) => isKeyWithReason(item, 'id')) &&
+    Array.isArray(entry.incompleteFiles) &&
+    entry.incompleteFiles.every((item) => isKeyWithReason(item, 'path'));
+/** AI が書いた報告を読む。形の揺れを受け入れると未確認が一覧から消えるので、何を直すかが分かるように失敗する。 */
+function parseReports(raw) {
+    if (!Array.isArray(raw) || !raw.every(isReport)) {
+        throw new Error('The report must be an array of { contentHash, targetVersion, completedFiles: [], unchecked: [{ id, reason }], incompleteFiles: [{ path, reason }] }.');
+    }
+    return raw;
+}
+/**
+ * lint の結果を、この snapshot と現在の内容のものだけ受け入れる。機械確認の組は担当の照合から外すので、古い結果を使うと
+ * 誰も見ていない組が残る。
+ */
+async function readCurrentLint(path, manifest) {
+    const lint = await readJson(path);
+    if (lint.checksSha256 !== manifest.lintChecksSha256) {
+        throw new Error('The lint result was not made from this snapshot. Run lint again.');
+    }
+    const current = await hashFiles(lint.root, Object.keys(lint.files));
+    for (const [file, hash] of Object.entries(lint.files)) {
+        if (current[file] !== hash)
+            throw new Error(`${file} changed after lint. Run lint again.`);
+    }
+    return lint;
+}
+export async function ruleCoverage(args) {
+    const { flags, files } = splitFiles(args);
+    const value = (name) => flagValues(flags, name)[0];
+    const manifestPath = value('--manifest');
+    const targetVersion = value('--target-version');
+    const out = value('--out');
+    if (manifestPath === undefined ||
+        targetVersion === undefined ||
+        out === undefined ||
+        files.length === 0) {
+        throw new Error(`Usage: ${RULE_COVERAGE_COMMAND}`);
+    }
+    const manifest = await verifySnapshot(manifestPath);
+    const lintPath = value('--lint');
+    const lint = lintPath === undefined ? null : await readCurrentLint(lintPath, manifest);
+    const toTarget = (file) => normalize(isAbsolute(file) ? relative(lint?.root ?? process.cwd(), file) : file);
+    const targets = files.map(toTarget);
+    // lint の対象に無いファイルは機械確認にならない。パスの基準がずれると、外した組を誰も見ないまま申告に数えてしまう。
+    const linted = new Set(Object.keys(lint?.files ?? {}).map((file) => normalize(file)));
+    const outside = lint === null ? undefined : targets.find((file) => !linted.has(file));
+    if (outside !== undefined) {
+        throw new Error(`${outside} is not in the lint result. Run lint again with the same files.`);
+    }
+    const reports = await Promise.all(flagValues(flags, '--report').map(async (path) => parseReports(await readJson(path))));
+    const coverage = classifyCoverage({
+        manifest,
+        targetVersion,
+        files: targets,
+        lint,
+        reports: reports.flat().map((report) => ({
+            ...report,
+            completedFiles: report.completedFiles.map(toTarget),
+            incompleteFiles: report.incompleteFiles.map((file) => ({
+                ...file,
+                path: toTarget(file.path),
+            })),
+        })),
+    });
+    await writeFile(out, `${JSON.stringify(coverage, null, 1)}\n`);
+    console.log(`Shinaps rule coverage: ${JSON.stringify(coverage.counts)} → ${out}`);
+}

package/dist/lib/rule-snapshot.js

@@ -0,0 +1,261 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { flagValues } from "./args.js";
+import { errorMessage, readJson, sha256 } from "./fs.js";
+export const RULE_SNAPSHOT_COMMAND = 'shinaps-skills rule-snapshot --since <epoch-ms> --input <search-input.json> [--input ...] [--exclude-label <slug> ...] [--captures <dir>] --out <dir>';
+// Codex の担当のファイル読取りが切り詰められない大きさ（モックのモデルで 8KB は全文が届き、18KB は切り詰められた）。
+// 1 件で超える規約は 1 件だけの part にし、行範囲で読めるよう整形する。
+const PART_MAX_BYTES = 8000;
+const CAPTURE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([key, item]) => [key, canonical(item)]));
+}
+const inputKey = ({ cursor: _cursor, ...rest }) => JSON.stringify(canonical(rest));
+const isRule = (value) => isRecord(value) && typeof value.id === 'string';
+const isPage = (value) => isRecord(value) &&
+    Array.isArray(value.userRules) &&
+    value.userRules.every(isRule) &&
+    Array.isArray(value.officialRules) &&
+    value.officialRules.every(isRule) &&
+    'nextCursor' in value;
+/** 応答の本文からページを取り出す。切り詰めやエラーの応答はページの形にならないので null になる。 */
+function parsePage(response) {
+    const content = isRecord(response) ? response.content : response;
+    if (!Array.isArray(content))
+        return null;
+    const text = content.map((item) => (isRecord(item) ? item.text : '')).join('');
+    let page;
+    try {
+        page = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    return isPage(page) ? page : null;
+}
+/**
+ * 捕捉の形式: plugin の hook が PostToolUse の標準入力の全体を
+ * `<captures>/<session>/<時刻 ms>-<tool_use_id>.json` に書いたもの。使う項目は tool_input と tool_response で、
+ * tool_response は Claude Code では content の配列、Codex では `{ content }`。
+ * @param session 捕捉の session のディレクトリ名
+ * @param name 捕捉のファイル名（先頭が時刻 ms）
+ * @param text 捕捉のファイルの内容
+ */
+function parseCapture(session, name, text) {
+    const event = JSON.parse(text);
+    const time = Number.parseInt(name, 10);
+    if (!isRecord(event) || !isRecord(event.tool_input) || Number.isNaN(time))
+        return null;
+    return { session, time, name, input: event.tool_input, page: parsePage(event.tool_response) };
+}
+export async function readCaptures(root) {
+    if (!existsSync(root))
+        return [];
+    const captures = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const session = entry.name;
+        for (const name of await readdir(join(root, session))) {
+            if (!name.endsWith('.json'))
+                continue;
+            const capture = parseCapture(session, name, await readFile(join(root, session, name), 'utf8'));
+            if (capture !== null)
+                captures.push(capture);
+        }
+    }
+    return captures.sort((a, b) => a.time - b.time || (a.name < b.name ? -1 : 1));
+}
+/**
+ * since 以降で最新の先頭ページから nextCursor null まで辿る。古い連鎖へは戻らない。戻ると、hook が止まった後や
+ * 取り直しが途中で止まった後に、以前の規約で成功してしまうため。
+ * @param captures 時刻の昇順の捕捉
+ * @param input cursor を含まない search_rules の入力
+ * @param since この時刻 (epoch ms) より前の捕捉を使わない
+ */
+function walkChain(captures, input, since) {
+    const key = inputKey(input);
+    const matching = captures.filter((row) => row.time >= since && inputKey(row.input) === key);
+    const first = matching.findLast((row) => row.input.cursor === undefined);
+    if (first === undefined) {
+        throw new Error(`No captured response since ${since} for ${key}. Check that the Shinaps hook is enabled and trusted, that this command runs in the same Git root as the fetch (or pass --captures), and that --input is the exact input of the fetch. Then fetch again from the first page.`);
+    }
+    const sessionRows = matching.filter((row) => row.session === first.session);
+    const pages = [];
+    let currentIndex = sessionRows.indexOf(first);
+    for (;;) {
+        const { page } = sessionRows[currentIndex];
+        if (page === null) {
+            throw new Error(`Incomplete chain: unusable response for ${key}. Fetch again from the first page.`);
+        }
+        pages.push(page);
+        if (page.nextCursor === null)
+            return pages;
+        const after = currentIndex;
+        const nextIndex = sessionRows.findIndex((row, index) => index > after && row.input.cursor === page.nextCursor && row.page !== null);
+        if (nextIndex === -1) {
+            throw new Error(`Incomplete chain: missing cursor ${page.nextCursor} for ${key}. Fetch again from the first page.`);
+        }
+        currentIndex = nextIndex;
+    }
+}
+/**
+ * @param source.captures 時刻の昇順の捕捉
+ * @param source.inputs search_rules の入力。複数のときは id の和を取る
+ * @param source.since この時刻 (epoch ms) より前の捕捉を使わない
+ * @param source.excludeLabels これらの label を持つ規約を除外する（理由を残す）
+ */
+export function buildSnapshot(source) {
+    const byId = new Map();
+    for (const input of source.inputs) {
+        for (const page of walkChain(source.captures, input, source.since)) {
+            for (const rule of [...page.userRules, ...page.officialRules]) {
+                const seen = byId.get(rule.id);
+                if (seen !== undefined && !isDeepStrictEqual(seen, rule)) {
+                    throw new Error(`Rule ${rule.id} was captured with different content. Fetch again.`);
+                }
+                byId.set(rule.id, rule);
+            }
+        }
+    }
+    const rules = [];
+    const excluded = [];
+    for (const rule of [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : 1))) {
+        const label = rule.labels?.find((slug) => source.excludeLabels?.includes(slug) === true);
+        if (label === undefined)
+            rules.push(rule);
+        else
+            excluded.push({ id: rule.id, reason: `label ${label} is on an empty axis` });
+    }
+    return { rules, excluded };
+}
+const partText = (rules) => `${JSON.stringify(rules, null, 1)}\n`;
+const checksText = (rules) => `${JSON.stringify({ rules: rules.filter((rule) => (rule.checks?.length ?? 0) > 0).map((rule) => ({ id: rule.id, checks: rule.checks })) }, null, 1)}\n`;
+const contentHashOf = (rules) => sha256(JSON.stringify(canonical(rules)));
+export function splitParts(rules) {
+    const parts = [];
+    for (const rule of rules) {
+        const last = parts.at(-1);
+        if (last !== undefined && Buffer.byteLength(partText([...last, rule])) <= PART_MAX_BYTES) {
+            last.push(rule);
+        }
+        else {
+            parts.push([rule]);
+        }
+    }
+    return parts;
+}
+/**
+ * @param snapshot buildSnapshot の結果
+ * @param inputs manifest に残す search_rules の入力
+ * @param out 出力先のディレクトリ
+ */
+export async function writeSnapshot(snapshot, inputs, out) {
+    await rm(join(out, 'parts'), { recursive: true, force: true });
+    await mkdir(join(out, 'parts'), { recursive: true });
+    const parts = [];
+    for (const [index, rules] of splitParts(snapshot.rules).entries()) {
+        const file = `parts/part-${String(index + 1).padStart(3, '0')}.json`;
+        const text = partText(rules);
+        await writeFile(join(out, file), text);
+        parts.push({ file, sha256: sha256(text) });
+    }
+    const lintChecks = checksText(snapshot.rules);
+    await writeFile(join(out, 'lint-checks.json'), lintChecks);
+    const manifest = {
+        contentHash: contentHashOf(snapshot.rules),
+        inputs,
+        ruleIds: snapshot.rules.map((rule) => rule.id),
+        excluded: snapshot.excluded,
+        parts,
+        lintChecksSha256: sha256(lintChecks),
+    };
+    await writeFile(join(out, 'manifest.json'), `${JSON.stringify(manifest, null, 1)}\n`);
+    return manifest;
+}
+/** snapshot のファイルが作成時から変わっていないことを確かめ、manifest を返す。 */
+export async function verifySnapshot(manifestPath) {
+    const directory = dirname(manifestPath);
+    const manifest = await readJson(manifestPath);
+    const rules = [];
+    for (const part of manifest.parts) {
+        const text = await readFile(join(directory, part.file), 'utf8');
+        if (sha256(text) !== part.sha256)
+            throw new Error(`Snapshot part changed: ${part.file}. Run rule-snapshot again.`);
+        const partRules = JSON.parse(text);
+        if (!Array.isArray(partRules))
+            throw new Error(`Snapshot part is not a list: ${part.file}. Run rule-snapshot again.`);
+        rules.push(...partRules);
+    }
+    if (contentHashOf(rules) !== manifest.contentHash)
+        throw new Error('Snapshot content changed. Run rule-snapshot again.');
+    if (!isDeepStrictEqual(rules.map((rule) => rule.id), manifest.ruleIds)) {
+        throw new Error('manifest.json ruleIds do not match the parts. Run rule-snapshot again.');
+    }
+    const checks = await readFile(join(directory, 'lint-checks.json'), 'utf8');
+    if (sha256(checks) !== manifest.lintChecksSha256)
+        throw new Error('lint-checks.json changed. Run rule-snapshot again.');
+    return manifest;
+}
+/** 24 時間より古い捕捉だけを消す。他の session の取得中の捕捉は残す。 */
+async function removeOldCaptures(root, now) {
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const directory = join(root, entry.name);
+        for (const name of await readdir(directory)) {
+            if (now - Number.parseInt(name, 10) > CAPTURE_MAX_AGE_MS)
+                await rm(join(directory, name), { force: true });
+        }
+        if ((await readdir(directory)).length === 0)
+            await rm(directory, { recursive: true, force: true });
+    }
+}
+// plugin の hook は依存なしで動かすため同じ処理を持つ。同じ保存先になることは test/rule-snapshot.test.ts の通しの試験が確かめる。
+function projectRoot(cwd) {
+    for (let directory = cwd;; directory = dirname(directory)) {
+        if (existsSync(join(directory, '.git')))
+            return directory;
+        if (dirname(directory) === directory)
+            return cwd;
+    }
+}
+export async function ruleSnapshot(args) {
+    const since = Number(flagValues(args, '--since')[0]);
+    const inputPaths = flagValues(args, '--input');
+    const out = flagValues(args, '--out')[0];
+    if (!Number.isFinite(since) || inputPaths.length === 0 || out === undefined) {
+        throw new Error(`Usage: ${RULE_SNAPSHOT_COMMAND}`);
+    }
+    const rawInputs = await Promise.all(inputPaths.map((path) => readJson(path)));
+    const inputs = rawInputs.filter(isRecord);
+    if (inputs.length !== rawInputs.length || inputs.some((input) => input.fields !== 'full')) {
+        throw new Error(`--input must be an object with fields "full": ${JSON.stringify(rawInputs)}`);
+    }
+    const root = flagValues(args, '--captures')[0] ??
+        join(projectRoot(process.cwd()), '.shinaps/work/rule-captures');
+    let snapshot;
+    try {
+        snapshot = buildSnapshot({
+            captures: await readCaptures(root),
+            inputs,
+            since,
+            excludeLabels: flagValues(args, '--exclude-label'),
+        });
+    }
+    catch (error) {
+        throw new Error(`${errorMessage(error)} Captures: ${root}`, { cause: error });
+    }
+    const manifest = await writeSnapshot(snapshot, inputs, resolve(out));
+    await removeOldCaptures(root, Date.now());
+    console.log(`Shinaps rule snapshot: ${manifest.ruleIds.length} rules, ${manifest.excluded.length} excluded, ${manifest.parts.length} parts, contentHash ${manifest.contentHash} → ${out}`);
+}