@shinaps/skills 0.43.0 → 0.45.0

package/dist/lib/managed-session.js

@@ -1,9 +1,10 @@
 import { createHash, 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 { withLock } from './lock.js';
-import { filesBeta, managedBeta } from './managed-ant.js';
+import { readJson, readJsonIfExists, writeFileAtomic } from "./fs.js";
+import { withLock } from "./lock.js";
+import { filesBeta, managedBeta } from "./managed-ant.js";
+import { importSnapshot } from "./managed-snapshot.js";
 export const staffings = ['LITE', 'BASIC', 'ULTRA'];
 export const permissions = ['commit', 'push', 'draft_pr'];
 const leadKey = './agents/shinaps-dev-managed-cc.md';
@@ -64,27 +65,28 @@ export async function runSession(account, request, options) {
         };
         // 作成より前に記録する。作成後に記録できずに終わっても、次の実行は止まり、重複して作らない。
         await writeFileAtomic(recordPath, JSON.stringify(record, null, 2) + '\n');
-        const resources = [
-            {
-                type: 'github_repository',
-                url: request.repository.url,
-                mount_path: request.repository.mount_path,
-                ...(options.githubToken ? { authorization_token: options.githubToken } : {}),
-                checkout: { type: 'commit', sha: request.base_sha },
-            },
-        ];
-        if (options.claudeMdPath) {
-            // upload は記録の後に行う。記録の前だと、途中で止まった実行の再実行のたびに Files が増える。
-            let fileId;
+        const resources = request.snapshot
+            ? []
+            : [
+                {
+                    type: 'github_repository',
+                    url: request.repository.url,
+                    mount_path: request.repository.mount_path,
+                    ...(options.githubToken ? { authorization_token: options.githubToken } : {}),
+                    checkout: { type: 'commit', sha: request.base_sha },
+                },
+            ];
+        // upload は記録の後に行う。記録の前だと、途中で止まった実行の再実行のたびに Files が増える。
+        const upload = async (file, mountPath) => {
             try {
-                fileId = await readId(ant({
+                const fileId = await readId(ant({
                     // セッションの Files と同じ beta の Files API に上げる。パスは絶対パスにする (ant は `-` を
                     // stdin と解釈する)。
                     argv: [
                         'beta:files',
                         'upload',
                         '--file',
-                        resolve(options.claudeMdPath),
+                        resolve(file),
                         ...filesBeta,
                         '--transform',
                         'id',
@@ -92,14 +94,18 @@ export async function runSession(account, request, options) {
                     ],
                     apiKey: account.apiKey,
                 }), 'ant files upload');
+                resources.push({ type: 'file', file_id: fileId, mount_path: mountPath });
             }
             catch (error) {
                 // セッションはまだ作っていないので、記録を残すと同じ依頼の再実行が不要に止まる。
                 await rm(recordPath, { force: true });
                 throw error;
             }
-            resources.push({ type: 'file', file_id: fileId, mount_path: '/CLAUDE.md' });
-        }
+        };
+        if (request.snapshot)
+            await upload(request.snapshot.bundle, '/source.bundle');
+        if (options.claudeMdPath)
+            await upload(options.claudeMdPath, '/CLAUDE.md');
         const body = {
             agent,
             environment_id: environment,
@@ -140,6 +146,16 @@ function initialMessage(request) {
         `必須検証（任意）: ${request.verify ?? '指定なし。リポジトリの規約に従う'}`,
         `author（任意）: ${request.author ?? '指定なし'}`,
         ...(request.claude_md === null ? [] : ['利用者 CLAUDE.md: /mnt/session/uploads/CLAUDE.md']),
+        ...(request.snapshot
+            ? [
+                'ローカルコードの受け渡し: GitHubのcheckoutの代わりに /mnt/session/uploads/source.bundle を使用する。',
+                `作業前に git clone /mnt/session/uploads/source.bundle ${JSON.stringify(request.repository.mount_path)} を実行する。`,
+                `比較元は送信時点のスナップショット ${request.snapshot.id}。このSHAからheadブランチを作り作業する。`,
+                'このスナップショットには元のGit履歴・remote・資格情報は含まれない。pushとPRは行わない。',
+                `完了時はlaunch.mdの一時indexによる出力手順に従い、新規ファイルを含む ${request.snapshot.id} からの全差分を /mnt/session/outputs/changes.patch に書く。`,
+                '変更内容・検証結果・未完了事項を /mnt/session/outputs/report.md に書き、ローカルで再開できるようにする。',
+            ]
+            : []),
     ].join('\n');
 }
 /**
@@ -152,10 +168,17 @@ async function requireRecordedSession(account, sessionId) {
     for (const name of names.filter((entry) => entry.endsWith('.json'))) {
         const record = await readJson(join(directory, name));
         if (record.session_id === sessionId)
-            return;
+            return record;
     }
     throw new Error(`Session ${sessionId} was not created by managed run for account ${account.name}.`);
 }
+/** 回収済みのローカル snapshot のセッションを、APIキーを使わずに新しいディレクトリへ復元する。 */
+export async function importSession(account, sessionId, destination) {
+    const record = await requireRecordedSession(account, sessionId);
+    if (!record.request.snapshot)
+        throw new Error('This session did not use a local snapshot.');
+    return importSnapshot(record.request.snapshot, join(account.dir, 'sessions', sessionId, 'outputs', 'changes.patch'), destination);
+}
 /** セッションの状態と、lead の最後のメッセージ (1 行目が `状態: 完了|質問|未完了`) を返す。 */
 export async function sessionStatus(account, sessionId, ant) {
     await requireRecordedSession(account, sessionId);

package/dist/lib/managed-setup.js

@@ -1,10 +1,10 @@
 import { createHash } from 'node:crypto';
 import { lstat, mkdir, readdir, readFile, rm } from 'node:fs/promises';
 import { dirname, join, relative, sep } from 'node:path';
-import { errorCode, readJsonIfExists, readTextIfExists, writeFileAtomic } from './fs.js';
-import { withLock } from './lock.js';
-import { managedTemplatePath } from './layout.js';
-import { managedBeta } from './managed-ant.js';
+import { errorCode, readJsonIfExists, readTextIfExists, writeFileAtomic } from "./fs.js";
+import { withLock } from "./lock.js";
+import { managedTemplatePath } from "./layout.js";
+import { managedBeta } from "./managed-ant.js";
 /** 共通定義の 3 ディレクトリ。`definitions/` には、これと `claude-lock.json` 以外を置かない。 */
 const definitionDirs = ['agents', 'environments', 'skills'];
 const lockName = 'claude-lock.json';

package/dist/lib/managed-snapshot.js

@@ -0,0 +1,175 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { copyFile, lstat, mkdir, mkdtemp, readFile, readlink, realpath, rename, rm, symlink, chmod, } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { readJson, writeFileAtomic } from "./fs.js";
+const execute = promisify(execFile);
+// 呼び出し元の index の上書き・hooks・filter・署名を snapshot に持ち込まない。
+async function git(cwd, args, configuration = 'snapshot') {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_') || (configuration === 'source' && key.startsWith('GIT_CONFIG_'))));
+    const { stdout } = await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.autocrlf=false', ...args], {
+        cwd,
+        maxBuffer: 32 * 1024 * 1024,
+        env: {
+            ...env,
+            ...(configuration === 'snapshot'
+                ? { GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' }
+                : {}),
+            GIT_AUTHOR_NAME: 'Managed Snapshot',
+            GIT_AUTHOR_EMAIL: 'snapshot@example.invalid',
+            GIT_COMMITTER_NAME: 'Managed Snapshot',
+            GIT_COMMITTER_EMAIL: 'snapshot@example.invalid',
+            GIT_AUTHOR_DATE: '2000-01-01T00:00:00Z',
+            GIT_COMMITTER_DATE: '2000-01-01T00:00:00Z',
+        },
+    });
+    return stdout;
+}
+/**
+ * 元の index を変えずに、現在のソースのファイルを1コミットだけの独立したリポジトリへ固定する。
+ * @param source Git の checkout のルート。未コミットの変更と、無視されていない新規ファイルを含めて送る。
+ * @param root checkout の外にある、snapshot の非公開の保存先。
+ */
+export async function prepareSnapshot(source, root) {
+    source = await realpath(source);
+    const top = (await git(source, ['rev-parse', '--show-toplevel'], 'source')).trim();
+    if ((await realpath(top)) !== source)
+        throw new Error('Snapshot source must be the Git checkout root.');
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    root = await realpath(root);
+    if (root === source || root.startsWith(source + sep))
+        throw new Error('Snapshot storage must be outside the source checkout.');
+    const temporary = await mkdtemp(join(root, '.snapshot-'));
+    try {
+        const repository = join(temporary, 'repository');
+        await mkdir(repository);
+        // 方式を固定する。git の既定が変わっても、readSnapshot が受け付ける 40 桁の id にする。
+        await git(repository, ['init', '--object-format=sha1', '--initial-branch=snapshot']);
+        const candidates = [
+            ...new Set((await git(source, ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], 'source'))
+                .split('\0')
+                .filter(Boolean)),
+        ].sort();
+        const files = [];
+        for (const name of candidates) {
+            // ローカルの運用状態・資格情報・Git の内部・生成された依存物は送らない。
+            const parts = name.split('/');
+            if (parts.some((part) => ['.git', '.shinaps', 'node_modules', '.local'].includes(part)))
+                continue;
+            if (parts.some((part) => /^\.env(?:\.|$)/.test(part) && !/\.(example|sample|template)$/.test(part)) ||
+                /\.(pem|p12|pfx|key)$/i.test(name)) {
+                throw new Error(`Remove credential file from the snapshot source before sending: ${name}`);
+            }
+            const input = join(source, name);
+            let info;
+            try {
+                info = await lstat(input);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            if (!info.isFile() && !info.isSymbolicLink())
+                throw new Error(`Snapshot does not support directories or submodules as files: ${name}`);
+            // 親ディレクトリも確かめる。途中のディレクトリを差し替えると、checkout 外のファイルを読めてしまう。
+            const parent = await realpath(dirname(input));
+            if (parent !== source && !parent.startsWith(source + sep))
+                throw new Error(`Snapshot path leaves the source checkout: ${name}`);
+            const output = join(repository, name);
+            await mkdir(dirname(output), { recursive: true });
+            if (info.isSymbolicLink()) {
+                const target = await readlink(input);
+                const destination = resolve(dirname(input), target);
+                if (target.startsWith('/') ||
+                    (destination !== source && !destination.startsWith(source + sep)))
+                    throw new Error(`Snapshot symlink leaves the source checkout: ${name}`);
+                await symlink(target, output);
+            }
+            else {
+                await copyFile(input, output);
+                await chmod(output, info.mode & 0o111 ? 0o755 : 0o644);
+            }
+            files.push(name);
+        }
+        await git(repository, ['add', '--all', '--force']);
+        await git(repository, [
+            '-c',
+            'commit.gpgsign=false',
+            'commit',
+            '--allow-empty',
+            '-m',
+            'Local source snapshot',
+        ]);
+        const id = (await git(repository, ['rev-parse', 'HEAD'])).trim();
+        const directory = join(root, id);
+        await git(repository, ['bundle', 'create', join(temporary, 'source.bundle'), 'HEAD']);
+        const snapshot = {
+            id,
+            source,
+            directory,
+            bundle: join(directory, 'source.bundle'),
+            files,
+        };
+        await writeFileAtomic(join(temporary, 'snapshot.json'), JSON.stringify(snapshot, null, 2) + '\n');
+        try {
+            await rename(temporary, directory);
+        }
+        catch (error) {
+            if (!['EEXIST', 'ENOTEMPTY'].includes(error.code ?? ''))
+                throw error;
+            // 同じ内容は別の checkout からも作られうるが、比較元としては同じ tree である。
+            return readSnapshot(join(directory, 'snapshot.json'));
+        }
+        return snapshot;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+/**
+ * prepare が書いた manifest だけを受け付ける。id は git の引数と lead への指示文に、bundle は upload に
+ * 使うので、別のファイルを渡された場合にそのまま使わない。
+ * @param manifest prepare が出力した `snapshot.json` のパス。
+ */
+export async function readSnapshot(manifest) {
+    const { id, source, directory, bundle, files } = (await readJson(manifest)) ?? {};
+    if (typeof id !== 'string' ||
+        !/^[0-9a-f]{40}$/.test(id) ||
+        typeof source !== 'string' ||
+        typeof directory !== 'string' ||
+        !isAbsolute(directory) ||
+        bundle !== join(directory, 'source.bundle') ||
+        !Array.isArray(files) ||
+        !files.every((file) => typeof file === 'string'))
+        throw new Error(`Not a snapshot manifest written by managed prepare: ${manifest}`);
+    return { id, source, directory, bundle, files };
+}
+/**
+ * 比較元と差分を新しいディレクトリに復元する。元の checkout は変更しない。
+ * @param snapshot リモートのセッションが使った、保存済みの比較元。
+ * @param patch 回収した lead の差分。比較元からの全体の差分。
+ * @param destination 復元先の新しいディレクトリ。既に存在してはいけない。
+ */
+export async function importSnapshot(snapshot, patch, destination) {
+    destination = resolve(destination);
+    await mkdir(destination, { mode: 0o700 });
+    try {
+        await git(destination, [
+            'clone',
+            '--no-local',
+            '--',
+            join(snapshot.directory, 'repository'),
+            '.',
+        ]);
+        await git(destination, ['checkout', '--detach', snapshot.id]);
+        const content = await readFile(patch);
+        if (content.length)
+            await git(destination, ['apply', '--index', '--', resolve(patch)]);
+        return destination;
+    }
+    catch (error) {
+        await rm(destination, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/lib/managed.js

@@ -1,21 +1,26 @@
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { errorMessage } from './fs.js';
-import { managedAccountDir, managedRoot, packageRoot } from './layout.js';
-import { antCommand } from './managed-ant.js';
-import { validateManagedConfig } from './managed-config.js';
-import { collectOutputs, permissions, replySession, runSession, sessionStatus, staffings, } from './managed-session.js';
-import { setupAccount } from './managed-setup.js';
+import { join } from 'node:path';
+import { errorMessage } from "./fs.js";
+import { managedAccountDir, managedRoot, packageRoot } from "./layout.js";
+import { antCommand } from "./managed-ant.js";
+import { validateManagedConfig } from "./managed-config.js";
+import { collectOutputs, importSession, permissions, replySession, runSession, sessionStatus, staffings, } from "./managed-session.js";
+import { setupAccount } from "./managed-setup.js";
+import { prepareSnapshot, readSnapshot } from "./managed-snapshot.js";
 const managedUsage = [
     'Usage: shinaps-skills managed setup --account <name> [--account <name> ...] [--apply]',
-    '       shinaps-skills managed run <managed.json> --account <name> --base <branch> --base-sha <sha> --head <branch> --staffing <LITE|BASIC|ULTRA> --allow <none|commit,push,draft_pr> --budget-cents <n> --task-file <file> [--verify <command>] [--author "<name> <email>"] [--title <title>] [--claude-md <file>]',
+    '       shinaps-skills managed run <managed.json> --account <name> --base <branch> (--base-sha <sha> | --snapshot <manifest>) --head <branch> --staffing <LITE|BASIC|ULTRA> --allow <none|commit,push,draft_pr> --budget-cents <n> --task-file <file> [--verify <command>] [--author "<name> <email>"] [--title <title>] [--claude-md <file>]',
     '       shinaps-skills managed status --account <name> --session <id>',
     '       shinaps-skills managed reply --account <name> --session <id> --message-file <file>',
     '       shinaps-skills managed collect --account <name> --session <id>',
+    '       shinaps-skills managed prepare --source <local-checkout-root>',
+    '       shinaps-skills managed import --account <name> --session <id> --destination <new-directory>',
     'API keys: --api-key <name>=<key>, or SHINAPS_MANAGED_API_KEY_<NAME> (prefer the environment variable; arguments are visible to other processes).',
     'GitHub token for the mounted repository: SHINAPS_MANAGED_GITHUB_TOKEN.',
+    'Local source: prepare lists the frozen files and manifest; pass --snapshot <manifest> to run instead of --base-sha. Local snapshots do not push or create PRs.',
 ].join('\n');
-const accountName = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const accountName = /^[a-z0-9][a-z0-9-]*$/;
 const githubTokenVariable = 'SHINAPS_MANAGED_GITHUB_TOKEN';
 const valueFlags = new Set([
     'account',
@@ -33,12 +38,15 @@ const valueFlags = new Set([
     'claude-md',
     'session',
     'message-file',
+    'source',
+    'snapshot',
+    'destination',
 ]);
 const repeatableFlags = new Set(['account', 'api-key']);
 /** アカウント名ごとのキーの環境変数名。名前に `_` を許さないので、名前と一対一に対応する。 */
 const apiKeyVariable = (account) => `SHINAPS_MANAGED_API_KEY_${account.toUpperCase().replaceAll('-', '_')}`;
 /**
- * `shinaps-skills managed <setup|run|status|reply|collect>` を実行する。出力とエラー文から、渡された
+ * `shinaps-skills managed <setup|run|status|reply|collect|prepare|import>` を実行する。出力とエラー文から、渡された
  * APIキーと GitHub token の値を伏字にする。
  */
 export async function managed(args, options = {}) {
@@ -74,6 +82,25 @@ async function dispatch(args, context) {
     const home = context.home ?? homedir();
     const ant = context.ant ?? antCommand(context.env);
     const accounts = flags.get('account') ?? [];
+    if (command === 'prepare') {
+        if (apply || positional.length || accounts.length)
+            throw usageError();
+        const snapshot = await prepareSnapshot(required(flags, 'source'), join(managedRoot(home), 'snapshots'));
+        context.log(JSON.stringify({ ...snapshot, manifest: join(snapshot.directory, 'snapshot.json') }, null, 2));
+        return;
+    }
+    if (command === 'import') {
+        if (apply || positional.length || accounts.length !== 1 || !accountName.test(accounts[0]))
+            throw usageError();
+        const account = { name: accounts[0], dir: managedAccountDir(managedRoot(home), accounts[0]) };
+        const sessionId = required(flags, 'session');
+        context.log(JSON.stringify({
+            account: account.name,
+            session_id: sessionId,
+            directory: await importSession(account, sessionId, required(flags, 'destination')),
+        }, null, 2));
+        return;
+    }
     if (command === 'setup') {
         if (positional.length || !accounts.length)
             throw usageError();
@@ -164,12 +191,19 @@ async function run(configPath, account, flags, context, ant) {
     }
     const optional = (flag) => flags.get(flag)?.[0] ?? null;
     const claudeMdPath = optional('claude-md');
+    const snapshotPath = optional('snapshot');
+    if (snapshotPath && flags.has('base-sha'))
+        throw new Error('Use either --base-sha or --snapshot.');
+    const snapshot = snapshotPath ? await readSnapshot(snapshotPath) : undefined;
+    if (snapshot && (allow.includes('push') || allow.includes('draft_pr'))) {
+        throw new Error('Local snapshots support local result recovery; push and draft_pr are not available.');
+    }
     const request = {
         account: account.name,
         repository: config.repository,
         vault_id: settings.vault_id,
         base: required(flags, 'base'),
-        base_sha: required(flags, 'base-sha'),
+        base_sha: snapshot?.id ?? required(flags, 'base-sha'),
         head: required(flags, 'head'),
         staffing: staffing,
         allow,
@@ -179,6 +213,7 @@ async function run(configPath, account, flags, context, ant) {
         author: optional('author'),
         title: optional('title'),
         claude_md: claudeMdPath === null ? null : await readFile(claudeMdPath, 'utf8'),
+        ...(snapshot ? { snapshot } : {}),
     };
     const sessionId = await runSession(account, request, {
         ant,
@@ -188,6 +223,7 @@ async function run(configPath, account, flags, context, ant) {
         now: context.now ?? (() => new Date()),
     });
     context.log(`Observe: shinaps-skills managed status --account ${account.name} --session ${sessionId}`);
+    context.log(JSON.stringify({ account: account.name, session_id: sessionId }));
 }
 function resolveAccounts(names, flags, env, home) {
     const keys = new Map();
@@ -200,7 +236,7 @@ function resolveAccounts(names, flags, env, home) {
     const unique = [...new Set(names)];
     const invalid = unique.filter((name) => !accountName.test(name));
     if (invalid.length) {
-        throw new Error(`Invalid account name: ${invalid.join(', ')}. Use lowercase letters, digits and single hyphens.`);
+        throw new Error(`Invalid account name: ${invalid.join(', ')}. Use lowercase letters, digits and hyphens, starting with a letter or digit.`);
     }
     const missing = unique.filter((name) => !(keys.get(name) || env[apiKeyVariable(name)]));
     if (missing.length) {

package/dist/lib/transaction.js

@@ -1,8 +1,8 @@
 import { mkdir, rm, rename, cp } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
-import { managedAgent, marketplaceName, payloadDir, pluginId, statePath } from './layout.js';
-import { errorCode, errorMessage, readJsonIfExists, readTextIfExists, writeFileAtomic, } from './fs.js';
+import { managedAgent, marketplaceName, payloadDir, pluginId, statePath } from "./layout.js";
+import { errorCode, errorMessage, readJsonIfExists, readTextIfExists, writeFileAtomic, } from "./fs.js";
 /** エージェント内容の sha256。state.json と journal の `nextHashes` はこの形式で記録する。 */
 export const digest = (text) => createHash('sha256').update(text).digest('hex');
 /** 配布物を Codex に登録する。install と restore で同じ手順を使う。 */

package/docs/development.md

@@ -7,7 +7,7 @@
 - Claude 版: `plugins/shinaps-claude/`、marketplace は `.claude-plugin/marketplace.json`
 - Codex 版: `plugins/shinaps-codex/`、marketplace は `.agents/plugins/marketplace.json`。サブエージェントは `plugins/shinaps-codex/agents/`
 - Claude Managed Agents 版: 両 plugin の `managed-agents/`。plugin と一緒に配布され、npm パッケージの `plugins/` にも含まれる
-- 配布 CLI: ソースは `bin/skills.ts` と `lib/*.ts`。`npm run build`（`tsc`）で `dist/` に JS を出力し、npm にはそれを配布する。Node.js は `node_modules` 配下の `.ts` に型除去を適用しないため、ソースのままは配布できない。checkout では型除去で直接実行するので、`enum` など型除去で消せない構文は使わない（`tsconfig.json` の `erasableSyntaxOnly`）
+- 配布 CLI: ソースは `bin/skills.ts` と `lib/*.ts`。規約の機械検査（`lint`）は ESLint の Node API を使い、仕組みと同梱ルールの追加手順は [規約の機械検査](lint.md) にある。TypeScript は typescript-eslint が対応する 6 系を実行時の依存に持ち、開発用の `tsc` も同じ版を使う（typescript-eslint が 7 に対応したら上げる）。`npm run build`（`tsc`）で `dist/` に JS を出力し、npm にはそれを配布する。Node.js は `node_modules` 配下の `.ts` に型除去を適用しないため、ソースのままは配布できない。checkout では型除去で直接実行するので、`enum` など型除去で消せない構文は使わない（`tsconfig.json` の `erasableSyntaxOnly`）
 
 品質基準とプロジェクト設定の方針は両版で揃え、クライアント固有の実行手順とエージェントの形式は別々に管理する。スキルを追加・変更したら各版への適用可否を判断する。
 

package/docs/install.md

@@ -4,7 +4,7 @@ Claude Code 版の更新と、Codex 版の導入・更新・削除・macOS で
 
 ## 導入・更新・削除
 
-Node.js 22 以上と、`plugin marketplace add` / `plugin add` に対応した Codex CLI が必要です。Codex のスキルだけを使う場合、Claude Code のインストールは不要です。
+Node.js 22.13 以上の 22 系または 24 以上と、`plugin marketplace add` / `plugin add` に対応した Codex CLI が必要です。Codex のスキルだけを使う場合、Claude Code のインストールは不要です。
 
 ```sh
 npx @shinaps/skills@latest install codex
@@ -23,10 +23,10 @@ npx @shinaps/skills@latest recover codex
 
 ## 配布 CLI
 
-設定の検証（`validate-linear-config`・`validate-managed-config`）と Managed Agents の操作（`managed`）には、配布 CLI `shinaps-skills` を使います。CLI は plugin に含まれないため、利用中のスキルと同じ版を導入します。
+設定の検証（`validate-linear-config`・`validate-managed-config`）、Managed Agents の操作（`managed`）、規約の機械検査（`lint`、[規約の機械検査](lint.md)）には、配布 CLI `shinaps-skills` を使います。CLI は plugin に含まれないため、利用中のスキルと同じ版を導入します。
 
 ```sh
-npm install -g @shinaps/skills@0.43.0
+npm install -g @shinaps/skills@0.45.0
 shinaps-skills --version
 ```
 

package/docs/lint.md

@@ -0,0 +1,71 @@
+# 規約の機械検査（`shinaps-skills lint`）
+
+Shinaps AIの規約が持つ機械検査（`checks`）を手元で実行し、規約×ファイルの組ごとに、AI照合を省けるかを判定するCLIです。エージェント向けの使い方は plugin の `references/lint.md` にあります。
+
+## 前提と保証
+
+- プロジェクトの変更は要りません。プロジェクトのlint設定（`eslint.config.*`・`.oxlintrc.json`・`bunfig.toml` など）・`package.json` のscript・`node_modules` のパッケージは読み込みません。ESLintのNode APIを `overrideConfigFile: true` で使い、パーサーとプラグインはこのパッケージの依存から渡します。読むのは対象ファイルと、型情報を使うルールのための `tsconfig.json`・型宣言だけです（実行はしません）。
+- 対象ファイルへ書き込みません（自動修正はしません）。結果はローカルのファイルに書き、サーバーへは送りません。
+- プロジェクトの `eslint-disable` コメントでは検査を抑止しません（`allowInlineConfig: false`）。プロジェクトの都合の例外は、指摘を確認する側で扱います。
+- 組をAI照合から外してよいのは、coverage が `full` の検査が、ESLintの判定でそのファイルに適用され、検査の実行単位が完了し、そのファイルに致命的な報告もruleIdの無い報告も無いときだけです。それ以外の組は `not-run`（または `partial`）として返し、合格にしません。coverage は検査を登録したときの判断で、このCLIは値を読むだけです。
+
+## 使い方
+
+```sh
+shinaps-skills lint --checks <checks.json> --root <project> --out <result.json> -- <files...>
+```
+
+- `--checks`・`--out` のパスは、コマンドを実行したディレクトリが基準です。
+- `--checks`: `{ "rules": [{ "id": "<規約id>", "checks": [{ "rule": "...", "options": [...], "files": ["**/*.ts"], "coverage": "full" }] }] }`。形が違えば何も書かずに終了コード1で終わります。
+- `--root`: 対象プロジェクトのルート。ESLintの `cwd` と、結果のパスの基準になります。
+- `<files...>`: 対象ファイル（`--root` からの相対パスか絶対パス）。どの検査も適用されないファイルはESLintに渡しません。渡すファイルが無ければESLintを起動しません（ファイルを省くとESLintはルート配下を全て検査するため）。
+- `--out`: 結果のJSON。
+
+結果:
+
+```json
+{
+  "root": "/path/to/project",
+  "units": [{ "id": "syntax-0", "typed": false, "rules": ["@typescript-eslint/method-signature-style"], "fileCount": 3 }],
+  "pairs": [
+    { "ruleId": "<規約id>", "file": "src/a.ts", "state": "covered", "findings": [] },
+    { "ruleId": "<規約id>", "file": "src/b.ts", "state": "violation", "findings": [{ "rule": "@typescript-eslint/method-signature-style", "line": 2, "column": 3, "message": "..." }] },
+    { "ruleId": "<規約id>", "file": "tests/c.ts", "state": "not-run", "reason": "...", "findings": [] }
+  ]
+}
+```
+
+| state | 意味 | 照合 |
+| --- | --- | --- |
+| `covered` | `full` の検査が実行され、違反が無い | 外す |
+| `violation` | `full` の検査が実行され、指摘がある（同じ規約の `partial` の検査の指摘を含む） | 外し、`findings` を指摘にする |
+| `partial` | `partial` の検査だけが実行された | 残し、`findings` も指摘にする |
+| `not-run` | 実行していない（`reason` に理由） | 残す |
+
+## 実行の仕組み
+
+1. 各検査のルールを、ESLint core・`@typescript-eslint`・`vue`・同梱の `shinaps` から引きます。この版に無いルールの検査は `not-run` になり、他の検査は止まりません。
+2. 検査ごとに、その検査の設定だけを入れたESLintで `calculateConfigForFile` を呼び、ルールが有効なファイルを適用先にします。globの解釈はESLintだけが行います。ESLintが設定を拒否した検査（不正なoptionsなど）は、ここで `not-run` になります。
+3. 同じルール・同じoptionsの検査は1つの設定にまとめ、同じルールでoptionsが違うものだけを別の実行単位にします。型情報を使うルール（`meta.docs.requiresTypeChecking`）は `projectService` を使う単位に分けます。この単位は全てのファイルを typescript-eslint で読み、型の得られないファイル（`tsconfig.json` に含まれないTS・JS、Vue）はそのファイルだけが `not-run` になります。型なしの検査と、他のファイルの型付きの検査は影響を受けません。型情報を使うルールはVueのファイルでは実行できません。
+4. 実行単位ごとに `lintFiles` を1回呼び、組を分類します。指摘は、ESLintがそのファイルに適用すると判定した検査の規約にだけ付けます。
+
+## 同梱ルール
+
+| ルールID | 内容 | 型情報 |
+| --- | --- | --- |
+| `shinaps/prefer-promise-with-resolvers` | Promiseのexecutorが受け取る `resolve`・`reject` を、executorの外で使うために変数・プロパティへ代入する書き方（deferred promise）を報告する。`Promise.withResolvers()` で書ける。包んだ関数の代入や、値として渡す呼び出しは報告しない | 不要 |
+
+### 同梱ルールの追加
+
+規約の検査に既存のルールが使えないとき、レビュー済みでテスト済みのルールをこのパッケージに同梱します。サーバーにはルールのIDとoptionsだけを保存し、コードは配布しません。同梱していないルールは、実装・テスト・レビュー・リリースを経るまで使えません（それまでは、その規約はAI照合のままです）。
+
+1. `lib/lint-rules.ts` にルールを足し、`shinapsPlugin.rules` に登録します。IDは意味を変えずに使い続けます（規約の検査はIDで保存され、登録時の意味のレビューがその挙動を前提にするため）。意味が変わるなら別のIDにします。型情報を使うルールには `meta.docs.requiresTypeChecking: true` を付けます（付けないと型なしの実行単位に入り、その単位の検査が全て `not-run` になります）。
+2. `test/lint.test.ts` に、ESLintの `RuleTester` で報告する例・しない例を書きます。規約の good・bad の例と、誤って報告しやすい形（同じ名前の別の変数など）を含めます。型情報を使わないルールは、型情報なしの `RuleTester` で動くことがそのまま確認になります。型情報を使うルールは、`languageOptions.parserOptions` に `projectService` を付けた `RuleTester` で試します。
+3. この文書の「同梱ルール」の表に追加し、通常の変更と同じくレビュー・リリースします。
+4. 規約に検査を付けるのはリリースの後です。規約の全文を読んで coverage を決めます（plugin の `references/lint.md`）。
+
+実例: `shinaps/prefer-promise-with-resolvers`（`lib/lint-rules.ts`）。右辺の識別子をscopeで解決し、Promiseのexecutorの引数そのものかを確かめることで、内側の関数の同じ名前の引数を取り違えないようにしています。テストは `test/lint.test.ts` の末尾にあります。
+
+## 依存
+
+ESLint・typescript-eslint・TypeScript・vue-eslint-parser・eslint-plugin-vue を完全一致の版で依存に持ちます（パッケージの導入が約50MB増えます）。typescript-eslint は TypeScript 7 に対応していないため、TypeScript は6系です（開発用の `tsc` も同じ版を使います）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shinaps/skills",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Install Shinaps AI workflows and custom agents for Codex",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22"
+    "node": "^22.13.0 || >=24"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -36,10 +36,14 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
-    "@types/node": "^26.6.4",
-    "typescript": "^7.0.2"
+    "@types/node": "^26.6.4"
   },
   "dependencies": {
-    "ajv": "^8.20.0"
+    "ajv": "^8.20.0",
+    "eslint": "10.14.0",
+    "eslint-plugin-vue": "10.12.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.1",
+    "vue-eslint-parser": "10.4.1"
   }
 }

package/plugins/shinaps-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shinaps",
   "description": "Shinaps AIの開発ワークフロー。プロジェクトの指示から条件を読み、調査・設計・実装・簡素化・レビュー・コミット・PR・リリースとLinearでの開発進行を支援する。",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "author": {
     "name": "shinaps"
   },

package/plugins/shinaps-claude/managed-agents/skills/dev-managed-cc/references/launch.md

@@ -71,3 +71,7 @@ PR: <draft PR の URL。無ければ なし>
 | hooks | 未対応 |
 | permission mode | 定義の `permission_policy` で固定 |
 | セッション予算 | セッション作成時の `max_list_cost` で付ける |
+
+## ローカルsnapshotで始める場合
+
+初回メッセージにsource.bundleが指定されている場合は、通常のHEAD確認より先に `/mnt/session/uploads/source.bundle` を指定された作業先へcloneする。比較元は初回メッセージのsnapshot SHAとし、GitHubへのアクセスや元の履歴を前提にしない。成果物は上記の一時indexで比較元からの全差分を出力する手順に従い、変更内容・検証結果・未完了事項を `/mnt/session/outputs/report.md` にも残す。

package/plugins/shinaps-claude/references/linear/configuration.md

@@ -4,7 +4,7 @@
 
 ## 検証CLIと契約版
 
-利用中のskillとCLIの版を確認し、0.43.0のskillには同じ版のnpm CLIを導入する（`npm install -g @shinaps/skills@0.43.0`）。pluginだけにはCLIは含まれない。導入・更新が必要ならその権限を確認し、検証のたびに `npx latest` を取得しない。
+利用中のskillとCLIの版を確認し、0.45.0のskillには同じ版のnpm CLIを導入する（`npm install -g @shinaps/skills@0.45.0`）。pluginだけにはCLIは含まれない。導入・更新が必要ならその権限を確認し、検証のたびに `npx latest` を取得しない。
 
 0.35.0から通常設定の `review_flow.mode` に `ask` を受理する。`config_version` は2のままで、既存のauto・manualの設定は変更不要。0.33.0〜0.34.xのCLIと `$schema` のURLは `ask` を拒否するため、`ask` を使う設定では `$schema` も0.35.0以降のURLにする。