upgrade

ランタイム設定（ステップ 0 — 処理を開始する前）

ドメイン固有の動作を設定するため、以下のファイルを読み込みます。

1. ops/derivation-manifest.md — 用語の対応付け、プラットフォームのヒント

   • vocabulary.notes をノートフォルダー名に使用します
   • ノートの種類への参照には vocabulary.note / vocabulary.note_plural を使用します
   • 抽出を表す動詞には vocabulary.reduce を使用します
   • 関連を見つける動詞には vocabulary.reflect を使用します
   • 後方パスを表す動詞には vocabulary.reweave を使用します
   • 検証を表す動詞には vocabulary.verify を使用します
   • メタ認知を表す動詞には vocabulary.rethink を使用します
   • MOC への参照には vocabulary.topic_map を使用します

2. ops/config.yaml — 処理の深さ、ドメインのコンテキスト

3. ops/derivation.md — 導出の状態とエンジンのバージョン

これらのファイルが存在しない場合は、共通のデフォルトを使用します。

今すぐ実行

対象：$ARGUMENTS

直ちに解析します。

• 対象に特定のスキル名（例：「upgrade reduce」）が含まれている場合は、そのスキルだけを確認します
• 対象に「--all」が含まれている場合は、生成されたすべてのスキルを確認します
• 対象が空の場合は、生成されたすべてのスキルを確認します（「--all」と同じです）

今すぐ開始してください。 以下にアップグレードの手順を示します。

---

ハッシュ比較ではなく照合を行う理由

スキルは、生成マニフェストとのハッシュ比較によってアップグレードされるものではありません。ハッシュ比較で答えられるのは、「このファイルは変更されたか」という限定的な問いです。メタスキルによる照合では、本質的な問いに答えます。「現時点でわかっていることを踏まえると、このスキルのアプローチは今も最善か」。

ナレッジベースが拡充されれば、変更されていないスキルでも古くなっていることがあります。一方、ユーザーが大幅に編集したスキルでも、別の方法で最新の考え方をすでに取り入れていることがあります。バイト単位で差分を比較するより、方法論について推論するほうが有益です。

---

2 つのアップグレード経路

生成されたスキルとメタスキルでは、アップグレードの仕組みが根本的に異なります。

カテゴリ	スキル	アップグレードの仕組み
生成されたスキル	/{vocabulary.reduce}, /{vocabulary.reflect}, /{vocabulary.reweave}, /{vocabulary.verify}, /ralph, /next, /remember, /{vocabulary.rethink}, /stats, /graph, /tasks, /refactor, /learn, /recommend, /ask	ナレッジグラフとのランタイム照合
メタスキル	/setup, /architect, /health, /reseed, /add-domain, /help, /tutorial, /upgrade	プラグインのリリースサイクル — プラグイン自体を更新

/upgrade は生成されたスキルを評価します。自身や他のメタスキルは評価できません。それはプラグインのメンテナーの責任です。

---

ステップ 1：現在のシステムのインベントリを作成

Vault の現在の状態を収集します。

1. 以下を確認するために ops/derivation.md を読み込みます。

   • 元の導出状態
   • システムの生成に使用されたエンジンのバージョン
   • ドメインの説明と次元上の位置

2. 以下を確認するために ops/generation-manifest.yaml（存在する場合）を読み込みます。

   • スキルのバージョンと生成日時
   • 各スキルを生成したプラグインのバージョン

3. インストール済みのスキルをすべて一覧表示します。

   # Find all skill directories with SKILL.md
   for dir in .claude/skills/*/; do
     skill=$(basename "$dir")
     version=$(grep '^version:' "$dir/SKILL.md" 2>/dev/null | head -1 | awk -F'"' '{print $2}')
     gen_from=$(grep '^generated_from:' "$dir/SKILL.md" 2>/dev/null | head -1 | awk -F'"' '{print $2}')
     echo "$skill  v$version  (from $gen_from)"
   done
   

4. 現在の次元上の位置を確認するために ops/config.yaml を読み込みます。

5. ユーザーによる変更を確認します。

   # Detect skills modified after generation
   for dir in .claude/skills/*/; do
     skill=$(basename "$dir")
     file="$dir/SKILL.md"
     [[ ! -f "$file" ]] && continue
     # Check git status — modified files indicate user customization
     git_status=$(git status --porcelain "$file" 2>/dev/null)
     if [[ -n "$git_status" ]]; then
       echo "MODIFIED: $skill"
     fi
   done
   

インベントリを提示します。

--=={ upgrade : inventory }==--

System: {domain description}
Engine: arscontexta-{version}
Skills: {count} installed ({modified_count} user-modified)

  Skill               Version  Generated From    Modified
  /{vocabulary.reduce}    1.0  arscontexta-v1.6  no
  /{vocabulary.reflect}   1.0  arscontexta-v1.6  yes
  ...

---

ステップ 2：ナレッジベースと照合

生成された各スキル（対象が指定されている場合はそのスキル）について、プラグインにバンドルされたナレッジベースを参照し、そのスキルの現在のアプローチが最新のベストプラクティスを反映しているか評価します。

ナレッジベースの階層

プラグインの4つのコンテンツ階層から読み取ります。

階層	パス	内容
方法論グラフ	${CLAUDE_PLUGIN_ROOT}/methodology/	すべてのコンテンツ — kind: フィールドで絞り込みます（research/guidance/example）
リファレンスドキュメント	${CLAUDE_PLUGIN_ROOT}/reference/	WHAT — 構造化されたリファレンスドキュメントと次元マップ

methodology/ 内のノートは、frontmatter の kind: フィールドによって区別されます。

• kind: research — WHY：原則と認知科学の基盤（213件の主張）
• kind: guidance — HOW：運用手順とベストプラクティス（9件のドキュメント）
• kind: example — WHAT IT LOOKS LIKE：ドメイン構成（12件の例）
• type: moc — ナビゲーション：関連ノートを結び付けるトピックマップ（15件のマップ）

スキルごとの参照プロセス

評価対象の各スキルについて、次の手順を実施します。

1. 現在の vault スキルを読む — アプローチ全体、品質ゲート、エッジケースへの対応を把握します。

2. 関連するナレッジベースのドキュメントを読む：

   • このスキルのドメインに関する研究上の主張（例：/{vocabulary.reduce} の場合は、抽出方法論に関する主張）
   • 処理パイプラインのベストプラクティスに関するガイダンスドキュメント
   • スキルの運用パターンに関するリファレンスドキュメント

3. テキストではなく方法論を比較する：

   • スキルはナレッジベースが推奨する品質ゲートを実装していますか？
   • ナレッジベースが特定するエッジケースに対応していますか？
   • ナレッジベースが推奨する探索・検索パターンを使用していますか？
   • このスキルの生成後に、ナレッジベースに新しい手法が追加されていますか？

4. 各調査結果を分類する：

   分類	意味	例
   現状適合	スキルがナレッジベースのベストプラクティスを反映している	対応不要
   改善	ナレッジベースに、スキルにない手法が追加されている	新しい品質ゲート、より良い検索パターン
   修正	ナレッジベースの内容がスキルのアプローチと矛盾している	古い方法論、既知のアンチパターン
   拡張	ナレッジベースが、スキルで考慮されていないシナリオを扱っている	新しいエッジケース、新しいドメインパターン

5. ユーザーによる変更を確認する： スキルがユーザーによって変更されている場合は、現在のバージョン（ユーザーによる変更を含む）を読み、次の点を評価します。

   • ユーザーの変更にすでに改善内容が含まれているか（対応を省略）
   • ユーザーの変更と改善内容が独立しているか（併存可能）
   • ユーザーの変更と改善内容が競合しているか（並べて確認するよう提示）

---

ステップ3：アップグレード計画を作成する

改善可能な各スキルについて、構造化された提案を作成します。

Skill: /{domain:skill-name}
Status: {current | enhancement | correction | extension}
User-modified: {yes | no}

Current approach:
  {2-3 sentences describing what the skill currently does}

Proposed improvement:
  {2-3 sentences describing what would change}

Research backing:
  {Specific claims from the knowledge base that support this change}
  - "{claim title}" — {how it applies}
  - "{claim title}" — {how it applies}

Impact: {what changes for the user's workflow}
Risk: low | medium | high
Reversible: yes (previous version archived to ops/skills-archive/)

リスク評価

リスクレベル	基準
低	追加的な変更（新しい品質ゲート、より良いログ記録）。既存の動作は変わりません。
中	動作の変更（異なる抽出戦略、変更された検索パターン）。出力品質に影響します。
高	構造的な変更（フェーズの順序の変更、引き継ぎ形式の変更）。パイプラインの連携に影響します。

ユーザーが変更したスキルの並列比較

スキルがユーザーによって変更されており、アップグレードが可能な場合は、並べて比較して提示します。

Skill: /{domain:skill-name} (USER-MODIFIED)

Your version:                     Recommended:
  [relevant section excerpt]        [what knowledge base suggests]

Your customization:
  {description of what the user changed and why it appears intentional}

Options:
  (a) Keep your version unchanged
  (b) Apply upgrade, preserving your customizations
  (c) Apply upgrade, replacing your version (archived to ops/skills-archive/)

選択肢（b）には、アップグレードがユーザーの変更と互換性があることが必要です。競合する場合は、その理由を説明し、（a）または（c）を推奨してください。

---

ステップ4：計画を提示する

--=={ upgrade }==--

Plugin: arscontexta-{current_version}
Knowledge base: {count} research claims, {count} guidance docs
Skills checked: {count}

Upgrades available: {count}
  Enhancements: {n}  |  Corrections: {n}  |  Extensions: {n}

  1. /{domain:skill-name}
     Type: Enhancement
     Change: {one-line summary}
     Research: "{claim title}"
     Risk: low

  2. /{domain:skill-name} (USER-MODIFIED)
     Type: Correction
     Change: {one-line summary}
     Research: "{claim title}", "{claim title}"
     Risk: medium
     Note: Side-by-side comparison available

  ...

{If no upgrades:}
  All {count} skills reflect current best practices.
  No upgrades needed.

Apply all? Select specific upgrades (e.g., "1, 3")?
Or "show 2" for side-by-side detail on a specific skill.

ユーザーの返答を待ちます。明示的な承認なしに先へ進んではいけません。

---

ステップ5：承認されたアップグレードを適用する

承認された各アップグレードについて、次の手順を実施します。

5a. 現在のバージョンをアーカイブする

mkdir -p ops/skills-archive
SKILL_NAME="{skill-name}"
DATE=$(date +%Y-%m-%d)
cp ".claude/skills/${SKILL_NAME}/SKILL.md" \
   "ops/skills-archive/${SKILL_NAME}-${DATE}.md"

5b. 更新したスキルを生成する

1. プラグインからスキルの生成ブロックを読み取ります（利用可能な場合）
2. ステップ2で特定した具体的な改善を適用します
3. ops/derivation-manifest.md にあるユーザーの語彙変換を保持します
4. ops/config.yaml にあるユーザーの次元上の位置を保持します
5. 選択肢（b）を選んだ、ユーザーが変更したスキルについては、ユーザーのカスタマイズを更新後のスキルに統合します

5c. バージョン追跡を更新する

スキルの frontmatter を更新します。

---
version: "{incremented}"
generated_from: "arscontexta-{current_plugin_version}"
---

5d. 生成マニフェストを更新する

ops/generation-manifest.yaml が存在する場合、このスキルのエントリを更新します。

skills:
  {skill-name}:
    version: "{new_version}"
    upgraded: "{ISO 8601 UTC}"
    upgrade_source: "knowledge-graph-consultation"
    changes: "{brief description of what changed}"

---

ステップ 6：検証する

承認されたすべてのアップグレードを適用した後、次の手順を実行します。

1. カーネルの検証 — カーネルチェックを実行し、構造上の不変条件が満たされていることを確認します。

   # Verify skill files are valid
   for dir in .claude/skills/*/; do
     [[ -f "$dir/SKILL.md" ]] || echo "MISSING: $dir/SKILL.md"
   done
   

2. コンテキストファイルの確認 — コンテキストファイル内のすべてのスキル参照が引き続き解決できることを確認します。

3. 語彙の確認 — アップグレードしたスキルで、ドメインの語彙が一貫して使われていることを確認します。

   # Spot-check that vocabulary markers were resolved
   grep -l '{vocabulary\.' .claude/skills/*/SKILL.md 2>/dev/null
   # Should return nothing — all markers should be resolved
   

4. パイプラインとの互換性 — パイプラインスキル（/{vocabulary.reduce}、/{vocabulary.reflect}、/{vocabulary.reweave}、/{vocabulary.verify}）をアップグレードした場合は、/ralph との引き継ぎ形式の互換性を確認します。

---

最終レポート

--=={ upgrade complete }==--

Applied: {N} upgrades
Archived: {N} previous versions to ops/skills-archive/
Skipped: {N} (user-modified, kept as-is)

Changes:
  - /{skill}: {what changed} (Research: "{claim}")
  - /{skill}: {what changed} (Research: "{claim}")

Validation: {PASS | FAIL with details}

{If any validation failed:}
  WARNING: Validation issue detected.
  Previous versions available in ops/skills-archive/
  for manual rollback.

Note: Run /{vocabulary.verify} on a recent {vocabulary.note}
to confirm upgraded skills work correctly in practice.

---

不変条件

/upgrade は自動で実装しません。 アップグレード計画は必ず最初にユーザーへ提示します。どのアップグレードを適用するかは、ユーザーが決定します。これにより、システムが人間の理解なしに自らを変更するという、認知を外部委託してしまう失敗モードを防ぎます。

すべてのアップグレードは助言にとどまります。ファイルの所有者はユーザーです。

---

エッジケース

改善点がない場合： 確認したスキルの数とともに、「すべてのスキルは現在のベストプラクティスを反映しています。アップグレードは不要です。」と報告します。

生成マニフェストがない場合： すべてのスキルをバージョン 0（世代状態不明）として扱います。手法を現在のナレッジベースと比較します。これは問題ありません。コンサルテーションでは、バージョン番号ではなくアプローチについて検討するためです。

スキルがユーザーによって変更されている場合： 並べて比較した内容を提示します。ユーザー版を維持する、カスタマイズとアップグレードを統合する、（アーカイブしたうえで）置き換える、という 3 つの選択肢を提示します。黙って上書きしてはいけません。

ops/derivation-manifest.md がない場合： すべての出力で汎用語彙を使用します。

プラグインのナレッジベースを利用できない場合： ナレッジベースの参照には Ars Contexta プラグインが必要であることを報告します。プラグインに同梱されている methodology/ ディレクトリと reference/ ディレクトリがない場合、/upgrade はスキルを評価できません。

ユーザーがアップグレードを一貫して拒否する場合： これはエラーではなく、シグナルです。その傾向を記録します。ユーザーのドメインにナレッジベースの推奨事項が合っていない可能性があります。複数回の /upgrade 実行にわたって続く場合は、ops/observations/ に記録します。

修正内容がユーザーによる変更と競合する場合： ナレッジベースが単なる拡張ではなく修正を特定した一方で、ユーザーがスキルを変更している場合は、競合を明確に説明します。元のアプローチが間違っていたために、ユーザーがスキルを変更した可能性があります。その修正によって、すでに問題が解決していることもあります。両方を提示し、ユーザーに判断を委ねます。

複数のスキルに同じ変更が適用される場合： 同じナレッジベースの改善が複数のスキルに適用される場合（新しい検索パターンなど）、スキルごとに重複して列挙するのではなく、複数のスキルに影響する単一の概念上の変更として提示します。