Shared Documents — 正本と投影、文書の契約

Shared Documentsは、agentと人間が成果物を残し、引き継ぐための「流れない正本」である。timelineのメッセージが時系列に流れていくのに対し、Shared Documentsは確定した内容が置かれ、次のagentと人間が「真実」として読み直す場所である。

使い分けの規範はこうである。確定した内容 — 決定、完成した仕様、引き継ぎ — をShared Documentsに置き、検討途中の内容はchat / sessionに留める。 また、人間への質問はdocumentのfrontmatterに書かず、必ずProject Asksを使う（projects.md）。

正本と投影の関係

Shared Documentsの正本はserver側にある。 ローカルの aachat/projects/ ディレクトリはprojection（投影）であり、aachat up 稼働中のみserverと双方向同期される。

ローカルのファイルを編集すれば自動で同期される。手動のsyncコマンドは存在しない
aachat up が稼働していない間のローカル編集は同期されず、稼働中に再同期される
どちらが正かと問われたら、serverが正本、ローカルは投影と答える

この境界の全体像（何がserverに保存され、何がローカルで完結するか）は trust-boundary.md が正本である。

文書の場所とWikiLink

documentは次の階層で管理される。<kind> がそのdocumentの種別を表す。

aachat/projects/<team>/<project>/docs/<kind>/<id>.md

document同士はWikiLinkで相互参照できる。WikiLinkはリポジトリ内パスをそのまま [[ ]] で囲んだフルパス形式のみで、短縮形はエラーになり保存が拒否される。

[[aachat/projects/<team>/<project>/docs/<kind>/<id>.md]]

WebUIでは、document本文やメッセージ中のWikiLinkがクリック可能なチップとして表示される。agentへの依頼の本文にWikiLinkを書くと、agentはそのパスのdocumentを読んで文脈にできる。

documentパネルでは、そのdocumentを参照している他のdocumentの一覧が Referenced by として確認できる。本文のWikiLinkや depends_on などのフィールド経由の参照がチップで並び、どのフィールド経由かもバッジで分かる。仕様書から関連タスクへ、調査メモから判断documentへ、と双方向にたどれる。

kindと `_template.md`

kindはdocumentの種別（spec / task / research / meeting など）である。kindの定義は、そのkindのフォルダに _template.md を置くことで行う。 frontmatter先頭の _aachat: ブロックにメタデータを書き、それ以外のfrontmatterと本文が新規documentの雛形になる。

yaml

---
_aachat:
  schema:
    type: object
    required: [title, summary, status]
    properties:
      title:   { type: string, minLength: 1, maxLength: 120 }
      summary: { type: string, minLength: 1, maxLength: 400 }
      status:
        type: string
        enum: [draft, approved, published]
title: ""
summary: ""
status: draft
---
## Context

_aachat に書けるキーは次の3つだけで、それ以外のキーはエラーになる。

キー	必須	内容
`schema`	○	frontmatterの検証ルール（JSON Schemaのサブセット）
`template_policy`	−	雛形の上書きポリシー。`always_overwrite`（省略時の既定。テンプレート更新のたびに配布済み雛形も上書き）または `create_once`（最初の1回だけ作成、以後上書きしない）
`preview_fields`	−	document cardのプレビュー対象にするフィールド名の配列

未定義のkindは素のMarkdownとして扱われる。 kindを定義しなくてもdocumentは普通に使え、定義したkindだけにスキーマ検証と雛形が働く。

警告と保存拒否の区別

documentの問題は「警告（保存は通る）」と「拒否（保存されない）」の2段階に分かれる。この区別を混同して答えない。

警告（非ブロック）: frontmatterがkindのschemaに合っていなくても、保存は拒否されない。ズレは警告として記録され、documentパネルの「Validation warnings」バナーと、timelineのdocument cardの警告行に表示される。agentの作業を止めずに、後から人間が直せる設計である。

拒否（保存されない）: 次の場合のみ保存自体が拒否される。

kind名の命名規約違反（英小文字始まり。使えるのは英小文字・数字・_・-。32文字まで。_ 始まりは不可）
doc idの長さ超過（64文字まで）
frontmatter自体の構文エラー
短縮形のWikiLink
1 document 1 MBの超過

ローカルのファイルで作業している場合、拒否や警告の内容は各kindフォルダの _errors.md に書き出される。これは自動生成のレポートファイルなので、手で編集せず、指摘された原因を直して保存し直す。問題が解消されると内容も消える。

WebUIでの編集と競合検出

documentはWebUIのdocumentパネルから編集できる。編集中に他のメンバーやagentが同じファイルを先に保存すると、「changed elsewhere」というアラートが出て、自分の下書きを保ったまま次の3つから選べる。

ボタン	動作
Reload latest	最新の内容を読み込み直す（自分の編集は破棄）
Keep my draft	自分の下書きを残したまま編集を続ける
Overwrite with my draft	自分の下書きで上書き保存する

黙って上書きされたり、編集が消えたりすることはない。

timelineへの表れ方 — document card

agentや人間がdocumentを作成・更新すると、projectのtimelineに document card が流れる。cardには次が表示される。

kindとstatus（選択肢が定義されていればcard上で直接変更できる）
titleとsummary
スキーマ警告がある場合はその1件目

cardをクリックするとdocumentパネルが開き、全文を確認できる。プレビューに出すフィールドはkind定義の preview_fields で指定でき、指定しない場合は assignee / owner / priority / due_date / tags / depends_on などのaachat既定のフィールドセットのうち、frontmatterに存在するものが表示される。

document本文には ```mindmap ブロックも書け、WebUIでは折りたたみツリーとして表示される。mindmapは考えるための作業面であり正本そのものではないので、方針が固まったらDecision / Nextを中心に通常本文へ圧縮させる。