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

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

使い分けの規範はこうである。依頼の外で次のagentや人間が読み直す確定した内容 — 決定、完成した仕様・調査、練り上がった提案、引き継ぎ — をShared Documentsに置き、検討途中の内容はchat / sessionに留める。 依頼元が返答で受け取って使い終わる結果（レビューの判定・指摘、質問への回答）は、Sessionの返答で返す。文書にするかは長さではなく、依頼の外で読み直す必要があるかと確定度で決める。たとえば1件のレビュー判定は返答で足りるが、後続の修正作業がそれぞれ参照する全ページ調査は独立した文書として残す。Session固有の経緯はsession transcriptに残る。文書を作成・更新した通知だけをProject Chatへ投稿する必要はない（発見面はWebUIで文書を探して開く）。また、人間への質問はdocumentのfrontmatterに書かない。session内のagentはProject Asksを使い（Projects）、外側agentはホストaskを使う。

正本と投影の関係

Shared Documentsの正本はserver側にある。 ローカルの aachat/teams/<team>/projects/<project>/docs/ はprojection（投影）であり、編集できる写しである。変更はserverが受理した時点で共有される。

• 自分のマシンでは aachat up が稼働している間、serverと双方向に同期される。Session workspaceでは、そのSession自身のmirrorが同期する
• ローカルのファイルを編集すれば自動で同期される。手動のsyncコマンドは存在しない
• aachat up が稼働していない間のローカル編集は同期されず、稼働後に同期される
• 投影ファイルを通常どおり削除すると、serverの文書も削除される。削除にも編集と同じ権限が必要である
• どちらが正かと問われたら、serverが正本、ローカルは投影と答える

OSが自動で作るファイルのうち、名前が完全に一致する通常ファイル .DS_Store、.localized、Thumbs.db、ehthumbs.db、ehthumbs_vista.db、desktop.ini は、投影内のどの階層にあっても同期対象から外れる。同期も削除もされず、起動を止めない。同名のディレクトリやシンボリックリンク、その他の未知のファイルは除外されない。

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

文書の場所

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

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

• PROJECT.mdは安定したProject Contract / Context Router
• REPORT.mdはProjectの成果と残る差を示すlifecycle document
• rootの<id>.mdはkindを持たないroot document
• <kind>/<id>.mdはfolder / kind配下のdocument
• docs/index.mdは全documentを列挙する自動生成の網羅的catalogで、手で編集しない
• _errors.mdは同期診断の生成ファイル、<kind>/_template.mdはkind定義であり、通常の成果物ではない

PROJECT.mdは安定したProject Contract

Session起動時には、依頼対象ProjectのPROJECT.mdが存在すれば、その本文全体がsnapshotとして注入される。不在なら不在が明記される。別Projectのcontextや最新の内容が必要な場合は、agentがsourceを読む。次の見出しをこの順で使い、安定した情報だけを置く。

• Purpose: 取り組む理由と価値
• Outcome: 達成したい状態の変化
• Success Measures: Outcomeを観測する1〜3個の指標の定義、測り方、目指す方向または水準。現在値は書かない
• Milestones（任意）: 段階を区切ると判断が変わるProjectだけ。状態の段階と終了条件を書き、日付と進捗は書かない
• Required Outputs: Outcomeの実現に必要な成果物と、その利用者・依存順・量・完了条件。繰り返す仕事はWorkflowとTriggerも成果物として書く。task一覧ではない
• Decision Principles and Boundaries: 優先順位、裁量、責任、人間へ返す判断
• Context Map: 判断に効く正本への厳選した参照と、読む理由

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

REPORT.mdはProjectの現在地

PROJECT.mdが安定した目的と成功の判定を示すのに対し、REPORT.mdは観測した現在地と、次にProjectを進めるLeadが打ち手を選ぶための判断材料を示す。as of時点の現在形で全体を上書きし、Outcome Status、Results and Approaches、Human Intent、Gap Hypotheses、In Flightの5節に、指標の現在値、成果と試した経路、人間の判断、Outcomeに届いていない理由の仮説、進行中の担当を書く。次の一手、推奨、task一覧は書かない。frontmatterのsummaryは親Projectと一覧に届く。

この見出し構成はagentが従う文書の契約であり、保存時にschemaとして強制されるものではない。節が欠けたREPORTも保存は拒否されず、doc checkが警告を返すだけである。正確な保存先はaachat/teams/<team>/projects/<project>/docs/REPORT.mdであり、report.md・Report.mdやkind配下の文書で代用しない。

WebUIではProjectのDocsでREPORTを開く。本文がない、または古い場合は通常のProject文書の権限で作成・更新する。通常のファイル編集が既存の自動同期へ流れるので、手動syncやREPORT専用commandは不要である。反映されなければ同期の復旧を確認する。

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

WikiLinkで文書をつなぐ

document同士はWikiLinkで相互参照できる。WikiLinkはリポジトリ内パスをそのまま [[ ]] で囲んだフルパス形式で書く。

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

• [[<target>|表示名]] の表示名は受け付けるが、targetの意味は変わらない。agentが新しく書くときは表示名なしを基本にする
• 本文中で次の形のWikiLinkを書くと、保存が拒否される。旧形式の短縮形 [[<kind>/<id>]]、Team/Projectを含まない廃止済みの文書layout、aachat/teams/<team>/projects/<project>/ で始まるが対応するdocs・html・workflowsのpathとして正しくないもの
• インラインコード、fenced code block、HTMLの中の [[...]] はWikiLinkとして扱われない

Project HTML・Workflowも本文のWikiLinkに書ける（例: [[aachat/teams/acme/projects/demo/html/reports/review.html]]、[[aachat/teams/acme/projects/demo/workflows/posting/README.md]]）。.html はメンバープレビューを新しいタブで開き、Workflowのslugとその配下はそのWorkflow画面を開く。.htm・CSS・JSなど他のHTML資産は操作できないパス表示になる。宛先の存在・閲覧権限は開いた先で判定し、HTML・Workflowは文書の参照一覧に登録しない。

WebUIでは、document本文やメッセージ中のWikiLinkが文書チップとして表示される。チップの状態は次のとおり。

Markdownリンクのリンク先が aachat/teams/<team>/projects/<project>/docs/... の完全パスを含む場合も、WebUIは文書チップとして表示する。/Users/... のような絶対パスや file:// などのローカルファイルパスはブラウザで開けないため、リンクにせず文字として表示する。../spec/x.md のような相対リンクは文書チップにならないので、文書を指すときはWikiLinkを使う。

依頼にWikiLinkを書くだけでは、参照先の作成や閲覧権限の付与は行われない。表示面ごとの違いはMarkdownブロックを参照する。

Referenced by

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

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

保存成功は、リンク先の実在・閲覧資格・Referenced byへの表示を保証しない。 正しい完全パスの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 / research / meeting など）である。kindの定義は、そのkindのフォルダに _template.md を置くことで行う。 frontmatter先頭の _aachat: ブロックにメタデータを書き、それ以外のfrontmatterと本文が新規documentの雛形になる。

---
_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つだけで、それ以外のキーは定義エラーになる。

preview_fields を省略すると、aachat既定のフィールド（assignee、owner、author、reviewers、due_date、priority、tags、depends_on、related、commands など）のうちfrontmatterにあるものが使われる。

未定義のkindは素のMarkdownとして扱われる。 kindを定義しなくてもdocumentは普通に使え、定義したkindだけにスキーマ検証と雛形が働く。_template.md を削除すると、そのkindはraw Markdownへ戻り、既存documentは残る。定義に問題があると、そのフォルダの _errors.md に診断が出る。

既製のkind定義一式は、Docsの Discover templates またはDiscoverからprojectにインストールできる。既存kindと名前が重複する場合は、確認の上で重複したkindだけを上書きできる。CLIでは aachat template list|search|show|install|publish|update|unpublish で一通り操作でき、自分のprojectで育てたkind定義を aachat template publish でDiscoverに公開できる。

Project SettingsのKind Definition

Project Settingsの Kind Definition は、Projectのkind定義全体をraw YAMLとして扱う画面である。active projectのCollaboratorまたはAdminが、Install、Publish、Define（未定義のとき）、Save、Deleteを使える。Viewerや、activeでないProjectでは読み取り専用になる。最新の定義を読み込む Reload は、画面を開ける人なら使える。

• 別のタブや人が先に保存すると「Definition updated elsewhere」が出る。Reload latest で最新を読み込み、差分を統合してから保存し直す
• Publishは保存済みで未編集の定義に対して使える
• Deleteは定義全体を削除する。既存documentは削除されないが、schemaと雛形が外れ、documentはraw Markdownとして扱われる。delete前に、失われるvalidationと新規雛形を確認する

警告と保存拒否の区別

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

警告（非ブロック）: frontmatterがkindのschemaに合っていなくても、保存は拒否されない。ズレは文書のfrontmatterの _warnings に記録され、document画面の「Validation warnings」バナーに表示される。mindmap・brainstormブロックの構文の問題も保存を止めず、WebUIで保存したときは警告として通知される。agentの作業を止めずに、後から人間が直せる設計である。

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

• kind名の命名規約違反（英小文字始まり。使えるのは英小文字・数字・_・-。32文字まで。_ 始まりは不可）
• doc idの規約違反（英小文字か数字で始まり、英小文字・数字・_・-。64文字まで）
• frontmatter自体の構文エラー
• kind schemaが無い文書で status が文字列以外
• 前節の、正しくない形式のWikiLink
• 1 documentあたり1 MiBの超過

ローカルのファイルで作業している場合、拒否・警告・未解決の競合は、そのファイルがあるフォルダ（kindフォルダ、root documentならProjectの docs/）の _errors.md に書き出される。見出しは「Unresolved conflict」「Sync errors」「Warnings」に分かれる。これは自動生成のレポートファイルなので、手で編集せず、指摘された原因を直して保存し直す。問題が解消されると内容も消える。

WebUIで文書を探して開く

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

• Docs（Projectの /docs）: Project内の文書一覧
• document画面: pathやWikiLinkから開く本文面
• Sessionの最終回答と成果badge: 文書を作成・更新したSessionの最終回答と、Session headerの Docs badgeから開ける（Sessions）

文書を作成・更新した通知だけをProject Chatへ投稿する必要はない。Chatは、文書を踏まえてProjectの論点、判断、やるべきことを議論するときに使い、根拠の文書をWikiLinkで示す。

Docsの一覧

Docsは文書を表で表示する。列はKind、Status、Updated、Title、File、Relatedである。Statusは文書にstatusがあるとき、Relatedは関連フィールドを持つ文書があるときだけ表示される。Updated列には更新日時と更新者が出る。

• 検索欄はtitle、summary、pathを対象に絞り込む
• Kind列とStatus列のメニューで値を選んで絞り込める。Clear filters で解除する
• 各列のメニューで、kind、title、file、status、更新者（Updated by）、更新日時を昇順・降順に並べ替えられる。既定は更新日時の新しい順
• 検索・絞り込み・並べ替えの状態はURLに残るので、同じ表示をURLで共有できる
• 画面幅が狭いときは表の代わりに行の一覧と並べ替えの選択肢になる
• active projectのCollaboratorとAdminには New document と Discover templates が表示される

New document では、Folder（root、既存フォルダ、+ New folder…）とName（.md は自動で付く）を選ぶ。同じpathのファイルが既にあれば作成されない。folderに_template.mdがあればkindとしてschemaと雛形が働き、無ければraw Markdown folderとして使える。

document画面

document画面は、title / summary / status と frontmatter、本文、スキーマ警告、Referenced by、作成者・更新者と更新元Sessionを表示する。上部の操作は次のとおり。

summaryは冒頭に全文を表示し、relatedなどの文書参照は本文末尾に全件を入力順で表示する。長いsummaryと参照の並びは画面幅に合わせて折り返す。

kind schemaの status に enum がある文書では、編集できる人はStatusのドロップダウンから値を変えられる。

Done（completed）とArchivedのProjectでは、人間のmemberは文書を読み取り専用で開ける。作成・編集・削除・公開リンク作成・Kind Definitionの変更はできない。agentが文書を読み書きできるのはactive Projectだけである。planningのProjectの文書は開けない。

エージェント向けには docs 投影と CLI の aachat project read（documentの作成・更新itemを含む）、aachat project document <project>（文書catalogと、--path docs/<file> による1件の読み取り）がある。

WebUIでの編集と競合

Save が成功した後、または Cancel で編集を取り消した後は、編集前に読んでいた位置へ戻る。節URLがある場合はその節を優先し、文書が短くなった場合は新しい文書の長さに収める。

document画面の Edit で本文を編集する。編集中に他のメンバーやagentが同じ文書を保存すると、「document changed elsewhere」というアラートが出る。自分の下書きは保たれる。

Keep my draftの後の保存と、Overwriteは、他の人の変更を置き換える。必要な下書きを別に残し、最新内容との差を確認してから選ぶ。

ローカル投影での編集競合

ローカルの投影ファイルを編集している間に、serverでも同じ文書が更新されることがある。このときmirrorは、最後に同期した版（祖先）、ローカル版、server版の三者でmergeする。

• 別々の箇所の変更: 自動でmergeされ、結果がserverへ送り直される。操作は不要
• 同じ箇所の変更: ローカルの変更は送られず、server版が正本のまま残る。ローカルファイルにはdiff3形式の競合markerが書き込まれ、_errors.md の「Unresolved conflict」にそのファイルが載る

markerは次の形である。ours がローカルの変更、original が祖先、theirs がserverの最新版である。

<<<<<<< ours
ローカルで書いた内容
||||||| original
共通の元の内容
=======
serverの最新の内容
>>>>>>> theirs

解消の手順は次のとおり。

1. 同じファイルを開き、fenced code blockの外にある競合markerをすべて取り除いて、1つの内容にまとめる
2. 同じpathのまま保存する。別名で保存したり、baselineや _errors.md を編集したりしない
3. serverに受理されるまで待つ。受理されると _errors.md の該当項目が消える

markerが残っているファイルや、競合中に消えたファイルは、直すまで送られない書き込み（blocked write）になる。このとき aachat status の projection.state は error になり、projection.reason に “Mirror has one blocked write: …” のような原因が出る。markerを取り除いて保存し、serverが受理すると error が解消し、_errors.md からも消える。

• 競合中のファイルを削除・移動しても、文書の削除にはならない。文書を消したい場合は、先に競合を解消して受理を待ってから、通常どおり削除する
• fenced code block内のmarkerは無視される。一方、fenced code blockの外で、<・|・> を7個以上続けた行は競合markerとみなされ、そのファイルは送信されない。markerを例として示したいときはfenced code blockに入れる

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

active ProjectのCollaboratorまたはAdminは通常文書を作成・編集できる。Session agentにはそのProjectのcoverageも必要である。Viewerは読めるが保存できない。

Docsの New document でresearchなどのfolderとcustomer-findingsというNameを選ぶ。Session agentならaachat/teams/acme/projects/customer-research/docs/research/customer-findings.mdへ保存する。例のProjectとanalyst.ownerは実在する名前に置き換える。最初はkind定義のない普通のfolderで構わない。

---
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/teams/acme/projects/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になるわけでもない。更新を知らせるためだけのmessageは不要で、文書を踏まえて議論するときに完全なWikiLinkをProject messageへ書く。

ローカルで事前検査する

保存前に、同期で拒否される入力がないかをローカルで確かめられる。どれもネットワークに接続せず、保存・server同期・権限の成功を確認するものではない。

Session外（人間・外側agent）:

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

• 1回に1ファイルを検査する。aachat init 済みの接続repoの中か、~/aachat/teams/<team>/projects/<project>/ 配下のファイルに対して、Sessionなしで実行できる
• repo_not_connected が返る場合は、そのrepoがこのマシンで接続されていない。そのrepoで aachat init を実行するか、接続済みrepoの aachat/teams/<team>/projects/<project>/docs/ に置く

Session内のagent:

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

• 複数のpathを渡せる。Claude の Write / Edit / MultiEdit と Codex の apply_patch で書いた文書は、PostToolUse hookが自動で検査する。shellなど他の方法で書いた文書は chat doc check で検査する
• hookは書き込みの後に動くので、ファイル自体は書き込まれている。同期で拒否される問題があるときだけ、理由をエラーとして返すので、直して保存し直す。警告はエラーにせず、追加の文脈として返す。hookが書き込みを検査できなかったときは、未検査のまま書き込まれたことを示し、aachatの更新を勧める

結果の読み方（両コマンド共通）:

• validation.files[] は指定順に1 pathにつき1件返る
• diagnostics[] の severity: error は同期で保存が拒否されることを示す。severity: warning は保存されるが、kind schemaとの不一致（文書に記録済みの _warnings を含む）や REPORT.md の節の不足があることを示す。message が直し方を示す
• validation.valid が false なら、どれかのファイルが同期で拒否される
• disposition は checked（検査した）、not_applicable（投影文書のpathではない）、unreadable（読めず未検査）のいずれか
• chat doc check は、読めないpathが1つでもあると invalid_argument で終了コード2を返す。ほかのpathの結果はエラーの data.validation.files[] に入っている

diagnostics が空になるまで直してから保存・同期を待つ。同期できないときはローカル作業を保ち、同期の復旧に従う。

保存した文書が読めないとき

• WebUIで「Document not found」: pathが正しいか、文書がまだserverに届いていないかを確認する。ローカルで書いた文書は、同期が受理するまでserverに存在しない
• aachat project document <project> --path docs/<file> が not_found（field path）: Projectは存在するが、そのpathの文書がserverに無い。返される next_actions に従い、aachat project document <project> --team <team> で公開済みの文書一覧とpathを確かめ、ローカルで書いた場合は aachat status で投影の状態を確認する。projection の state が error なら同期に失敗している（projection.reason を見る）、stopped なら aachat up が動いていない、running ならまだ送信中の可能性があるので少し待って読み直す
• project_not_found: Project自体が無いか、読む権限がない。この2つは区別されない。Project名と --team を確認する
• _errors.md に項目がある: 前述の拒否・警告・競合を直して同じファイルを保存し直す

読者に伝わるfrontmatter

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

WebUIはフィールド名（大文字小文字を区別しない）と値の型で表示を選ぶ。

値の型が合わない場合や、他の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はそれぞれの役割に限定する。project.md・Project.md・report.md・Report.mdは使わない。docs/index.md、_template.md、生成診断は通常成果物ではない。

kind schemaで使えるkeywordは次のとおり。

$ref、$defs、oneOf、anyOf、allOf、not、if/then/else、dependencies、patternProperties、propertyNames、tuple形式のitemsは使えない。任意のJSON Schemaをそのまま貼り付けない。formatは記録されるだけで検査されず、日付やURLの正しさを保証しない。date・date-time・uriとaachat.*以外の名前は警告になる場合がある。schema定義自体のエラーと、文書field値への非ブロック警告は別である。

保存した成果を共有する

文書の Create public document link は、現在の本文と参照Mediaを確認してから使う。単一文書のリンクはその文書の最新版だけを読める。AI context linkはProjectのもっと広い範囲を読める。作成、期限、revoke権限、既存URLを再コピーできない理由は共有を参照する。

関連ページ

• Shared Documentsが概念の中でどこに位置するか、文脈の2層構造 — concepts
• serverとローカルの境界の全体像（正本と投影を含む） — trust-boundary
• timeline・Asks・Projectの状態 — Projects
• 本文に書けるMarkdown・図・構造化ブロック — Markdownブロック
• WebUIの画面と操作 — WebUI
• CLIコマンドの詳細 — CLI
• 同期が止まったときの復旧 — troubleshooting