@shinaps/skills 0.31.0 → 0.32.0

package/README.md

@@ -6,12 +6,24 @@ Shinaps AIの利用者向け開発ワークフロー。Claude CodeとCodexには
 
 共通スキルが持つのは判断手順。対象環境・必須検証・公開条件は、対象プロジェクトの `AGENTS.md` / `CLAUDE.md` と参照先、README、CI、既存スクリプトから読み取る。専用設定ファイルは必須にしない。
 
-例外として `linear-execute` の開発進行とチーム設定の変更には、対象リポジトリの `.shinaps/linear.yaml` を必須にする。操作の継続的な許可と終了地点を会話から推測せず、合意した範囲だけを続けて進めるためである。設定は `config_storage: shared` でGit共有、`local` でメインの作業ツリーだけに保存する。既存設定でキーがない場合だけ従来のlocal扱いを維持し、自動追記・許可の再合意は求めない。sharedは現在のcheckout、localはメインの設定と補足を正本とする。共有設定が欠けていても端末別のlocal設定では補わない。[共通設定](plugins/shinaps-claude/references/linear/configuration.md)の読取・保存手順に従う。設定がなくてもIssueの読み取り・整理はできる。設定が必要な実行で共通の読取手順により真に未設定と確認できた場合だけ、同じセッションで `linear-plan` の初期設定ヒアリングへ進み、合意した設定の保存・確認後に元の依頼を再開する。
+例外として `linear-execute` の開発進行とチーム設定の変更には、対象リポジトリの `.shinaps/linear.json` を必須にする。操作の継続的な許可と終了地点を会話から推測せず、合意した範囲だけを続けて進めるためである。設定は `config_storage: shared` でGit共有、`local` でメインの作業ツリーだけに保存する。必須キーの欠落は設定不備として止め、旧設定は明示移行する。sharedは現在のcheckout、localはメインの設定と補足を正本とする。共有設定が欠けていても端末別のlocal設定では補わない。[共通設定](plugins/shinaps-claude/references/linear/configuration.md)の読取・保存手順に従う。設定がなくてもIssueの読み取り・整理はできる。設定が必要な実行で共通の読取手順により真に未設定と確認できた場合だけ、同じセッションで `linear-plan` の初期設定ヒアリングへ進み、合意した設定の保存・確認後に元の依頼を再開する。
 
-sharedで採用する `instructions.md` は共有YAMLの `references.specifications` に明記して開始・再開時に読み、他の必要補足は内容に対応する `references` に記載する。必要補足の欠落・読取不能は依存工程を止め、未採用とは扱わない。設定・採用補足・ignoreの個別例外を一緒に共有するか、共有済み資料への参照に置き換える。端末の絶対パスやsession/thread ID、進捗・QA結果は `.shinaps/work/` に分け、秘密値はどちらにも保存しない。保存方式の合意だけでstage・commit・push・追跡解除を許可しない。
+sharedで採用する `instructions.md` は共有JSONの `references.specifications` に明記して開始・再開時に読み、他の必要補足は内容に対応する `references` に記載する。必要補足の欠落・読取不能は依存工程を止め、未採用とは扱わない。設定・採用補足・ignoreの個別例外を一緒に共有するか、共有済み資料への参照に置き換える。端末の絶対パスやsession/thread ID、進捗・QA結果は `.shinaps/work/` に分け、秘密値はどちらにも保存しない。保存方式の合意だけでstage・commit・push・追跡解除を許可しない。
 
 例えばPCブラウザのみのプロジェクトには対応ブラウザと確認コマンドを書く。iOSプロジェクトにはSimulatorと実機の使い分けを記す。スキルは一律の端末数やOS数を追加しない。既存の情報で決まらず結果を左右する条件だけ確認し、保存を了承された方針をプロジェクト側に残す。
 
+## JSON設定の検証
+
+0.32.0から `.shinaps/linear.json`（`config_version: 1`）を使います。旧YAML・scalar review_flow・旧キーの共存は移行未完了として止め、[移行手順](plugins/shinaps-claude/references/linear/configuration.md#旧設定の移行)に従います。コメントの運用条件も補足へ移します。
+
+CLIはpluginに含まれないため、利用中のskillと同じ `@shinaps/skills@0.32.0` を導入し、`shinaps-skills --version` で確認します。`shinaps-skills validate-linear-config <明示ファイル>` は同梱schemaだけで検証し、ネットワーク取得・正本探索・Git操作・入力変更は行いません。`$schema` は固定URLによるエディタ補助で、契約の正本は[同梱schema](plugins/shinaps-claude/references/linear/configuration.schema.json)です。
+
+```sh
+npm install -g @shinaps/skills@0.32.0
+shinaps-skills --version
+shinaps-skills validate-linear-config /absolute/repository/.shinaps/linear.json
+```
+
 ## スキル
 
 | 名前 | 用途 |
@@ -32,15 +44,15 @@ sharedで採用する `instructions.md` は共有YAMLの `references.specificati
 
 コミット・PR・リリースは、利用者の依頼またはLinear進行で合意済みの継続許可に従う。[共通設定](plugins/shinaps-claude/references/linear/configuration.md)・[担当と工程](plugins/shinaps-claude/references/linear/workflow.md)・[終了と待機](plugins/shinaps-claude/references/linear/execution.md)を参照し、必要な前工程が揃えば再確認せずに進む。単独スキル利用にはLinear進行や新しいゴールを必須にしない。`autonomous-commit-review` の役割は `commit` に統合した。個人用の別AI呼び出し・ブラウザ管理・ゴール管理・動画制作はこのpluginに含めない。
 
-`linear-execute` は初版では利用者本人の環境向けで、進行とAgent QAは会話側が担当する（Claude・Codexの入口ではCodex、Managedの入口では linear-execute を実行する Claude Code または Codex）。運用項目は明示必須で、既存設定の `config_storage`・`path_policy_overrides` 欠落は共通設定の説明に従い、それ以外は未記載を既定値で補わない。実装の担当は作業先の `.shinaps/linear.yaml` の `implementation_skill` で選ぶ。`dev-claude` は基本 `review_flow: auto` ならCodexがローカル `claude -p` を起動し、同じsessionをresumeする。manualならWebStormのClaudeへAI Terminal Bridgeで依頼する。[CLI手順](plugins/shinaps-claude/references/linear/claude-cli.md)に従い、CLIの既存権限・model・effort・pluginsを保持する。`dev-codex` を選ぶと、会話側はゴール・進行・Agent QAを担当し、Issueごとの別Codexタスクが実装・QA指摘の修正・許可されたコミットを行う。タスク作成・連絡には `codex_task` とツールが要求する明示依頼が必要。`dev-managed-cc` を選ぶと、Issueごとの Managed Agents セッションが実装し、進行役が差分を適用してQAとreview_flowに従ったコミット工程を行う。`managed_session:<USD>` と `dev_delegation` が必要で、Bridge は不要。どの入口でも `implementation_skill` は許可を増やさない。Bridge本体は同梱せず、導入済みのMCPとWebStormプラグインを使う。`SKILL.md` は担当ごとに両版で書き分け、共通の手順と書式は `references/linear/` に置く。`references/linear/` はClaude版を編集元としてCodex版とManaged Agents版へ同じ内容を複製し、テストで一致を確認する。
+`linear-execute` は初版では利用者本人の環境向けで、進行とAgent QAは会話側が担当する（Claude・Codexの入口ではCodex、Managedの入口では linear-execute を実行する Claude Code または Codex）。運用項目は明示必須で、未記載を既定値で補わない。実装の担当は作業先の `.shinaps/linear.json` の `implementation_skill` で選ぶ。`dev-claude` はauto/manualともCodexがローカル `claude -p` を起動し、同じsessionをresumeする。manualのレビューUIは `review_flow.tool` で選ぶ。[CLI手順](plugins/shinaps-claude/references/linear/claude-cli.md)に従い、CLIの既存権限・model・effort・pluginsを保持する。`dev-codex` を選ぶと、会話側はゴール・進行・Agent QAを担当し、Issueごとの別Codexタスクが実装・QA指摘の修正・許可されたコミットを行う。タスク作成・連絡には `codex_task` とツールが要求する明示依頼が必要。`dev-managed-cc` を選ぶと、Issueごとの Managed Agents セッションが実装し、進行役が差分を適用してQAとreview_flowに従ったコミット工程を行う。`managed_session:<USD>` と `dev_delegation` が必要で、Bridge は不要。どの入口でも `implementation_skill` は許可を増やさない。Bridge本体は同梱せず、導入済みのMCPとWebStormプラグインを使う。`SKILL.md` は担当ごとに両版で書き分け、共通の手順と書式は `references/linear/` に置く。`references/linear/` はClaude版を編集元としてCodex版とManaged Agents版へ同じ内容を複製し、テストで一致を確認する。
 
-`review_flow: auto` はAIが自然な単位を決め、独立レビュー・QA後にstage・commitする。`manual` はAIが単位を計画し、単位外を安全にstashしてstage・提示し、人がレビュー・修正・commitする。両方のstage権限とautoのAI commit権限は利用者との明示合意に含まれ、未合意ファイルからは得ない。`path_policy_overrides` は `paths` と `review_flow` だけを持つ。全変更が一つのルールで覆われる単位だけ適用し、改名は旧新両パスを判定する。競合時は止める。旧 `human_code_review`・`commit_mode`・permissionsのstage/commit・パス別ai_commitは明示移行が必要。[共通設定](plugins/shinaps-claude/references/linear/configuration.md#パス別の方針)を参照する。
+`review_flow: { "mode": "auto" }` はAIが自然な単位を決め、独立レビュー・QA後にstage・commitする。`review_flow: { "mode": "manual", "tool": "plasma" }`（toolは `webstorm` も可） はAIが単位を計画し、単位外を安全にstashしてstage・提示し、人がレビュー・修正・commitする。両方のstage権限とautoのAI commit権限は利用者との明示合意に含まれ、未合意ファイルからは得ない。`path_policy_overrides` は `paths` と `review_flow` だけを持つ。全変更が一つのルールで覆われる単位だけ適用し、改名は旧新両パスを判定する。競合時は止める。旧 `human_code_review`・`commit_mode`・permissionsのstage/commit・パス別ai_commitは明示移行が必要。[共通設定](plugins/shinaps-claude/references/linear/configuration.md#パス別の方針)を参照する。
 
-0.29.0では旧 `document_only_changes: ai_commit` を廃止した。利用先では依存工程を止め、具体的なパス例外への移行または例外廃止を合意する。説明だけの変更の許可とは同値でないため自動変換しない。旧 `none` は例外なしとして維持でき、新規設定は `path_policy_overrides: []` にする。
+0.29.0では旧 `document_only_changes: ai_commit` を廃止した。利用先では依存工程を止め、具体的なパス例外への移行または例外廃止を合意する。説明だけの変更の許可とは同値でないため自動変換しない。旧 `none` もJSONへ明示移行し、新規設定は `path_policy_overrides: []` にする。
 
 `permissions` の `development_operations` を明示すると、既存アカウントのログイン・環境準備・依存導入・起動・テスト・QAを継続的に許可できる。コミット・公開・破壊的操作の許可や人レビューは別に扱う。
 
-旧 `linear` の入口は廃止した。相談・Issue整理・設定変更は `linear-plan`、実行は `linear-execute` を使う。YAMLの名前・運用項目は変わらない。実行範囲は毎回の依頼で確定し、バックログではブロッカー到達と報告を終了条件にできる。人レビュー・Human QA待ちは予定工程として待機する。
+旧 `linear` の入口は廃止した。相談・Issue整理・設定変更は `linear-plan`、実行は `linear-execute` を使う。設定は0.32.0からJSONへ移行する。実行範囲は毎回の依頼で確定し、バックログではブロッカー到達と報告を終了条件にできる。人レビュー・Human QA待ちは予定工程として待機する。
 
 ### dev の入口と体制
 
@@ -72,7 +84,7 @@ sharedで採用する `instructions.md` は共有YAMLの `references.specificati
 
 ## Codex
 
-Node.js 22以上と、`plugin marketplace add` / `plugin add` に対応したCodex CLIを使う。Claude Codeのインストールは不要。ただし `linear-execute` の開発進行をClaudeの入口で行う場合は、autoではローカルClaude Code、manualではWebStormのClaude CodeとAI Terminal Bridgeが必要になる。Managedの入口で進める場合は `ant` CLI が必要になる。
+Node.js 22以上と、`plugin marketplace add` / `plugin add` に対応したCodex CLIを使う。Claude Codeのインストールは不要。ただし `linear-execute` の開発進行をClaudeの入口で行う場合は、両modeともローカルClaude Codeが必要になる。Managedの入口で進める場合は `ant` CLI が必要になる。
 
 導入・更新・削除:
 
@@ -249,7 +261,7 @@ npm pack --dry-run
 
 ### Codexでの人レビュー
 
-manualでは対象checkoutと単位の差分を提示し、人のレビュー・修正・コミット完了を待ちます。Claude経路はWebStorm、Codex経路はPlasmaを使います。Plasmaは別途導入するツールで、未導入時も人レビューを省略しません。変更の目的と確認点は会話に示し、人の完了通知後の実コミット照合と修正の検証は[共通手順](plugins/shinaps-codex/references/human-review.md)に従います。autoには人レビュー待ちを追加しません。
+manualでは対象checkoutと単位の差分を提示し、人のレビュー・修正・コミット完了を待ちます。実装runtimeによらず、実効 `review_flow.tool` でPlasmaまたはWebStormを選びます。Plasmaは別途導入するツールで、未導入時も人レビューを省略しません。変更の目的と確認点は会話に示し、人の完了通知後の実コミット照合と修正の検証は[共通手順](plugins/shinaps-codex/references/human-review.md)に従います。autoには人レビュー待ちを追加しません。
 
 ### CIとnpm自動公開
 
@@ -323,7 +335,7 @@ Claude版は全16エージェントが `opus / medium`。Codex版の役割定義
 ```text
 .shinaps/
 ├── .gitignore             # 保存方式に応じた除外・共有対象の例外
-├── linear.yaml            # linear のプロジェクト設定（任意）
+├── linear.json            # linear のプロジェクト設定（任意）
 ├── linear/                # linear の補足（任意）
 └── work/
     ├── {日時}-{作業名}/

package/dist/bin/skills.js

@@ -1,10 +1,23 @@
 #!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { packageRoot } from '../lib/layout.js';
+import { validateLinearConfig } from '../lib/linear-config.js';
 import { run } from '../lib/install.js';
 import { autoUpdate } from '../lib/auto-update.js';
 import { errorMessage } from '../lib/fs.js';
 const [command, ...rest] = process.argv.slice(2);
 try {
-    if (command === 'auto-update')
+    if (command === '--version') {
+        console.log(JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version);
+    }
+    else if (command === 'validate-linear-config') {
+        if (rest.length !== 1)
+            throw new Error('Usage: shinaps-skills validate-linear-config <file>');
+        await validateLinearConfig(rest[0]);
+        console.log('Linear configuration is valid (config_version: 1).');
+    }
+    else if (command === 'auto-update')
         await autoUpdate(rest);
     else
         await run(process.argv.slice(2));

package/dist/lib/install.js

@@ -10,6 +10,7 @@ const actions = ['install', 'update', 'uninstall', 'recover'];
 const isAction = (value) => actions.includes(value);
 const usage = [
     'Usage: shinaps-skills <install|update|uninstall|recover> codex',
+    '       shinaps-skills validate-linear-config <file>',
     '       shinaps-skills auto-update <enable|disable|status|check> codex',
     'Claude Code: /plugin marketplace add sh1n4ps/shinaps-skills',
     '             /plugin install shinaps@shinaps-skills',

package/dist/lib/linear-config.js

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Ajv } from 'ajv';
+import { packageRoot } from './layout.js';
+/** 明示されたファイルを同梱の契約で検証する。設定の探索・変更や外部取得は行わない。 */
+export async function validateLinearConfig(path) {
+    const input = JSON.parse(await readFile(path, 'utf8'));
+    // 版の不一致は設定修正とskill更新で対処が異なるため、schema検証より先に案内する。
+    if (typeof input === 'object' && input !== null && !Array.isArray(input)) {
+        const version = 'config_version' in input ? input.config_version : undefined;
+        if (version === undefined || (Number.isInteger(version) && Number(version) < 1)) {
+            throw new Error('config_version is missing or old. Migrate with linear-plan to config_version: 1.');
+        }
+        if (Number.isInteger(version) && Number(version) > 1) {
+            throw new Error('Future config_version. Update the skill and matching CLI before continuing.');
+        }
+    }
+    const schema = JSON.parse(await readFile(join(packageRoot, 'plugins/shinaps-claude/references/linear/configuration.schema.json'), 'utf8'));
+    const validator = new Ajv({
+        allErrors: true,
+        coerceTypes: false,
+        useDefaults: false,
+        removeAdditional: false,
+    });
+    const validate = validator.compile(schema);
+    if (!validate(input)) {
+        const errors = validate.errors
+            ?.map((error) => `${error.instancePath || '/'} ${error.message} ${JSON.stringify(error.params)}`)
+            .join('\n');
+        throw new Error(`Invalid Linear configuration. Correct the JSON to match configuration.schema.json:\n${errors}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shinaps/skills",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Install Shinaps AI workflows and custom agents for Codex",
   "type": "module",
   "bin": {
@@ -39,5 +39,8 @@
     "@biomejs/biome": "2.5.15",
     "@types/node": "^26.6.4",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0"
   }
 }

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

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

package/plugins/shinaps-claude/references/dev/workflow.md

@@ -105,7 +105,7 @@ Issue・既存spec・調査記録・関連コード・検証方法を必要な
 
 初期体制と変更理由、実際の担当・確認範囲、計画と実装後のレビュー回数、採否・修正、検証結果、未実施・未照合・未解決事項を報告する。
 
-linear-executeから受けた作業は未コミットの差分と結果を進行役へ返す。devの完了はLocal Agent QAへの引き渡しであり、進行全体の終了ではない。[Linear共通設定](../linear/configuration.md)と[担当と工程](../linear/workflow.md)に従い、QA後のcommit工程の依頼を受け、autoはAIコミット、manualは人への提示準備を行う。Claudeのauto経路は [Claude CLI](../linear/claude-cli.md) のresultへ報告し、同じsessionのresumeで質問・修正を受ける。manual経路はBridgeで返す。Codex・Managedはそれぞれの既存返却経路を使う。
+linear-executeから受けた作業は未コミットの差分と結果を進行役へ返す。devの完了はLocal Agent QAへの引き渡しであり、進行全体の終了ではない。[Linear共通設定](../linear/configuration.md)と[担当と工程](../linear/workflow.md)に従い、QA後のcommit工程の依頼を受け、autoはAIコミット、manualは人への提示準備を行う。Claudeのauto/manual両modeは [Claude CLI](../linear/claude-cli.md) のresultへ報告し、同じsessionのresumeで質問・修正を受ける。manualの提示はprocess終了後に実効 `review_flow.tool` で行う。Codex・Managedはそれぞれの既存返却経路を使う。
 
 単独のdevではコミットが許可されている場合だけ範囲とモードを `commit` へ渡す。許可がなければ未コミットで返し、形式的な許可確認を追加しない。PR・リリースも許可された範囲で各スキルへ渡す。単独devにLinear進行・新しいゴールを必須にしない。
 

package/plugins/shinaps-claude/references/human-review.md

@@ -2,22 +2,26 @@
 
 manualで人がレビュー・修正・commitする場合に使う。review_flow・操作許可は、プロジェクト設定と今回の依頼に従う。この手順はそれらを変更しない。
 
-Claude経路のmanualはWebStormでレビューする。Plasmaを必須にしない。以下のCodex UI手順はCodex経路に適用する。
+実装runtimeによらず、実効 `review_flow.tool` が `plasma` ならPlasma、`webstorm` ならWebStormを使う。UIの指定がない場合は提示前に一問で確認する。設定のmanualでtoolが欠落していれば設定を修正する。CLIのprocess終了を確認してから提示し、人の操作と実装処理を並行しない。
 
 ## 対象の準備
 
 レビュー対象のcheckoutの絶対パス、ブランチ、比較元のcommit、対象ファイルと完全な差分、検証結果を確定する。未追跡ファイルも対象に含める。stageは許可された範囲だけで行い、無関係な差分や既存のステージ境界を変更しない。対象差分と比較元は作業記録へ残し、後で承認対象と照合できるようにする。
 
-## CodexではPlasmaで開く
+## plasmaではPlasmaで開く
 
-Codex実装経路で人への窓口がCodexの場合は、レビューを依頼する会話でPlasmaを開く。人への窓口がClaudeの場合は既存の差分提示方法を使い、Plasmaのためだけに別のCodexタスクを作らない。
+レビューを依頼する進行役の会話でPlasmaを開く。必要なツールが利用不能なら止め、runtimeから別UIを推測しない。
 
 1. 利用可能なPlasmaの`open_workbench`ツールと現在の入力仕様を確認する。ファイルを開く`route`が使える場合は、対象checkoutの絶対パスとレビュー対象のファイルを指定する。現在の形式は`/open?project=ABSOLUTE_PATH&file=RELATIVE_PATH&line=START&endLine=END`で、各値をURLエンコードする。存在するファイルを使い、適切なファイルがない場合はプロジェクト選択画面から対象checkoutを選ぶ。
 2. ファイルを開くことと差分を表示することを区別する。ファイル用routeに差分モードの未定義パラメーターを足さない。利用可能なUI操作ツールでPlasmaのGit画面を確認し、レビュー対象に合う比較を選ぶ。UI操作が使えない場合は、対象プロジェクト・比較方法・ファイル一覧を示して利用者に選択を依頼する。
 3. 表示中のcheckout・比較元・対象範囲をGitで確定した差分と照合する。ステージ済みの単位なら`git diff --cached`を基準にする。作業ツリー全体や別ブランチの差分を、その単位の差分として提示しない。対象全体を表示できない場合は、未表示の範囲を明示し、完全な差分を確認できる方法を利用者と決める。
 4. 会話に変更の目的、確認してほしい点、検証結果、対象単位を示し、レビュー・必要な修正・コミット完了を依頼する。Linear進行ではIssueも示す。Plasma内の注釈は指摘として扱い、画面を開いたことや操作の終了を承認とみなさない。
 
-Plasmaが未導入・起動失敗の場合は、その状態を伝え、Codexの差分表示など利用者が選んだ方法で同じ対象を提示する。無断でインストールや設定変更を行わず、表示できていないレビューを完了扱いにしない。
+Plasmaが未導入・起動失敗の場合は、その状態を伝えて止める。別UIを使う場合はtoolの変更を合意してから同じ対象を提示する。無断でインストールや設定変更を行わず、表示できていないレビューを完了扱いにしない。
+
+## webstormではWebStormで開く
+
+`webstorm <checkoutの絶対パス>` で対象を開く。checkout・branch・比較元を確認し、対象単位のstaged差分（`git diff --cached`）を提示する。単にファイルを開いたことを差分表示の完了と扱わない。会話に目的・確認点・検証結果・対象単位を示し、人のレビュー・修正・commit完了を待つ。ツールがない、起動できない、対象差分を確認できない場合は止め、無断fallbackしない。
 
 ## 人のレビュー・コミット完了後の照合
 

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

@@ -1,8 +1,8 @@
 # ローカルClaude CLIによる実装
 
-`dev-claude` の基本 `review_flow: auto` は、Codexが作業先でローカル `claude -p` を起動する。manualはWebStormのClaudeとBridgeを使う。初回実装前に基本flow、正確なcheckout・branch・HEAD・既存差分、経路許可（autoは `claude_cli`、manualは `bridge_request` または今回の明示依頼）を確定する。manualのBridge不足でCLIへfallbackしない。CodexとManagedの既存経路は変更しない。
+`dev-claude` はauto/manualとも、Codexが作業先でローカル `claude -p` を起動する。初回実装前に正確なcheckout・branch・HEAD・既存差分と `claude_cli` の許可（または今回の明示依頼）を確定する。CodexとManagedの既存経路は変更しない。
 
-パス例外はコミット単位のreview_flowだけを変え、実装経路を途中で切り替えない。CLI経路でmanual単位になった場合は、CLIの実行終了を確認して同じcheckoutをWebStormで人へ提示する。Codexが人のレビュー・修正・commit完了を受け取り、単位差分・SHAと照合する。その後の実装依頼は変更後のHEADと差分を添えて同じCLIセッションをresumeする。Bridge経路のauto単位も同じBridgeセッションでQA後にcommitを依頼する。
+パス例外はコミット単位のreview_flowを全体置換し、実装sessionを途中で切り替えない。manual単位ではstash・stageまで準備したCLIのprocess終了を確認し、進行役が同じcheckoutを実効 `review_flow.tool`（plasma / webstorm）で提示する。[人レビュー](../human-review.md)に従って人のレビュー・修正・commit完了を受け取り、単位差分・SHAと照合する。その後は変更後のHEADと差分を添えて同じCLI sessionをresumeする。人の操作中にCLIを並行実行しない。UI不足時は止め、別UIやBridgeへ無断で切り替えない。
 
 ## 起動と観測
 
@@ -32,6 +32,6 @@ resumeにも同じcwdと許可境界を指定し、外部で変化したHEAD・
 
 ## 操作権限
 
-`review_flow: auto` はClaudeの `--permission-mode auto` を意味しない。非対話起動では `--permission-mode dontAsk` を明示し、既存設定がbypassでも継承しない。model・effort・pluginsは保持し、操作許可は既存の個別allow設定と今回の範囲に限定する。`--permission-prompts none` は対話できないpromptを拒否として返すためであり、許可を付与しない。permission_denialsがあれば操作と必要な権限を報告し、既存の明示許可が対象を満たすか確認する。満たす場合だけ必要なSkill/Agentや対象を限定した `--allowedTools` を明示し、同じsessionへ明示的に再依頼する。新しい権限が必要ならCodexが人へ確認する。`--allowedTools` を使う場合も対象・操作に限定し、無条件の `Bash(*)`、bypassPermissions、dangerously-skip-permissionsを使わない。拒否を隠すsilent retryをしない。会話上の許可はCLIの権限チェックを消さない。
+`review_flow.mode: auto` はClaudeの `--permission-mode auto` を意味しない。非対話起動では `--permission-mode dontAsk` を明示し、既存設定がbypassでも継承しない。model・effort・pluginsは保持し、操作許可は既存の個別allow設定と今回の範囲に限定する。`--permission-prompts none` は対話できないpromptを拒否として返すためであり、許可を付与しない。permission_denialsがあれば操作と必要な権限を報告し、既存の明示許可が対象を満たすか確認する。満たす場合だけ必要なSkill/Agentや対象を限定した `--allowedTools` を明示し、同じsessionへ明示的に再依頼する。新しい権限が必要ならCodexが人へ確認する。`--allowedTools` を使う場合も対象・操作に限定し、無条件の `Bash(*)`、bypassPermissions、dangerously-skip-permissionsを使わない。拒否を隠すsilent retryをしない。会話上の許可はCLIの権限チェックを消さない。
 
 CLI仕様の参照: [headless](https://code.claude.com/docs/en/headless)、[CLI reference](https://code.claude.com/docs/en/cli-reference)。利用版で必要なflagが非対応なら状態を報告して停止し、権限回避へ切り替えない。

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

@@ -1,13 +1,26 @@
 # プロジェクト設定
 
-設定は、運用上の決定と既存資料への参照を持つ。手順の全文は書かない。秘密値を保存しない。設定はAIが読む文書であり、専用のプログラムで検査しない。
+設定は、運用上の決定と既存資料への参照を持つ。手順の全文は書かない。秘密値を保存しない。設定は `config_version: 1` のJSONで、[JSON Schema](configuration.schema.json)を契約の正本とする。利用前に同梱CLIで構造を検証し、合意・参照先・工程の実在確認は各手順で行う。
+
+## 検証CLIと契約版
+
+利用中のskillとCLIの版を確認し、0.32.0のskillには同じ版のnpm CLIを導入する（`npm install -g @shinaps/skills@0.32.0`）。pluginだけにはCLIは含まれない。導入・更新が必要ならその権限を確認し、検証のたびに `npx latest` を取得しない。
+
+```sh
+shinaps-skills --version
+shinaps-skills validate-linear-config /absolute/repository/.shinaps/linear.json
+```
+
+ローカル開発では `node bin/skills.ts validate-linear-config <file>` を使える。CLIは指定された一つのJSONを読み、同梱schemaで検証する。ネットワーク取得、正本探索、Git操作、入力変更、型変換、既定値の補完、未知キーの除去はしない。未知キーはroot・下位とも拒否する。成功は構造が有効なことだけを表し、許可の合意やLinearの状態・参照ファイルの存在は保証しない。
+
+`config_version` が欠落または旧版なら移行、未来版ならskillとCLIの更新、不正型なら設定修正を案内する。JSONコメントは使わず、運用条件は補足へ書く。`$schema` は設定例の固定URLでエディタを補助し、CLIは外部のschemaを取得しない。
 
 ## 配置と保存方式
 
 ```text
 .shinaps/
   .gitignore            # 保存方式に応じた除外と共有対象の例外
-  linear.yaml           # 対象・工程・許可・終了地点・参照先・報告
+  linear.json           # 対象・工程・許可・終了地点・参照先・報告
   linear/
     instructions.md     # 採用する場合だけ置くプロジェクト固有の指示
     references/         # 必要な場合だけ分ける詳細資料
@@ -18,7 +31,7 @@
 
 - `shared`: 設定と運用に必要な補足をGitで共有し、現在のcheckoutの設定を正本とする。
 - `local`: メインの作業ツリーに設定と補足を保存し、Gitの対象外とする。
-- 既存設定にキーがない場合だけ、従来どおり `local` として扱う。自動追記や既存の許可の再合意は不要。新規設定は明記する。空値・`null`・その他の値は不正として止め、他の必須項目の欠落も補完しない。
+- `config_storage` と `path_policy_overrides` を含む必須項目の欠落は不正。旧設定は下の移行手順で明示的に移行する。
 
 保存方式は共有範囲の選択であり、対象・操作許可・担当・終了地点・レビュー条件を変えない。必須でない空ファイルを作らない。補足にSKILL.mdや独立した呼び出し名を置かず、READMEなどが正本の内容は参照する。
 
@@ -26,17 +39,17 @@
 
 開始時と再開時に次の順で正本を一つ決め、設定と補足を読み直す。「現在」は作業対象のcheckout、「メイン」は同じリポジトリの `git worktree list` の先頭を指す。同じcheckoutなら一つだけ読む。
 
-1. 現在の `.shinaps/linear.yaml` を確認する。読取不能・不正値なら止める。`shared` なら現在だけを採用し、メインの設定は調べない。
-2. 現在が `local` 相当（明示 `local` または既存キー欠落）、または設定が真に不在の場合だけ、メインを確認する。不在の場合は、そのcheckoutのindexとHEADに設定がないことも確かめる。どちらかにあれば削除・未展開による不備として止める。Git状態を確定できないときも、未設定とは扱わない。
-3. メインが `local` 相当ならメインだけを採用する。現在のコピーで上書き・統合しない。メインが `shared` なら現在との不整合または現在の共有設定不足として止める。メインが不正・読取不能なら止める。メインが不在の場合もindexとHEADを確認し、両方にないときだけ真の不在とする。現在が `local` 相当なのにメインが不在なら正本不備で止める。両方が真に不在の場合だけ初期設定へ進む。
+1. 現在の `.shinaps/linear.json` を確認し、上記CLIで検証する。探索候補に旧 `.shinaps/linear.yaml` があれば移行対象として止める。JSON/YAMLの共存も移行未完了であり、一方を選んで続けない。読取不能・不正値なら止める。`shared` なら現在だけを採用し、メインの設定は調べない。
+2. 現在が `local`、または設定が真に不在の場合だけ、メインを同じ検証と旧YAML確認で確認する。不在の場合は、そのcheckoutのindexとHEADに設定がないことも確かめる。どちらかにあれば削除・未展開による不備として止める。Git状態を確定できないときも、未設定とは扱わない。
+3. メインが `local`ならメインだけを採用する。現在のコピーで上書き・統合しない。メインが `shared` なら現在との不整合または現在の共有設定不足として止める。メインが不正・読取不能なら止める。メインが不在の場合もindexとHEADを確認し、両方にないときだけ真の不在とする。現在が `local`なのにメインが不在なら正本不備で止める。両方が真に不在の場合だけ初期設定へ進む。
 
-不在の確認には、そのcheckoutで `git ls-files -- .shinaps/linear.yaml`（index）と `git ls-tree HEAD -- .shinaps/linear.yaml`（HEAD）を使う。HEAD未作成なら、その状態が確定した場合に限りHEADに設定なしと扱う。追跡状態だけで保存方式を推測しない。未追跡の `shared` は準備中の設定として読めるが、共有済みとは報告しない。追跡済みの `local` は不整合として報告し、自動で追跡解除しない。
+不在の確認には、そのcheckoutで `git ls-files -- .shinaps/linear.json .shinaps/linear.yaml`（index）と `git ls-tree HEAD -- .shinaps/linear.json .shinaps/linear.yaml`（HEAD）を使う。HEAD未作成なら、その状態が確定した場合に限りHEADに設定なしと扱う。追跡状態だけで保存方式を推測しない。未追跡の `shared` は準備中の設定として読めるが、共有済みとは報告しない。追跡済みの `local` は不整合として報告し、自動で追跡解除しない。
 
 設定・`instructions.md`・必要な `references` は同じ正本から読む。補足の相対パスは正本のリポジトリルートを基準とし、コード・検証・配備などの操作対象の相対パスは現在の作業先を基準とする。共有設定の不足を別checkout・別端末のlocal設定や補足で補わない。`.shinaps/work/` の記録は証拠であり、設定を上書きしない。
 
-- `shared` では、採用した補足を共有YAMLの `references` に明示する。`instructions.md` は `references.specifications` に記載し、開始・再開時に必ず読む。存在するのに記載がなければ採用情報の不備として止め、無視や自動追記で続けない。
+- `shared` では、採用した補足を共有JSONの `references` に明示する。`instructions.md` は `references.specifications` に記載し、開始・再開時に必ず読む。存在するのに記載がなければ採用情報の不備として止め、無視や自動追記で続けない。
 - その他の補足は内容に対応する既存の5分類へ記載し、担当する工程に必要なものを読む。参照された補足がない・読めない場合は未採用と解釈せず、依存する工程を止める。採用した `instructions.md` の欠落・読取不能は設定に依存する実行全体の開始・再開を止める。
-- `local` 相当では従来どおり、存在する `instructions.md` を開始・再開時に読み、その他の補足は工程に必要なものを読む。既存設定への参照の自動追記はしない。
+- `local`では従来どおり、存在する `instructions.md` を開始・再開時に読み、その他の補足は工程に必要なものを読む。既存設定への参照の自動追記はしない。
 - 採用していない任意の補足はなくてもよい。必要な補足を未採用扱いにして運用条件を減らさない。
 - 補足ファイルは追加の条件と手順を表す。設定の決定（対象・許可・終了地点・工程の対応）と、人の完了・QAの証拠の要件は変えない。補足と設定が矛盾したら、設定に従って止め、どちらを直すか確認する。
 - 不足や矛盾があれば、影響する工程の開始前に止めて一問ずつ確認する。影響しない工程は続ける。許可の追加やステータスの新設を推測で補わない。
@@ -47,10 +60,12 @@
 
 ## 項目
 
-以下の項目は明示必須（既存設定の `config_storage` と `path_policy_overrides` の欠落はそれぞれの説明に従う）。省略・不正値を既定値で補わず、依存する工程を止めて設定を確認する。`null`・`none`・空の一覧は、以下で認めた箇所だけで「使用しない」を表す。
+以下の項目は明示必須。`$schema` だけはエディタ補助として省略できる。省略・不正値を既定値で補わず、依存する工程を止めて設定を確認する。`null`・`none`・空の一覧は、以下で認めた箇所だけで「使用しない」を表す。
 
 | キー | 内容 |
 | --- | --- |
+| `config_version` | 整数 `1`。パッケージ版とは独立した契約版 |
+| `$schema` | 任意のエディタ補助。固定URLは下記。CLIはこのURLを取得しない |
 | `config_storage` | `shared`（Git共有）または `local`（メインの作業ツリーだけに保存）。保存・読取規則は上記に従う |
 | `target.workspace` | Linearのworkspace |
 | `target.team` | チームのキー（例 `SHINAPS`） |
@@ -61,9 +76,9 @@
 | `permissions` | 継続的に許可した操作の一覧（下の「許可」）。許可なしは `[]` |
 | `references` | `specifications`・`validation`・`environments`・`deployment`・`publication` の5分類をすべて記載し、既存資料のパスまたはURLの一覧を指定する。該当資料なしは `[]` |
 | `cycle_report` | Cycle報告の設定（下の「Cycle報告」）。報告を使わない場合は `null` |
-| `implementation_skill` | Issueの実装・修正に使うruntimeの入口。担当数は固定せずメインが作業ごとに決める。`dev-claude`（基本 `review_flow` がautoならCodexがローカルClaude CLI、manualならWebStormのClaudeへBridgeで依頼する）、`dev-codex`（Issueごとの別Codexタスクがその入口を実行し、会話側は進行・Agent QAを担当する）、または `dev-managed-cc`（linear-executeを実行する会話が進行役になり、IssueごとのClaude Managed Agentsセッションのleadがその入口で実装する） |
-| `review_flow` | `auto`（AIが自然な単位を決め、独立レビュー・QA後にstage・commit）、`manual`（AIが単位を計画し、単位外を安全にstashしてstage・提示、人がレビュー・修正・commit） |
-| `path_policy_overrides` | パス別に `review_flow` を上書きするルールの一覧。例外なしは `[]`。既存設定で欠落していれば例外なし（下の「パス別の方針」） |
+| `implementation_skill` | Issueの実装・修正に使うruntimeの入口。担当数は固定せずメインが作業ごとに決める。`dev-claude`（auto/manualともCodexがローカルClaude CLIの同じsessionへ依頼する）、`dev-codex`（Issueごとの別Codexタスクがその入口を実行し、会話側は進行・Agent QAを担当する）、または `dev-managed-cc`（linear-executeを実行する会話が進行役になり、IssueごとのClaude Managed Agentsセッションのleadがその入口で実装する） |
+| `review_flow` | `{ "mode": "auto" }`（AIが自然な単位を決め、独立レビュー・QA後にstage・commit）、`{ "mode": "manual", "tool": "plasma" }` または `{ "mode": "manual", "tool": "webstorm" }`（AIが単位を計画し、単位外を安全にstashしてstage・提示、人がレビュー・修正・commit） |
+| `path_policy_overrides` | パス別に `review_flow` を上書きするルールの一覧。例外なしは `[]`（下の「パス別の方針」） |
 
 - 利用者と合意した `review_flow` は両方とも対象のstageを許可し、`auto` だけAIのcommitも許可する。`manual` のcommitは人が行う。未合意の設定ファイルから許可を得ない。その場の明示指示が優先し、push・公開・履歴変更は別の許可に従う。
 - `implementation_skill` が決めるのは、実装・修正の担当と実行方式だけである。`permissions`・`stop_after`・人レビュー・コミットの方針と、`dev_delegation`・worktreeの作成・別セッションの作成の許可を変えない。その場の明示的な指定は設定に優先する。既存の設定にキーがなくても、自動で書き加えない。担当と工程の対応は [workflow.md](workflow.md) の「担当と窓口」にある。
@@ -75,14 +90,16 @@
 
 `path_policy_overrides` は、各予定コミットに入る全変更を対象に方針を適用する。Linear進行でも単独の `commit` でも同じ規則を使う。新規設定は `path_policy_overrides: []` とし、具体的なパスと上書き項目を利用者と合意した場合だけルールを追加する。
 
-```yaml
-path_policy_overrides:
-  - paths: ["docs/**", "README.md"]
-    review_flow: auto
+```json
+{
+  "path_policy_overrides": [
+    { "paths": ["docs/**", "README.md"], "review_flow": { "mode": "auto" } }
+  ]
+}
 ```
 
-- 各ルールは空でない `paths` と `review_flow: auto | manual` だけを必須とする。その他のキー、省略、不正値や構文は設定不備として依存工程を止める。
-- パス別のflowもstageとcommit担当を上記のとおり決める。push・公開・終了地点・ツール権限・必要なQAは変更しない。実装開始時のClaude通信経路は基本flowで固定し、パス例外では切り替えない（[Claude CLI](claude-cli.md)）。
+- 上書きは `review_flow` オブジェクト全体を置換する。autoへ切り替える場合はtoolを引き継がない。各ルールは空でない `paths` と `review_flow` オブジェクト だけを必須とする。その他のキー、省略、不正値や構文は設定不備として依存工程を止める。
+- パス別のflowもstageとcommit担当を上記のとおり決める。push・公開・終了地点・ツール権限・必要なQAは変更しない。実装開始時のClaude CLI sessionを保持し、パス例外では切り替えない（[Claude CLI](claude-cli.md)）。
 - パス設定への合意は対象と工程の許可であり、変更内容に含まれる未合意仕様や権限拡張への承認ではない。内容や拡張子から例外許可を推定しない。
 
 ### パターンとコミット全体の照合
@@ -92,7 +109,7 @@ path_policy_overrides:
 各予定コミットの全変更に現れる旧・新パスが、一つのルールのパターン一覧で覆われる場合だけ、そのルールをそのコミット全体へ適用できる。追加は新パス、削除は旧パス、改名・移動は両方を含め、modeだけの変更も対象にする。新パスだけの一覧や現在残っているファイルだけでは判定しない。
 
 - コミット全体に適用できるルールがなければ、そのコミット全体を通常方針とする。複数ルールをファイル別・項目別に合成しない。
-- コミット全体に適用できるルールが複数ある場合、`review_flow` が同じならその方針を採用し、適用した全ルールを記録する。一つでも結果が異なれば依存工程を止めて競合の解消を求める。並び順やパターンの詳細度では優先しない。
+- コミット全体に適用できるルールが複数ある場合、`review_flow` のmodeとtoolが両方同じならその方針を採用し、適用した全ルールを記録する。同じmanualでもtoolが異なるなど、一つでも結果が異なれば依存工程を止めて競合の解消を求める。並び順やパターンの詳細度では優先しない。
 - モードによらず自然な責務単位を先に決め、その予定コミットごとに判定する。同じ依頼に別の変更があっても、独立した範囲内コミットには例外を適用できる。例外取得だけを目的とした恣意的な分割はしない。依頼全体は網羅性と最終照合に使い、方針を固定する単位にはしない。
 
 ### 判定記録と変更時の扱い
@@ -103,9 +120,13 @@ path_policy_overrides:
 
 ### 旧設定の移行
 
-`human_code_review`・`commit_mode`・`permissions` の `stage` / `commit`・パス別 `ai_commit` は廃止。新キーと共存していても依存工程を止め、利用者と `review_flow` と必要な経路権限への移行を明示合意して旧キーを除く。旧値の組合せを暗黙にauto/manualへ変換しない。
+0.32.0から `.shinaps/linear.yaml` とscalar `review_flow` は受け付けない。`linear-plan` で以下を行い、正本発見・検証・保存を完了してから再開する。CLIは移行しない。
 
-`document_only_changes: none` は例外なしとして読めるため、自動変更や再合意は不要。旧 `document_only_changes: ai_commit` は廃止し、新設定と共存していても依存工程を止める。具体的なパスと上書き項目への移行、または例外廃止を利用者と合意してから旧キーを除く。説明だけの変更の許可とパスの許可は同値ではないため、自動変換・二重運用をしない。既存プロジェクトへ例外許可を自動追加しない。
+1. 旧設定の正本と保存方式、既存の許可・終了地点・補足を確認する。JSONとYAMLが共存する場合は内容を比較し、移行未完了として扱う。
+2. `config_version: 1`、必須の `config_storage` と `path_policy_overrides` を明記する。省略していた値も移行案で明示する。autoは `{ "mode": "auto" }`、manualは利用する `tool` を含むオブジェクトへ移す。既存のWebStorm等の合意は維持できるが、不明なUIをruntimeから推測しない。
+3. Claudeの実装は両modeとも `claude_cli` を使う。旧Bridge経路からの権限変更は移行案へ明記し、許可なく追加しない。`bridge_request` 自体は有効で、他runtimeや別用途の既存許可を削除しない。
+4. YAMLコメントの運用条件は `instructions.md` または対応する参照資料へ移し、sharedでは参照と共有対象に含める。旧 `human_code_review`・`commit_mode`・permissionsのstage/commit・`document_only_changes`・パス別ai_commitは除去する。旧noneは例外なしへの移行案、旧ai_commitは具体的パスへの移行または廃止を合意し、暗黙変換しない。
+5. 合意済みのJSONを保存して検証し、旧YAMLを除き、ignore・参照・共有対象も更新する。追跡解除・stage・commitは既存の許可と安全手順に従う。新旧差分で許可・工程・保存方式・補足が保たれていることを確認する。
 
 ## 終了地点
 
@@ -127,8 +148,8 @@ path_policy_overrides:
 | `issue_update` | 対象のteam・projectの中で、利用者が任せたIssue・Cycleの範囲に対する運用上の更新（本文・コメント・状態・依存・Linearへの添付、整理で必要になったIssueの作成・分割）と、利用者から任された目的の作業を着手前にIssueへ紐づけるための作成（[issue.md](issue.md) の「着手前に作業をIssueへ紐づける」）。チーム設定の変更、未合意の範囲・期限の変更、Cycle外への進行、Issueの削除、外部への送信を含めない |
 | `development_operations` | 任された対象の開発に必要な、既存アカウントへの通常のログイン、ローカル環境準備、プロジェクトの依存導入、開発サーバー・Simulatorの起動停止、ビルド・テスト・QA操作を継続的に許可する。下の範囲に従う |
 | `codex_task` | 対象IssueごとのCodex実装タスクの新規作成・状態確認・実装や修正や許可済みコミットの依頼。アーカイブ、worktree作成、操作許可の追加、タスク側でのゴールや実装タスクの再作成は含めない。ツールの明示依頼要件も満たす。アーカイブの合意と手順は [完了後の整理](codex-task.md#完了後の整理) に従う |
-| `claude_cli` | auto ClaudeのローカルCLI起動、同じsessionの状態・結果取得、質問への回答・修正・許可済みコミットのresume。既存CLI設定と個別の操作権限を維持する（[手順](claude-cli.md)） |
-| `bridge_request` | BridgeによるCodexからClaudeへの実装・修正の依頼と、ClaudeからCodexへの開発進行の引き渡し |
+| `claude_cli` | auto/manual共通のClaudeのローカルCLI起動、同じsessionの状態・結果取得、質問への回答・修正・許可済みコミットのresume。既存CLI設定と個別の操作権限を維持する（[手順](claude-cli.md)） |
+| `bridge_request` | Bridgeによる別会話との任意の進行の引き渡し・人の完了報告。報告は照合材料であり、CLIの実装経路・レビューUI・操作許可を変更しない（[手順](workflow.md#bridgeでの任意の引き渡し・報告)） |
 | `managed_session:<USD>` | 対象IssueごとにClaude Managed Agentsのセッションを作り、同じIssueのコミット前のQA修正には続けて使う（コミット後の修正は新しいセッションで行う。扱いは[Managedセッション](managed-session.md)の「QAと修正」に従う）。`<USD>` は1セッションの予算の上限で、正の整数のUSD（作成時にセントへ換算する）。値がない、または正の整数でない場合は設定不備として止める。含める操作: 作業先のコミット済みの内容（git bundle）と、あれば `~/.claude/CLAUDE.md` のFiles APIへのアップロード、上限内での予算の設定、一覧から名前で一件に特定したvaultの受け渡し、状態・イベント・出力の取得、回答と修正依頼の送信、取得した差分の作業先への適用と作業記録の展開。含めない操作: 上限を超える予算の引き上げ（その場で確認する）、セッションとファイルのアーカイブ・削除、定義のapply、vaultの作成・変更 |
 | `push` | 対象Issueの作業ブランチの通常のpush |
 | `pr_create` | 対象IssueのPRの作成と更新 |
@@ -138,7 +159,7 @@ path_policy_overrides:
 | `dev_delegation` | `implementation_skill` で選んだdevの入口の中で、サブエージェントへ委託する。許可がない場合は、入口のメインが同じ観点を自分で確認し、独立確認とは報告しない。worktreeの作成は含まない |
 | `evidence:<保存先>` | Linear以外の指定した保存先へQA素材を保存する（LinearのIssueへの添付は `issue_update` に含む） |
 
-- 開発進行には `issue_update` が必要。Claudeの入口は基本 `review_flow: auto` なら `claude_cli` とローカルClaude CLI、`manual` なら `bridge_request` とWebStormのBridgeを使う。今回の明示依頼による同じ経路の許可も引き継ぐ。Codexの入口は `codex_task` とタスク操作ツール、Managedの入口は `managed_session:<USD>`・`dev_delegation` と認証済み `ant` CLIが必要。初期設定は `issue_update`・選んだ経路の許可・`dev_delegation` と `review_flow` を具体的に提案し、合意を得る。設定の存在だけでは許可を得ない。初回実装前に経路を確定し、manualのBridge不足をCLIへのfallbackで補わない。
+- 開発進行には `issue_update` が必要。Claudeの入口はauto/manualとも `claude_cli` とローカルClaude CLIを使う。今回の明示依頼による同じ経路の許可も引き継ぐ。Codexの入口は `codex_task` とタスク操作ツール、Managedの入口は `managed_session:<USD>`・`dev_delegation` と認証済み `ant` CLIが必要。初期設定は `issue_update`・選んだ経路の許可・`dev_delegation` と `review_flow` を具体的に提案し、合意を得る。設定の存在だけでは許可を得ない。manualの提示UIは `review_flow.tool` で選び、利用不能なら止める。
 - `development_operations` は、既存の認証手段と利用者が許可した既存アカウントを使い、対象の開発・検証環境と専用の検証データで行う操作に限る。本人の二要素認証・セキュリティキー・CAPTCHA等が必要なら具体的に依頼し、回避しない。ログイン成功を新しい権限への同意と扱わず、新規アカウント・OAuth権限の拡大・課金・新規クラウド資源・共有環境への破壊的変更・実利用者データの操作は含めない。秘密値をIssueや証拠へ記載しない。
 - この包括許可は `stage`・`commit`・`push`・`pr_create`・`merge`・`deploy:*`・`publish:*`・外部への送信・履歴やデータの破壊的操作を含まない。テストや環境準備がこれらを伴うときも、stage・commitは合意済みflow、その他はそれぞれの許可が必要。人レビュー・Human QA・ツール側の承認条件を省略しない。`permissions` に明示された場合だけ適用し、既存設定に自動で追加しない。
 - 一つの操作が別の操作を伴う場合は、伴う操作の許可も必要とする（マージで本番へ自動配備される場合は `merge` と `deploy:production`）。
@@ -163,44 +184,55 @@ path_policy_overrides:
 
 shinaps-skills側の例。shinaps-aiも、自分のリポジトリの設定で同じprojectを指す。
 
-```yaml
-# 設定を置いたこのリポジトリを作業先とするIssueに適用する。
-config_storage: shared
-target:
-  workspace: shinaps
-  team: SHINAPS
-  project: https://linear.app/shinaps/project/shinaps-ai-76ed13db8314 # projectを使わない場合は null
-team_settings: existing_only
-# ステータス名は形式の例。初期設定でチームの実際の一覧と照合して決める。
-statuses:
-  todo: Todo
-  refinement: In Progress
-  ready: Todo
-  coding: In Progress
-  local_agent_qa: In Progress
-  code_review: In Review
-  post_commit: In Review
-  human_input: In Progress
-  done: Done
-stop_after: pre_push_qa
-implementation_skill: dev-claude # manualはWebStorm Bridge、autoはローカルCLI
-review_flow: manual
-path_policy_overrides: []
-cycle_report: null
-permissions:
-  - development_operations # この範囲を利用者が合意した場合だけ記載
-  - issue_update
-  - bridge_request
-  - dev_delegation
-references:
-  specifications:
-    - README.md
-    - .shinaps/linear/instructions.md
-  environments: []
-  deployment: []
-  validation:
-    - .shinaps/linear/references/qa.md
-  publication: []
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/sh1n4ps/shinaps-skills/v0.32.0/plugins/shinaps-claude/references/linear/configuration.schema.json",
+  "config_version": 1,
+  "config_storage": "shared",
+  "target": {
+    "workspace": "shinaps",
+    "team": "SHINAPS",
+    "project": "https://linear.app/shinaps/project/shinaps-ai-76ed13db8314"
+  },
+  "team_settings": "existing_only",
+  "statuses": {
+    "todo": "Todo",
+    "refinement": "In Progress",
+    "ready": "Todo",
+    "coding": "In Progress",
+    "local_agent_qa": "In Progress",
+    "code_review": "In Review",
+    "post_commit": "In Review",
+    "human_input": "In Progress",
+    "done": "Done"
+  },
+  "stop_after": "pre_push_qa",
+  "implementation_skill": "dev-claude",
+  "review_flow": {
+    "mode": "manual",
+    "tool": "webstorm"
+  },
+  "path_policy_overrides": [],
+  "cycle_report": null,
+  "permissions": [
+    "development_operations",
+    "issue_update",
+    "claude_cli",
+    "dev_delegation"
+  ],
+  "references": {
+    "specifications": [
+      "README.md",
+      ".shinaps/linear/instructions.md"
+    ],
+    "environments": [],
+    "deployment": [],
+    "validation": [
+      ".shinaps/linear/references/qa.md"
+    ],
+    "publication": []
+  }
+}
 ```
 
 この例では `instructions.md` と `qa.md` を採用して一緒に共有する。実際に必要な補足だけを選び、例に合わせた空ファイルは作らない。
@@ -217,7 +249,7 @@ Claudeもこの手順で初期設定を行える。合意した設定の保存
 2. 作業先リポジトリのAGENTS.md・CLAUDE.md・README・CI・検証や配備のスクリプトを読み、`references` の候補を決める。
 3. 設定案を一つ作る。チーム設定を管理できる場合だけ、FamilyStayを基にした工程の分離（[workflow.md](workflow.md) の工程表に対応するステータス）を変更案として示す。利用者のプロジェクトらしいという推測で `manage_on_setup` にしない。
 4. 既存の情報で決まらない運用上の決定（`config_storage`、`stop_after`、`permissions`、`review_flow`、`team_settings`、Cycle報告、`implementation_skill`）だけを一問ずつ確認する。終了地点は上の一覧から選んでもらう。パス別の例外が必要な場合は、具体的な対象パターンと上書き項目、通常設定からの変更を示して合意する。例外を使わない新規設定には `path_policy_overrides: []` を記載する。旧設定の移行は上の手順に従う。
-5. 合意した方式の正本へ、下の保存手順に従って保存する。sharedでは採用する補足の `references` と共有対象を照合し、別checkoutでも同じ条件を読めるようにする。正本と補足を読み直して確認する。
+5. 合意した方式の正本へ、下の保存手順に従って保存する。sharedでは採用する補足の `references` と共有対象を照合し、別checkoutでも同じ条件を読めるようにする。同梱CLIでJSONを検証し、正本と補足を読み直して確認する。
 6. Linearのチーム設定の変更は、設定の保存とは別に扱う。対象チームと変更差分（追加・改名するステータスと順序）を示し、合意を得てから反映して読み戻す。反映後に `statuses` を実物に合わせて確定する。
 
 ## 設定変更
@@ -236,12 +268,12 @@ localでは設定と補足をメインへ保存し、Git対象外にする。新
 *
 ```
 
-sharedでは `.shinaps/.gitignore` 自身、`linear.yaml`、採用した補足だけを共有する。新規の例は次のとおり。`qa.md` は採用した個別資料の例であり、不要なら例外も作らない。
+sharedでは `.shinaps/.gitignore` 自身、`linear.json`、採用した補足だけを共有する。新規の例は次のとおり。`qa.md` は採用した個別資料の例であり、不要なら例外も作らない。
 
 ```gitignore
 *
 !/.gitignore
-!/linear.yaml
+!/linear.json
 !/linear/
 !/linear/instructions.md
 !/linear/references/
@@ -255,7 +287,7 @@ sharedでは `.shinaps/.gitignore` 自身、`linear.yaml`、採用した補足
 
 `git check-ignore --no-index -v <対象パス>` で有効な除外規則と例外を確認し、`git ls-files -- <対象パス>` で追跡状態、`git status --short --untracked-files=all` で実際の変更を確認する。ignoreだけでは追跡済みファイルは対象外にならない。追跡解除は自動で行わず、対象・影響と許可を確認する。
 
-必要補足はYAMLと一緒に共有するか、同じ内容を確認できる共有済み資料への参照に置き換える。元のPCだけに必要補足が残る状態は共有未完了。URLとアクセス条件も別PCで同じ運用を確認できるものにする。ignore例外やファイルの存在だけで採用の有無を決めず、共有YAMLの `references` と実際の共有対象を揃える。cloneやworktreeでも、参照された補足の欠落を未採用と解釈しない。
+必要補足はJSONと一緒に共有するか、同じ内容を確認できる共有済み資料への参照に置き換える。元のPCだけに必要補足が残る状態は共有未完了。URLとアクセス条件も別PCで同じ運用を確認できるものにする。ignore例外やファイルの存在だけで採用の有無を決めず、共有JSONの `references` と実際の共有対象を揃える。cloneやworktreeでも、参照された補足の欠落を未採用と解釈しない。
 
 作業記録の初期化と保全は [作業記録](../work-records.md) に従う。