@shinaps/skills 0.37.0 → 0.38.0

package/dist/lib/managed-setup.js

@@ -0,0 +1,167 @@
+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';
+/** 共通定義の 3 ディレクトリ。`definitions/` には、これと `claude-lock.json` 以外を置かない。 */
+const definitionDirs = ['agents', 'environments', 'skills'];
+const lockName = 'claude-lock.json';
+const upToDate = /Everything is up to date\./;
+/**
+ * 1 アカウントへ共通定義を導入・更新する。`apply` が false なら dry-run の計画を表示するだけで、
+ * クラウドを変更しない。`--prune`・`--force` は使わない (リソースを削除・上書きしないため)。
+ * @param source 同梱の共通定義を含むパッケージのルート。
+ * @returns 計画だけを示した (`planned`)、適用した (`applied`)、変更が無かった (`up-to-date`)。
+ */
+export async function setupAccount(account, options) {
+    const { ant, log } = options;
+    const definitions = join(account.dir, 'definitions');
+    // ant は --lock-file が無いと lock を cwd から上へ探す。definitions に lock が無いとき祖先の lock を
+    // 拾うと、別の組織や構成の lock で対応づけてしまうので、definitions 直下の lock を常に指定する
+    // (指定した lock が無ければ ant はそこへ新しく作る。キーは lock のディレクトリ基準で変わらない)。
+    const run = (mode) => ant({
+        argv: ['apply', mode, '--lock-file', lockName, '.'],
+        apiKey: account.apiKey,
+        cwd: definitions,
+    });
+    return withLock(account.dir, async () => {
+        await syncDefinitions(definitions, join(options.source, managedTemplatePath), join(account.dir, 'definitions.json'));
+        if ((await readTextIfExists(join(definitions, lockName))) === null) {
+            await refuseDuplicates(account, definitions, ant);
+        }
+        const plan = await run('--dry-run');
+        log(plan.trimEnd());
+        // dry-run は適用不能な計画でも終了コード 0 で返るので、計画の文言で判定する。
+        if (/This plan cannot be applied/.test(plan)) {
+            throw new Error(`The plan for account ${account.name} cannot be applied. See the plan above.`);
+        }
+        if (upToDate.test(plan))
+            return 'up-to-date';
+        if (!options.apply)
+            return 'planned';
+        log((await run('--yes')).trimEnd());
+        if (!upToDate.test(await run('--dry-run'))) {
+            throw new Error(`Account ${account.name} still has pending changes after apply. Run setup again without --apply to see them.`);
+        }
+        return 'applied';
+    });
+}
+/**
+ * definitions の3ディレクトリを同梱の定義に揃える。書き換え・削除するのは、setup が最後に書いた
+ * 内容 (`definitions.json` の記録) か今回書く内容と一致するファイルだけ。利用者の編集・追加や、
+ * 記録の無い既存ファイル (旧版の定義ごと複写した場合など) があれば、何も変えずに止める。apply は
+ * ディレクトリ内の定義をすべて送るので、利用者の変更を黙って送ることも失うこともしないため。
+ * definitions には同梱の定義だけを置く。利用者の変更は取り込まず、止めて退避してもらう。
+ * 途中で止まった同期は、各ファイルが記録か今回のどちらかに一致するので、再実行で続きから揃う。
+ * @param record 最後に書いたファイルの相対パス → sha256。apply が送らないよう definitions の外に置く。
+ */
+async function syncDefinitions(definitions, template, record) {
+    await mkdir(definitions, { recursive: true });
+    const unexpected = (await readdir(definitions)).filter((name) => name !== lockName && !definitionDirs.includes(name));
+    const current = await hashTree(definitions, unexpected);
+    const next = await hashTree(template, []);
+    const written = (await readJsonIfExists(record)) ?? {};
+    // 無いファイルは変更にしない。同梱の定義を書き直すだけで利用者の内容は失われず、停止して退避を
+    // 求めると、退避した後の再実行も同じ理由で止まり続けるため。
+    const changed = Object.keys(current)
+        .filter((path) => current[path] !== written[path] && current[path] !== next[path])
+        .sort();
+    if (changed.length) {
+        throw new Error(`Files in ${definitions} differ from what setup wrote: ${changed.join(', ')}. Setup does not overwrite, delete or apply them; it applies only the bundled definitions. Move them out of ${definitions} (keep ${lockName}), then retry and review the plan: it reverts cloud resources that were changed to match the bundled definitions.`);
+    }
+    for (const [path, hash] of Object.entries(next)) {
+        if (current[path] === hash)
+            continue;
+        await mkdir(dirname(join(definitions, path)), { recursive: true });
+        await writeFileAtomic(join(definitions, path), await readFile(join(template, path), 'utf8'));
+    }
+    for (const path of Object.keys(current).filter((path) => !(path in next))) {
+        await rm(join(definitions, path));
+    }
+    await removeEmptyDirectories(definitions);
+    await writeFileAtomic(record, JSON.stringify(next, null, 2) + '\n');
+}
+/**
+ * 3ディレクトリ配下の通常ファイルの相対パス → sha256。通常ファイル以外 (シンボリックリンクなど) と
+ * `extra` の項目は、内容を比べられない変更として値を空にする (記録・同梱のどちらとも一致しない)。
+ */
+async function hashTree(root, extra) {
+    const result = Object.fromEntries(extra.map((name) => [name, '']));
+    for (const directory of definitionDirs) {
+        const kind = await lstat(join(root, directory)).catch((error) => {
+            if (errorCode(error) === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!kind)
+            continue;
+        // 3ディレクトリ自体がシンボリックリンクなどなら、辿るとリンク先へ書き込むので変更として止める。
+        if (!kind.isDirectory()) {
+            result[directory] = '';
+            continue;
+        }
+        const entries = await readdir(join(root, directory), { recursive: true, withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                continue;
+            const path = relative(root, join(entry.parentPath, entry.name)).split(sep).join('/');
+            result[path] = entry.isFile()
+                ? createHash('sha256')
+                    .update(await readFile(join(root, path)))
+                    .digest('hex')
+                : '';
+        }
+    }
+    return result;
+}
+// 定義を消した後に残る空のディレクトリを消す。中身の無い skill のディレクトリを apply に渡さないため。
+async function removeEmptyDirectories(definitions) {
+    for (const directory of definitionDirs) {
+        const root = join(definitions, directory);
+        const nested = (await readdir(root, { recursive: true, withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(entry.parentPath, entry.name))
+            .sort((a, b) => b.length - a.length);
+        for (const path of nested) {
+            if ((await readdir(path)).length === 0)
+                await rm(path, { recursive: true });
+        }
+    }
+}
+// lock が無いと apply は既存のリソースと対応づかず、同じ名前で新しく作る。lock の hash は既存の
+// リソースから作り直せないので、同名のリソースがあれば作らずに止め、lock を戻してもらう。
+async function refuseDuplicates(account, definitions, ant) {
+    const names = new Set();
+    for (const directory of ['agents', 'environments']) {
+        for (const file of await readdir(join(definitions, directory))) {
+            const name = (await readFile(join(definitions, directory, file), 'utf8')).match(/^name: (.+)$/m)?.[1];
+            if (name)
+                names.add(name.trim());
+        }
+    }
+    const existing = [];
+    for (const resource of ['beta:agents', 'beta:environments']) {
+        const output = await ant({
+            argv: [
+                resource,
+                'list',
+                ...managedBeta,
+                '--format',
+                'jsonl',
+                '--transform',
+                '{name,archived_at}',
+            ],
+            apiKey: account.apiKey,
+        });
+        for (const line of output.split('\n').filter((text) => text.trim())) {
+            const item = JSON.parse(line);
+            if (item.name && names.has(item.name) && !item.archived_at)
+                existing.push(item.name);
+        }
+    }
+    if (existing.length) {
+        throw new Error(`Account ${account.name} has no lock, but resources with the same names exist: ${[...new Set(existing)].join(', ')}. Applying would create duplicates. If you used Managed Agents before, move the previous claude-lock.json (for example <definitions>/claude-lock.json from .shinaps/managed.json version 1) to ${definitions}/, then retry.`);
+    }
+}

package/dist/lib/managed.js

@@ -0,0 +1,249 @@
+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';
+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 status --account <name> --session <id>',
+    '       shinaps-skills managed reply --account <name> --session <id> --message-file <file>',
+    '       shinaps-skills managed collect --account <name> --session <id>',
+    '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.',
+].join('\n');
+const accountName = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const githubTokenVariable = 'SHINAPS_MANAGED_GITHUB_TOKEN';
+const valueFlags = new Set([
+    'account',
+    'api-key',
+    'base',
+    'base-sha',
+    'head',
+    'staffing',
+    'allow',
+    'budget-cents',
+    'task-file',
+    'verify',
+    'author',
+    'title',
+    'claude-md',
+    'session',
+    'message-file',
+]);
+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>` を実行する。出力とエラー文から、渡された
+ * APIキーと GitHub token の値を伏字にする。
+ */
+export async function managed(args, options = {}) {
+    const env = options.env ?? process.env;
+    const secrets = collectSecrets(args, env);
+    const redact = (text) => secrets.reduce((result, secret) => result.replaceAll(secret, '<redacted>'), text);
+    const log = (message) => (options.log ?? console.log)(redact(message));
+    try {
+        await dispatch(args, { ...options, env, log });
+    }
+    catch (error) {
+        throw new Error(redact(errorMessage(error)));
+    }
+}
+// 伏字にする値。解決に使うかどうかによらず、引数と環境変数で渡された全てのキーと token を含める。
+function collectSecrets(args, env) {
+    const values = Object.entries(env)
+        .filter(([name]) => name.startsWith('SHINAPS_MANAGED_'))
+        .map(([, value]) => value ?? '');
+    args.forEach((arg, index) => {
+        if (arg === '--api-key')
+            values.push(args[index + 1]?.split('=').slice(1).join('=') ?? '');
+    });
+    return values.filter((value) => value.length > 0);
+}
+async function dispatch(args, context) {
+    const [command, ...rest] = args;
+    if (!command || command === '--help' || command === 'help') {
+        context.log(managedUsage);
+        return;
+    }
+    const { positional, flags, apply } = parse(rest);
+    const home = context.home ?? homedir();
+    const ant = context.ant ?? antCommand(context.env);
+    const accounts = flags.get('account') ?? [];
+    if (command === 'setup') {
+        if (positional.length || !accounts.length)
+            throw usageError();
+        // キーを先に全て解決する。途中のアカウントで欠けて止まると、一部だけが更新された状態になる。
+        const resolved = resolveAccounts(accounts, flags, context.env, home);
+        const results = [];
+        const failures = [];
+        for (const account of resolved) {
+            try {
+                const result = await setupAccount(account, {
+                    apply,
+                    ant,
+                    log: context.log,
+                    source: context.source ?? packageRoot,
+                });
+                results.push(result);
+                context.log(`Account ${account.name}: ${result}.`);
+            }
+            catch (error) {
+                failures.push(account.name);
+                context.log(`Account ${account.name}: failed. ${errorMessage(error)}`);
+            }
+        }
+        if (failures.length)
+            throw new Error(`Setup failed for: ${failures.join(', ')}.`);
+        if (results.includes('planned')) {
+            context.log('No changes were applied. Re-run with --apply after reviewing the plans.');
+        }
+        return;
+    }
+    if (apply || accounts.length !== 1)
+        throw usageError();
+    const [account] = resolveAccounts(accounts, flags, context.env, home);
+    if (command === 'run') {
+        if (positional.length !== 1)
+            throw usageError();
+        return run(positional[0], account, flags, context, ant);
+    }
+    if (positional.length)
+        throw usageError();
+    const sessionId = required(flags, 'session');
+    if (command === 'status') {
+        context.log(JSON.stringify(await sessionStatus(account, sessionId, ant), null, 2));
+    }
+    else if (command === 'reply') {
+        await replySession(account, sessionId, await readFile(required(flags, 'message-file'), 'utf8'), ant);
+        context.log(`Sent the reply to session ${sessionId}.`);
+    }
+    else if (command === 'collect') {
+        const saved = await collectOutputs(account, sessionId, ant);
+        context.log([
+            ...saved,
+            'Saved only. Nothing was applied; review a patch with `git apply --check <changes.patch>` in a checkout of the agreed base.',
+        ].join('\n'));
+    }
+    else {
+        throw usageError();
+    }
+}
+async function run(configPath, account, flags, context, ant) {
+    const config = await validateManagedConfig(configPath);
+    if (!Object.hasOwn(config.accounts, account.name)) {
+        throw new Error(`Account ${account.name} is not listed in ${configPath}.`);
+    }
+    const settings = config.accounts[account.name];
+    const staffing = required(flags, 'staffing');
+    if (!staffings.includes(staffing)) {
+        throw new Error(`--staffing must be one of ${staffings.join(', ')}.`);
+    }
+    const allowText = required(flags, 'allow');
+    const listed = allowText === 'none' ? [] : allowText.split(',');
+    if (listed.some((permission) => !permissions.includes(permission)) ||
+        new Set(listed).size !== listed.length) {
+        throw new Error(`--allow must be none or a comma-separated subset of ${permissions.join(',')}.`);
+    }
+    // 並び順だけが違う同じ許可を別の依頼として扱わないよう、正規の順に揃える。
+    const allow = permissions.filter((permission) => listed.includes(permission));
+    const budget = required(flags, 'budget-cents');
+    if (!/^[1-9][0-9]*$/.test(budget))
+        throw new Error('--budget-cents must be a positive integer.');
+    // 次の 2 つは、セッションを作ってから lead が気づいても予算を消費した後になるので、作る前に止める。
+    if (allow.includes('draft_pr') && settings.vault_id === null) {
+        throw new Error(`draft_pr needs a vault with the GitHub MCP credential, but account ${account.name} has vault_id null.`);
+    }
+    const githubToken = context.env[githubTokenVariable] || null;
+    if ((allow.includes('push') || allow.includes('draft_pr')) && !githubToken) {
+        throw new Error(`push and draft_pr need ${githubTokenVariable} for the mounted repository.`);
+    }
+    const optional = (flag) => flags.get(flag)?.[0] ?? null;
+    const claudeMdPath = optional('claude-md');
+    const request = {
+        account: account.name,
+        repository: config.repository,
+        vault_id: settings.vault_id,
+        base: required(flags, 'base'),
+        base_sha: required(flags, 'base-sha'),
+        head: required(flags, 'head'),
+        staffing: staffing,
+        allow,
+        budget_cents: budget,
+        task: await readFile(required(flags, 'task-file'), 'utf8'),
+        verify: optional('verify'),
+        author: optional('author'),
+        title: optional('title'),
+        claude_md: claudeMdPath === null ? null : await readFile(claudeMdPath, 'utf8'),
+    };
+    const sessionId = await runSession(account, request, {
+        ant,
+        log: context.log,
+        githubToken,
+        claudeMdPath,
+        now: context.now ?? (() => new Date()),
+    });
+    context.log(`Observe: shinaps-skills managed status --account ${account.name} --session ${sessionId}`);
+}
+function resolveAccounts(names, flags, env, home) {
+    const keys = new Map();
+    for (const pair of flags.get('api-key') ?? []) {
+        const separator = pair.indexOf('=');
+        if (separator <= 0)
+            throw new Error('--api-key expects <account>=<key>.');
+        keys.set(pair.slice(0, separator), pair.slice(separator + 1));
+    }
+    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.`);
+    }
+    const missing = unique.filter((name) => !(keys.get(name) || env[apiKeyVariable(name)]));
+    if (missing.length) {
+        throw new Error(`Missing API key for ${missing.map((name) => `${name} (--api-key ${name}=<key> or ${apiKeyVariable(name)})`).join(', ')}.`);
+    }
+    return unique.map((name) => ({
+        name,
+        apiKey: keys.get(name) || env[apiKeyVariable(name)],
+        dir: managedAccountDir(managedRoot(home), name),
+    }));
+}
+// 値を取るフラグは `--name value` の形だけを受け付ける。エラー文には引数の値を含めない (キーを
+// 含みうるため)。
+function parse(args) {
+    const positional = [];
+    const flags = new Map();
+    let apply = false;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const name = arg.slice(2);
+        if (name === 'apply') {
+            apply = true;
+            continue;
+        }
+        const value = args[index + 1];
+        if (!valueFlags.has(name) || value === undefined)
+            throw usageError();
+        const values = flags.get(name) ?? [];
+        if (values.length && !repeatableFlags.has(name))
+            throw usageError();
+        flags.set(name, [...values, value]);
+        index++;
+    }
+    return { positional, flags, apply };
+}
+function required(flags, name) {
+    const value = flags.get(name)?.[0];
+    if (!value)
+        throw new Error(`Missing --${name}. See shinaps-skills managed --help.`);
+    return value;
+}
+const usageError = () => new Error('Invalid arguments for shinaps-skills managed. See shinaps-skills managed --help.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shinaps/skills",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Install Shinaps AI workflows and custom agents for Codex",
   "type": "module",
   "bin": {

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

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

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

@@ -2,7 +2,7 @@
 name: shinaps-dev-managed-cc
 description: shinaps の dev 工程を Claude Managed Agents で進める lead。メインとして調査・設計・実装・指摘の採否を行い、選んだ体制の独立した担当に別案と独立レビューを委任し（BASIC・ULTRAでは追加の担当を判断する）、draft PR まで進める。
 model:
-  id: claude-fable-5-1
+  id: claude-opus-5-5
   effort: medium
   speed: standard
 mcp_servers:

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

@@ -4,7 +4,7 @@
 
 ## 検証CLIと契約版
 
-利用中のskillとCLIの版を確認し、0.37.0のskillには同じ版のnpm CLIを導入する（`npm install -g @shinaps/skills@0.37.0`）。pluginだけにはCLIは含まれない。導入・更新が必要ならその権限を確認し、検証のたびに `npx latest` を取得しない。
+利用中のskillとCLIの版を確認し、0.38.0のskillには同じ版のnpm CLIを導入する（`npm install -g @shinaps/skills@0.38.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にする。
 

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

@@ -1,59 +1,84 @@
-# Claude Managed Agents の設定
+# Claude Managed Agents の設定とアカウント
 
-作業先リポジトリの `.shinaps/managed.json` に置く。`config_version: 1` のJSONで、[JSON Schema](configuration.schema.json)を契約の正本とする。
+Managed Agents は配布CLI `shinaps-skills managed` で導入・依頼・観測・回収する（[導入](setup.md)・[依頼と観測](execute.md)）。CLI は利用中の skill と同じ版の `@shinaps/skills` を使う。クラウドの操作は公式の `ant` CLI（2.4.0 以上）へ委ね、CLI は PATH 上の `ant` を呼ぶ。CLI が使うコマンド・フラグ・stdin の本文・出力の形は、ant 2.4.0 の公式ソースで照合した（実行は未確認。[未検証の境界](execute.md#未検証の境界)）。
 
-設定が持つのは、共通定義のコピーの置き場所・対象リポジトリ・GitHub MCP の資格情報を登録した vault だけである。許可・予算・Issueの範囲・base と head・終了条件は呼び出しのたびに利用者と合意して決め、設定には書かない。lead・役割・環境のリソース ID は lock から読み、設定には書かない。vault は lock に記録されないため、`vault_id` だけを設定に持つ。秘密値は書かない。schema は未知のキーを拒否するので、許可や予算などのキーを書いた設定は検証で失敗し、許可や予算として扱われることはない。
+## アカウント
 
-認証は `ant` の既存のログイン（利用者本人が `ant auth login` を行う）と環境変数、GitHub MCP は vault の資格情報を使う。
+アカウントは、APIキー1つが属する組織・workspace に利用者が付ける名前で、英小文字・数字と単独のハイフン（`^[a-z0-9]+(-[a-z0-9]+)*$`）にする。同じマシンでは、同じ名前は常に同じ組織・workspace を表すようにする。lock がアカウント名で引かれるので、別の組織に同じ名前を使うと別の組織の lock で適用しようとする（`ant apply` は lock と違う組織・workspace の資格情報を拒否して止まる）。
 
-## 配置
+### APIキー
+
+コマンドごとに、各アカウントのキーを次のどちらかで渡す。
+
+- 環境変数 `SHINAPS_MANAGED_API_KEY_<NAME>`（`<NAME>` はアカウント名の英大文字で、`-` は `_`。例 `work-us` → `SHINAPS_MANAGED_API_KEY_WORK_US`）。推奨。
+- 引数 `--api-key <name>=<key>`（環境変数より優先）。引数は同じマシンの他のプロセスやシェルの履歴から見えるので、共有のマシンでは使わない。
+
+CLI はキーを保存せず、出力とエラー文では伏字にする。`ant` へは子プロセスの環境変数 `ANTHROPIC_API_KEY` だけで渡し、親の `ANTHROPIC_*`（別のキー・`ant auth login` のプロファイル・workspace の指定）と他アカウントのキーは子へ渡さない。workspace をまたげる資格情報（`--workspace-id` が必要なもの）は扱わないので、workspace に属するキーを使う。
+
+### アカウントの状態
+
+各アカウントの状態は、マシン単位の管理ディレクトリ `~/.local/share/shinaps-ai/skills/managed/<account>/` に置く。lock は組織・workspace に属し、リポジトリには属さないため。複数のリポジトリから同じアカウントを使っても lock は1つになり、clone のやり直し・worktree・`git clean` で失われない。
 
 | パス | 内容 |
 | --- | --- |
-| `.shinaps/managed.json` | この設定 |
-| `<definitions>/agents/`・`environments/`・`skills/` | plugin の `managed-agents/` からコピーした共通定義。テンプレートの所有で、更新時は丸ごと置き換える |
-| `<definitions>/claude-lock.json` | `ant apply` が記録するクラウド上のリソースの ID と版 |
+| `definitions/agents/`・`environments/`・`skills/` | 同梱の共通定義の写し。setup が同梱の定義に揃える |
+| `definitions/claude-lock.json` | `ant apply` が記録するクラウド上の lead・役割・skill・環境の ID と版。setup は読むだけで書き換えない。手で編集しない |
+| `definitions.json` | setup が最後に書いた共通定義の各ファイルのハッシュ。利用者の変更の検出に使う |
+| `sessions/<request_id>.json` | このアカウントで作ったセッションの記録（入力と session ID。秘密値は含まない） |
+| `sessions/<session_id>/outputs/` | 回収した出力ファイル |
+| `update.lock` | 同じアカウントの setup・run を同時に1つにする排他（`ant apply` は lock を排他しないため） |
+
+`definitions/` には同梱の共通定義と lock だけを置き、共通定義を手で編集しない。適用はディレクトリ内の定義をすべて送るため。利用者が加えた定義の変更は導入に取り込まない（クラウドへ持ち越さない）。setup は、自分が最後に書いた内容か今回書く内容と一致するファイルだけを書き換え・削除する。利用者の編集・追加、記録の無い既存のファイル（旧版の定義ごと複写した場合など）、通常のファイル・ディレクトリ以外のもの、ほかの項目が一つでもあれば、何も変えずにそのアカウントを失敗にし、該当するパスを示す。それらを `definitions/` の外へ退避してから（lock は残す）再実行すると、同梱の定義を書き直して進む。消えた共通定義のファイルは書き直す。
+
+## lock の扱い
 
-いずれも Git 対象外にする。`.shinaps/.gitignore` が `*` で始まる場合は追加の設定なしで除外される。書き込む前に `git check-ignore --no-index -v <パス>` で除外を確認する。除外されていなければ、[導入の手順](setup.md#1-設定を読む)に従って既存の規則と共有例外を保ったまま `.shinaps/.gitignore` に必要な行だけを加えてから書き込む（新規作成の内容は[作業記録の共通手順](../work-records.md)と同じ）。`<definitions>` をリポジトリの外に置く場合は Git の対象にならないので、この確認は `.shinaps/managed.json` だけに行う。
+- `definitions/claude-lock.json` がクラウド上の ID の正本である。lead の ID は `./agents/shinaps-dev-managed-cc.md`、環境の ID は `./environments/shinaps-dev.yaml` の `id` にある。
+- lock のキーは lock のあるディレクトリからの相対パスである。共通定義を同じ構造で `definitions/` 直下に置き、そこで適用するので、既存のリソースに対応づく。
+- lock が無いと適用は既存のリソースと対応づかず、同じ名前のリソースを重複して作る。lock の `hash` は既存のリソースから作り直せないので、setup は lock が無いアカウントに同名の未アーカイブの lead・役割・環境があれば止まる。バックアップや以前の置き場所から lock を戻して再実行する。見つからなければ適用せず、利用者に相談する。
+- 別のマシンでは lock が無い。同じ組織を別のマシンから導入するときは、元のマシンの lock を同じ名前のアカウントへ複写する。
 
-## 項目
+## 作業先の設定（`.shinaps/managed.json`）
 
-全項目が必須で、`$schema` だけは省略できる。
+`managed run` だけが読む作業先の設定。`config_version: 2` のJSONで、[JSON Schema](configuration.schema.json)を契約の正本とする。持つのは、セッションにマウントするリポジトリと、アカウントごとの GitHub MCP の vault だけである。許可・予算・base と head・範囲・体制は依頼のたびに引数で明示し、設定には書かない。schema は未知のキーを拒否するので、許可や予算のキーを書いた設定は検証で失敗する。lead と環境の ID はアカウントの lock から読む。秘密値は書かない。
 
 | キー | 内容 |
 | --- | --- |
 | `$schema` | 任意のエディタ補助。CLI はこの URL を取得しない |
-| `config_version` | `1` |
-| `definitions` | 共通定義のコピーと lock を置くディレクトリ。リポジトリのルートからの相対パス、または絶対パス。clone のやり直し・worktree・`git clean` の影響を避けたい場合は、リポジトリの外の絶対パスにする。同じマシンの同じ組織で複数のリポジトリから使う場合は、全リポジトリの `definitions` に同じ絶対パスを指定し、lock を 1 つにする。別のマシンでは[lock の扱い](#lock-の扱い)に従う |
+| `config_version` | `2` |
 | `repository.url` | セッションにマウントする GitHub リポジトリの URL |
 | `repository.mount_path` | セッション内のマウント先（例 `/workspace/widgets`） |
-| `vault_id` | GitHub MCP の資格情報を登録した vault の ID。未登録なら `null` |
+| `accounts.<name>.vault_id` | そのアカウントで GitHub MCP の資格情報を登録した vault の ID（vault は組織ごと）。未登録なら `null`。依頼に使うアカウントを全て書く |
 
-## 検証
+設定は Git 対象外にする（`.shinaps/.gitignore` が `*` で始まる場合は追加の設定なしで除外される）。書き込む前に `git check-ignore --no-index -v .shinaps/managed.json` で除外を確認し、除外されていなければ既存の規則と共有例外を保ったまま `.shinaps/.gitignore` の末尾に `/managed.json` を加える（新規作成の内容は[作業記録の共通手順](../work-records.md)と同じ）。
 
-利用中の skill と同じ版の `@shinaps/skills` を導入し、`shinaps-skills validate-managed-config <明示ファイル>` で検証する。ローカル開発では `node bin/skills.ts validate-managed-config <file>` を使える。CLI は指定された一つのJSONを同梱 schema で検証し、ネットワーク取得・設定の探索・Git 操作・入力の変更はしない。成功は構造が正しいことだけを表し、lock や vault がクラウドに存在することは保証しない。
+### 検証
 
-`config_version` が欠落または旧版なら setup で作り直し、未来版なら skill と CLI を更新する。
+`shinaps-skills validate-managed-config <明示ファイル>` で検証する。ローカル開発では `node bin/skills.ts validate-managed-config <file>` を使える。CLI は指定された一つのJSONを同梱 schema で検証し、ネットワーク取得・設定の探索・Git 操作・入力の変更はしない。成功は構造が正しいことだけを表し、vault やアカウントの lock がクラウドに存在することは保証しない。
 
-## 設定例
+`config_version` が欠落または旧版なら作り直し、未来版なら skill と CLI を更新する。
+
+### version 1 からの移行
+
+version 1 は lock を作業先の `definitions`（既定 `.shinaps/managed/`）に置いていた。
+
+1. 使っていた組織・workspace にアカウント名を決める。
+2. `<definitions>/claude-lock.json` だけを `~/.local/share/shinaps-ai/skills/managed/<account>/definitions/claude-lock.json` へ移す（複数のリポジトリで同じ `definitions` を共有していた場合も1回でよい）。旧版の `agents/` などは移さない。移すと記録の無いファイルとして setup が止まる。
+3. 設定を version 2 で作り直す。`definitions` を除き、`vault_id` を `accounts.<account>.vault_id` へ移す。
+4. `managed setup --account <account>` で計画を確かめる（[導入](setup.md)）。lock を移し忘れると同名のリソースで止まる。旧版の定義を手で編集していた場合、その変更は持ち越されない。計画に、クラウド上の定義を同梱の定義へ戻す update が含まれることを確かめてから適用する。
+
+### 設定例
 
 ```json
 {
-  "$schema": "https://cdn.jsdelivr.net/npm/@shinaps/skills@0.34.0/plugins/shinaps-claude/references/managed/configuration.schema.json",
-  "config_version": 1,
-  "definitions": ".shinaps/managed",
+  "$schema": "https://cdn.jsdelivr.net/npm/@shinaps/skills@0.38.0/plugins/shinaps-claude/references/managed/configuration.schema.json",
+  "config_version": 2,
   "repository": {
     "url": "https://github.com/acme/widgets",
     "mount_path": "/workspace/widgets"
   },
-  "vault_id": null
+  "accounts": {
+    "personal": { "vault_id": null },
+    "work": { "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv" }
+  }
 }
 ```
-
-## lock の扱い
-
-- `<definitions>/claude-lock.json` がクラウド上の lead・役割・skill・環境の ID の正本である。`ant apply` が作成・更新するので手で編集しない。
-- lock のキーは lock のあるディレクトリからの相対パス（例 `./agents/shinaps-dev-managed-cc.md`）である。共通定義を同じ構造で `<definitions>` 直下に置くので、そこで適用すると既存のリソースに対応づく。
-- lead の ID は `./agents/shinaps-dev-managed-cc.md`、環境の ID は `./environments/shinaps-dev.yaml` の `id` から読む。
-- lock が無いと適用は既存のリソースと対応づかず、同じ名前のリソースを重複して作る。lock の `hash` は既存のリソースから作り直せないため、バックアップや以前の置き場所から戻す。見つからなければ適用せず、利用者に相談する。
-- 適用の前後に lock を作業記録（`.shinaps/work/`）へ複製し、適用後の差分を比べる。

package/plugins/shinaps-claude/references/managed/configuration.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://cdn.jsdelivr.net/npm/@shinaps/skills@0.34.0/plugins/shinaps-claude/references/managed/configuration.schema.json",
-  "title": "Shinaps Managed Agents configuration v1",
+  "$id": "https://cdn.jsdelivr.net/npm/@shinaps/skills@0.38.0/plugins/shinaps-claude/references/managed/configuration.schema.json",
+  "title": "Shinaps Managed Agents configuration v2",
   "type": "object",
   "properties": {
     "$schema": {
@@ -9,11 +9,7 @@
     },
     "config_version": {
       "type": "integer",
-      "const": 1
-    },
-    "definitions": {
-      "type": "string",
-      "minLength": 1
+      "const": 2
     },
     "repository": {
       "type": "object",
@@ -30,18 +26,32 @@
       "required": ["url", "mount_path"],
       "additionalProperties": false
     },
-    "vault_id": {
-      "anyOf": [
-        {
-          "type": "string",
-          "minLength": 1
+    "accounts": {
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "vault_id": {
+            "anyOf": [
+              {
+                "type": "string",
+                "minLength": 1
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
         },
-        {
-          "type": "null"
-        }
-      ]
+        "required": ["vault_id"],
+        "additionalProperties": false
+      }
     }
   },
-  "required": ["config_version", "definitions", "repository", "vault_id"],
+  "required": ["config_version", "repository", "accounts"],
   "additionalProperties": false
 }