Concept Registry — 判断基準の型とライフサイクル

Companyの2つのRegistryのうち、Conceptはチームで再利用する判断基準を扱います。このページでは、根拠を付けて提案し、人間がレビューしてpublishedにするまでの操作と、採用後の読み方を説明します。Session agentはaachat/teams/<team>/concepts/の投影YAMLを読み、編集後にchat registryで提案します。

kind — Vision・Issue・Policy

Conceptのkindは3種。最初に「どの問いへ答えるConceptか」で選ぶ。kindは内容の役割だけを表し、後述の意味軸（guidance_strength等）はkindから自動では決まらない。

意味軸 — 6種

Conceptにはkindとは独立に6つの意味軸がある。新規ConceptのYAMLは scope（domain・tags）・abstraction_level・time_horizon・guidance_strength・maturity を必須で指定する。policy = governing のようなkindとの自動対応はなく、review件数からの推測もしない。

governing + established は標準前提。governing + provisional は必ず考慮した上でsourceや最新レビューを確認する。governing + exploratory は必ず表面化させるが盲従しない。governing同士が矛盾する場合や未解決のconcernがある場合はスコアで勝者を決めず、リンク・出典・レビューを読んで衝突を明示する。

revisionモデル

Conceptは不変のrevisionの積み重ねである。current revisionを直接書き換えることはなく、変更は常に新しいrevisionの提案として残る。

• revisionの status は pending / published / declined の3つ
• 1つのConceptにつきpending revisionは常に1件まで。既存のpendingがある間は新しいproposalを出せない
• publish / declineは人間（teamのOwner/Admin）だけが行える。agentは提案までしかできない
• declineには理由が必須。次のsessionはその理由を読み、基準を較正してから再提案するかを判断する
• revision作成後の内容は不変。表現・出典・scope・時間軸を変える場合も新しいrevisionを積む

title は80文字、description は300文字までの入口であり、詳細な根拠は出典（下記）を通じて読む。要約ではなく入口として書く。

レビュー

published / pendingどちらのrevisionにも endorse（賛同）・concern（懸念）の2種のレビューを付けられる。concern はコメント必須（endorse は任意）で、解決ノート付きでresolveできる。published revisionにopenな concern があっても前提として読んでよいが、そのConceptに強く依存する判断では aachat_concept_reviews でcurrent revisionのコメントを確認し、concernの存在を明示する。review投稿はaachat_concept_reviewを使い、projected concepts/_index.yamlはopen_concern_countだけを持つ。

Concept間のリンク

Concept同士は8種の有向関係でつながる。

リンクにも candidate / accepted / retired / rejected のライフサイクルがある。agentはConcept YAMLのlinkを編集しchat registry submitすることで candidate として提案でき、acceptして初めてConcept Mapや判断で有効な関係として扱われる。accept / reject / retireは人間（teamのOwner/Admin）だけが行える。

published Conceptが今後の判断を誤らせる場合、agentはaachat_concept_removal_proposeでarchive案をReview queueへ送れる。accepted LinkはConcept YAMLから対象Linkを外してchat registry submit --reasonするとretire案になる。承認されるまでMapは変わらず、承認後もConceptはarchive、Linkはretireとして履歴が残る。

提案時の類似ガード（similarity gate）

新規Conceptのchat registry submitは登録前に既存Conceptと自動で照合される。類似があると登録されず、similar_found として返る。

• published の類似 — 既に判断基準として存在する。取り下げるか、関係があればリンク提案やレビューに切り替える。継続的なギャップを示す反証なら issue + contradicts リンクを検討する
• declined の類似 — 過去に人間が却下している。却下理由（status_reason）を読み、同じ提案を繰り返さない
• pending の類似 — 誰かのrevision proposalがレビュー待ち。重複提案しない
• 権限のない pending / declined の一致は内容やIDを返さず、hidden_match_count だけを返す
• 本当に別物だと判断した場合だけ、返ってきた proceed_token を付けて再送すると登録できる

出典（source）

提案は出典付きで出す。種類は5つ。

Session agentの提案では最低1件は--projectで指定したProjectに属する出典を指定し、他のProject出典も同じTeam内のSession coverageに含める。出典の可用性は accessible / restricted / unavailable の3段階で示され、restricted なsourceの中身を推測しない。unavailableは参照先を現在解決できない状態で、削除やSession coverageの変更などを確認する。

アーカイブ / 復元

Conceptはアーカイブ・復元できる。この操作はWebUI/人間の操作であり、agent向けMCP toolには含まれない。archivedなConceptやpublished contentを持たないConceptへ新しくリンクしない。

Concept Mapでの自由配置

WebUIのConcepts画面はマップビューを持ち、カードの位置（free_position）は人間の操作、またはagentがConcept YAMLを編集してchat registry submitすることで動かせる。配置は共有のsoft contextであり、近いConcept同士の位置は関連を検討する手掛かりにはなるが、source・typed link・意味軸と矛盾する場合はそちらを優先する。配置だけに現れる関係を事実として断定せず、重要そうならリンク提案の候補として扱う。

根拠付きのConceptを提案する

まずTeam sidebarのConceptsを開き、既存のConceptとReview queueを確認します。同じ方針やpendingの改訂がある場合は、その内容とレビューを読んで重複を避けます。提案前にCompanyの権限表を確認してください。以下は、Projectの書込権限とcoverageを持つSession agent向けの手順です。

例ではacme/help-center Projectのdocs/research/support-friction.mdに、利用者が答えを見つけられなかった事実と改善理由が記録されているものとします。自分の実在するTeam/Project、document kind、doc IDへ置き換え、出典を読んで内容を合わせます。架空の出典をそのままsubmitしないでください。

chat registry refresh --allを実行してconcepts/_index.yamlを読んだ後、新しいaachat/teams/acme/concepts/customer-self-service.concept.yamlへ次の全文を保存します。

format: aachat.team-concept/v1
id: null
kind: policy
title: Make answers easy to find
description: Prefer clear, searchable help before adding support channels.
scope:
  domain: product
  tags:
    - support
abstraction_level: directional
time_horizon: enduring
expires_at: null
guidance_strength: guiding
maturity: provisional
position: null
sources:
  - kind: shared_document
    project: "acme/help-center"
    document_kind: research
    doc_id: support-friction
restricted_source_count: 0
links: []

id: nullは新規登録を表します。新規Conceptにはposition: nullとlinks: []が必要です。位置とリンクはpublish後に別の操作で変更します。enduring以外の時間軸なら、将来の有効期限を引用符付きのRFC3339日時で指定します。入力するsourceは1〜20件で、restricted_source_countは新規では0です。

workspaceルートから次を順に実行します。

chat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
chat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center
chat registry refresh --all

checkが検証するのはローカルYAMLで、出典の存在やserver権限の保証ではありません。planが意図した単一操作であることを確認します。submitの提案受付後、Team Owner/AdminがConceptsのReview queueで出典と差分を読み、publishまたは理由付きdeclineを判断します。受付は採用ではありません。

投影YAMLはpublished currentだけを表します。提案後に旧本文へ戻ることや、新規pendingの本文がindexに現れないことを理由に再提案しないでください。結果のreceiptとReview queueを確認します。人間のpublish後にrefreshして、現在の本文が採用された内容になったことを確認します。

改訂と位置変更を分ける

既存Conceptはindexのfileが示すファイルをrefreshして編集します。たとえば説明を改善するときはdescriptionを変更し、他の必須フィールドと既存IDを保ったまま上のcheck → plan → submitを使います。意味・出典・scope等の改訂は新しいpending revisionになります。既にpendingがあれば先にその採否を確認します。

位置だけを変えるときは、既存ファイルのposition: nullまたは現在のpositionを次に置き換え、それ以外のフィールドを変えません。この抜粋だけをファイル全体として保存しないでください。

position:
  x: 240.0
  y: 120.0

同じcheck → plan → submit → refreshを実行します。positionだけの変更は直接反映され、Conceptの意味を承認したことにはなりません。座標は有限値で各軸-1000000〜1000000です。意味と位置を同時に編集するとmixed_editになるため、分けて送信します。

人間として接続済みrepoから提案する

Team projectionがaachat statusでhealthyであることを確認してから、同じYAMLに対して次を使います。

aachat registry check aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry plan aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml
aachat registry refresh --all

このCLIには--projectや--proceed-tokenはありません。Teamはrepo connectionから決まり、sourceに書いたProjectへのアクセスはserverが確認します。Owner/Adminがsubmitしても意味の変更は提案であり、publishは別の判断です。外側CLIでpositionをnullへクリアする操作は未対応です。また、accepted Linkの削除はagentのretire提案とは異なり、人間のretire操作としてOwner/Adminと--reasonが必要です。

出典とレビューを実際に読む

Concept MapのカードのメニューからSourcesを開き、出典を辿ります。カードを開いた詳細では、現在の内容、レビュー、Historyを確認できます。Review queueのpending内容と、現在publishedの内容を区別して読みます。たとえば上の方針がpublishedでも、「検索しにくい言語が残る」というopen concernがあるなら、全利用者が自己解決できるという事実には言い換えません。

restrictedは閲覧権限がない出典です。権限を持つ人間に必要な根拠の確認を依頼し、内容を推測しません。unavailableは参照先を現在解決できない状態です。削除やSession coverageの変更を確認し、読める根拠への改訂を検討します。WebUIでの改訂はすべての出典へアクセスできることが必要です。Session agentのYAML改訂ではrestricted_source_countを保持し、読める出典だけを編集します。serverは読めない出典を継承し、合計20件までの上限を確認します。indexのopen_concern_countだけでは懸念の内容は分からないので、コメントまで読みます。期限切れは採用履歴の削除ではなく、現在の判断文脈から外れる状態です。

Conceptの出典モデルとRegistry YAMLのsourcesが受け付けるのはshared_document、session、repository、external、human_decisionの5種類で、project_messageをYAMLへ書くことはできません。既存の投影で表示されない出典を自分で再構成せず、WebUIで確認してください。Session agentの提案はexternalやhuman_decisionだけではProject出典の条件を満たしません。

YAMLの制約と復旧

UTF-8・LF改行を使い、未知のキー、重複キー、タブ、anchor、alias、merge key、explicit tagを使いません。UUID、日時、ファイル参照は引用符付きで保ちます。新規は意味のあるASCII小文字slugとid: nullを使い、既存のIDや割り当てパスを改名しません。_index.yamlは生成物なので編集しません。1回のsubmitは1ファイル・1操作です。保存だけではserver mutationにならず、ファイル削除もConceptのarchiveにはなりません。

類似ガードの再送は、返された実際のtokenを使います。

chat registry submit aachat/teams/acme/concepts/customer-self-service.concept.yaml --project acme/help-center --proceed-token '<returned-proceed-token>'

競合時だけ、必要なローカル案を別の場所へ保管してから、対象ファイルを明示して破棄します。

chat registry refresh aachat/teams/acme/concepts/customer-self-service.concept.yaml --discard-local

このコマンドはローカル変更を捨てます。currentを読み直して必要な差分だけを再適用し、check → plan → submitへ戻ります。接続済みrepoならchatをaachatに置き換えます。通常のrefreshはdirtyファイルを勝手に上書きしません。結果不明の再送ではCLIが保持するinflight情報から先にserverの結果を照合するため、そのファイルや内部stateを編集・削除しないでください。

関連ページ

• 2層の概要と依頼の仕方: company
• Entityの型とライフサイクル: company
• 用語: glossary