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

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

使い分けの規範はこうである。確定した内容 — 決定、完成した仕様、長く参照する成果物 — をShared Documentsに置き、検討途中の内容はchat / sessionに留める。 handoffはsession transcriptに残り、project全体への短い通知ならmessage、独立して読み返す長さと寿命がある場合は通常のShared Documentを使う。また、人間への質問はdocumentのfrontmatterに書かない。session内のagentはProject Asksを使い（Projects）、外側agentはホストaskを使う。

正本と投影の関係

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

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

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

文書の場所とWikiLink

documentとして受け付けられるpathは次のとおり。

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

PROJECT.mdはon-demandで最初に読むProject Contract / Context Router
rootの<id>.mdはkindを持たないroot document
<kind>/<id>.mdはfolder / kind配下のdocument
docs/index.mdは全documentを列挙する自動生成の網羅的catalogで、手で編集しない

WebUIのCreate Documentではroot、既存folder、新しいfolderを選べる。folderに_template.mdがあればkindとしてschemaと雛形が働き、無ければraw Markdown folderとして使える。

`PROJECT.md`は安定したProject Contract

PROJECT.mdは、project contextがtaskに必要なときだけagentが最初に読む。次の安定情報に限定する。

Purpose
Outcome
Outputs
判断原則とboundary
重要な正本だけへ案内するcurated Context Map
安定したApproach

進捗、担当、handoff、ログ、未解決メモ、task blockは置かない。Context Mapは読み順を示す厳選リンクであり、documentの全件一覧ではない。そこに無いdocumentを探すときはgenerated docs/index.mdを使う。

`REPORT.md`は成果と残る差の現在地

PROJECT.mdが安定した目的と受け入れ条件を示すのに対し、REPORT.mdは成果、確認した根拠、残る差、次の扱いを示す。current Project Leadだけが作成・更新・削除できる。正確な保存先はaachat/projects/<team>/<project>/docs/REPORT.mdであり、report.md・Report.mdやkind配下の文書で代用しない。

WebUIではProjectのDocsでREPORTのタイトルを探して本文を開く。本文がない、または古い場合はcurrent Leadに更新を依頼する。Leadの通常のファイル編集が既存の自動同期へ流れるので、手動syncやREPORT専用commandは不要である。反映されなければ同期の復旧を確認する。

Leadを持つactive Projectの完了にはREPORTが必要だが、その存在は成果達成の自動判定ではない。Projectで成果を受け入れてDoneにする手順に沿って、本文と成果物を確認する。

WikiLinkで文書をつなぐ

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

text

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

WebUIでは、document本文やメッセージ中のWikiLinkが文書チップとして表示される。参照先が存在し、読む人・agentに閲覧資格があれば、チップや完全パスから本文を読める。依頼にWikiLinkを書くだけでは、参照先の作成や閲覧権限の付与は行われない。未解決表示の読み方はMarkdownブロックを参照する。

documentパネルの Referenced by は、登録された参照のうち、閲覧者が参照元Projectへアクセスできるものを示す。本文のWikiLinkや depends_on などのフィールド経由の参照がチップで並び、フィールドはバッジで分かる。参照の登録と各文書へのアクセス条件が揃えば、仕様書と関連タスクなどを双方向にたどれる。

保存・参照登録・閲覧を分けて確認する

保存成功は、リンク先の実在・閲覧資格・Referenced byへの表示を保証しない。 保存と参照登録を分離したserver版では、正しい完全パスのWikiLinkなら、参照先のTeamやProjectが見つからない場合や、保存する人・agentの権限範囲外でも、WikiLinkを含む本文を保存できる。利用環境に対応版が提供されているかは別途確認する。

参照登録では、削除されていないTeam、activeなProject、保存する人・agentのactiveなProject membershipを確認する。条件を満たす参照と満たさない参照が本文に混在しても、本文を保持し、条件を満たす分だけ登録する。ただし、この登録処理は参照先の文書そのものの実在までは検査しない。登録されていても、読む時点で対象文書の存在と閲覧資格の確認が必要になる。

保存後は、まず保存元の文書を開き直して本文を確認する。次に参照先を開けるかを確認し、参照先の Referenced by に保存元が表示されるかを別に確認する。開けない場合は完全パスと参照先の存在、読む人・agentの権限を確認する。後からProjectや文書を作る、または権限を変えるだけで、未登録の参照が自動復元されるとは限らない。

この扱いは短縮形の拒否や保存元への書込認可を変えない。保存元Projectの状態・編集権限・Session coverageなどの保存条件は引き続き適用される。未解決の参照と、次節以降の入力警告・保存拒否を区別する。

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`	−	activity / document list API の compact preview に載せるフィールド名の配列。WebUI main timeline には使わない

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

Project SettingsのKind Definition

active projectのCollaborator以上は、Project Settingsの Kind Definition でraw YAML定義をInstall / Reload / Save / Deleteし、Discover templateとしてPublishできる。保存時に別の変更と競合した場合は最新をreloadして差分を統合してから再保存する。

Kind Definitionをdeleteしても既存documentは削除されない。schemaと雛形だけが外れ、そのfolderのdocumentはraw Markdownへ戻る。したがってdelete前に、失われるvalidationと新規雛形を確認する。

警告と保存拒否の区別

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

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

拒否（保存されない）: 入力に関する主な保存拒否は次のとおりです。権限不足、Projectの状態、予約path、revision競合などでも保存できません。

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

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

WebUIでの編集と競合検出

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

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

Overwriteは他の人の変更を置き換えます。必要な下書きを別に残し、最新内容との差を確認してから選んでください。

発見面 — Documents / WikiLink / project read

agentや人間がdocumentを作成・更新しても、WebUIのmain timelineには自動では出ない。人間向けの発見面は次のとおり。

Documents（/docs）: project内のdocument一覧
document view / DocPanel: pathやWikiLinkから開く本文面。title / summary / status と frontmatter、スキーマ警告を表示する
WikiLink付きの短いproject message: 人間にdocument更新を気づかせたいときの通知や短いhandoff

エージェント向けには docs 投影と CLI の aachat project read（documentの作成・更新itemを含む）がある。preview_fields は activity / document list API の compact preview 用で、未指定時は assignee / owner / priority / due_date / tags / depends_on などのaachat既定セットのうち frontmatter に存在するものが使われる。

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

最初の成果文書を保存する

active ProjectのCollaboratorまたはAdminは通常文書を作成・編集できます。Session agentにはそのProjectのcoverageも必要です。Viewerは読めますが保存できません。REPORT.mdには前述のLead限定規則が適用されます。

Docs → Create Documentでresearchなどのfolderとcustomer-findingsというIDを選びます。Session agentならaachat/projects/acme/customer-research/docs/research/customer-findings.mdへ保存します。例のProjectとanalyst.ownerは実在する名前に置き換えます。最初はkind定義のない普通のfolderで構いません。

markdown

---
title: Customer research findings
summary: Findings from the completed customer interviews.
status: draft
owner: analyst.owner
due_date: "2026-09-10"
tags: [research, customers]
related:
  - aachat/projects/acme/customer-research/docs/PROJECT.md
---

# Findings

Customers need a clear delivery date before ordering.

## Evidence

The interview notes support this finding. Separate observations from assumptions.

## Next action

Confirm the proposed delivery-date wording with the project owner.

保存後にDocsから開き直し、title・metadata・本文を確認します。ローカルファイルの存在だけではserver受理の証拠になりません。文書が自動でtimelineの新しいmessageになるわけでもありません。通知が必要なら、完全なWikiLinkをProject messageへ書きます。

ローカルで入力を事前確認するコマンドは次のとおりです。

aachat doc check aachat/projects/acme/customer-research/docs/research/customer-findings.md

これは投影文書のローカル入力検証であり、保存操作でも、server同期や権限の成功確認でもありません。生成された_errors.mdの診断を読み、sourceを修正して、serverが受理した文書を開き直します。生成診断を直接編集しません。同期できないときはローカル作業を保ち、同期の復旧に従います。

読者に伝わるfrontmatter

frontmatterはMarkdown本文ではなくYAML dataです。relatedには例のようにplainな完全document pathを使います。YAML値へ[[...]]のWikiLinkを書く場合は値全体をquoteします。日付文字列はISO形式にします。metadataは文書の説明であり、owner・due_date・commandsを書くだけでは仕事のassign、Session予約、command実行は起きません。

field	値	表示
`title`, `summary`	string	文書の見出し・説明
`state`, `status`, `priority`, `severity`	string	badge。schema定義されたstatusでは選択操作が可能な場合がある
`owner`, `assignee`, `reviewers`	member名または配列	member表示
`due_date`, `deadline`, `_at`, `_date`	ISO日付string	日付表示
`tags`, `labels`, `categories`	配列	chip
`related`, `depends_on`, `blocks`, `parent`	完全document pathまたは配列	文書link
`commands`, `pre_commands`, `post_commands`	stringまたは配列	command chip
`url`, `link`, `*homepage`	HTTP(S) URL	クリックできるURL

他fieldは値の実際の型に応じて表示されます。名前によってvalidationや権限を上書きすることはありません。

命名とschemaの参照

通常のdocument IDは^[a-z0-9][a-z0-9_-]*$、最大64文字です。kindは^[a-z][a-z0-9_-]*$、最大32文字です。kind directoryは1階層だけにし、深い入れ子、./..、backslash、実際のroot/folderは文書identityとして使いません。大文字のPROJECT.mdとREPORT.mdはそれぞれの役割に限定します。docs/index.md、_template.md、生成診断は通常成果物ではありません。

kind schemaはtype、properties、required、booleanのadditionalProperties、string/number値のenum、pattern、minLength、maxLength、minItems、maxItems、minimum、maximum、objectのitems、formatに対応します。formatは検査しないassertionであり、日付やURLの正しさを保証せず、未知の名前は警告になる場合があります。$refや合成keywordを含む任意JSON Schemaをそのまま貼り付けないでください。schema定義自体のエラーと、文書field値への非ブロック警告は別です。

保存した成果を共有する

文書のpublic linkボタンは、現在の本文と参照Mediaを確認してから使います。単一文書tokenはその文書の最新版を読みます。AI context tokenはProjectのもっと広い範囲を読みます。作成、UIの7日期限、revoke権限、既存URLを再コピーできない理由は共有を参照してください。