docs: document single-path sync discipline

AGENTS.md

@@ -2,6 +2,12 @@
 
 UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文件是项目顶级索引，也承担 `scripts/cli.ts` 的 CLI 使用说明入口。
 
+## Critical Git / Multi-Repo Sync Rule
+
+- UniDesk 同时存在 main server、D601 `~/cq-deploy` 和其他 provider worktree 等多个开发/部署实例；Git remote 是长期 source of truth，本地部署实例只能视为运行副本或缓存。
+- 任何需要保留的代码、文档或配置变更，在完成必要自测/部署验证后必须立刻按 `git-spec` 提交并 push 到 remote；禁止让未推送的本地修改成为部署真相或后续任务依赖。
+- 提交前必须用 `git status` 和 `git diff` 区分并只提交当前任务相关文件，保留并避开并行任务产生的无关修改；长期规则见 `docs/reference/arch.md`。
+
 ## Critical Provider Gateway Upgrade Rule
 
 - `src/components/provider-gateway` 有任何代码或行为变更时，必须在同一变更集中递增 `src/components/provider-gateway/package.json` 的版本号，并在升级后通过 frontend 或 `debug health` 确认目标节点上报新版本；权威规则见 `docs/reference/provider-gateway.md`。

docs/reference/arch.md

@@ -64,6 +64,16 @@
     - All state changes are reported to the main server in real time by Provider Gateway
     - The main server writes state updates to PostgreSQL, completing the unified closed loop
     - Pipeline workflow control follows the OA event-flow model: OA is the only control bus, factual node events remain policy-neutral, and runner/monitor/frontend/CLI actions are represented as OA events; detailed constraints live in `docs/reference/pipeline-oa-event-flow.md`
+  - Single Authoritative Path Discipline
+    - Every durable capability must declare one authoritative data, control, event, or network path in reference docs, API contracts, health output, and E2E checks; frontend, CLI, worker, and service code must consume that path directly.
+    - Hidden fallback is forbidden. A service must not silently answer from local JSON, transcripts, in-memory state, stale task caches, direct host URLs, old service IDs, alternate proxies, local direct internet, or legacy event streams when the documented path is unavailable.
+    - Failure must be explicit and observable through HTTP status, response body, `/health`, diagnostics, frontend degraded state, or test output. If temporary compatibility is unavoidable, it must be documented as a bounded migration or degraded mode with a visible status marker, validation gate, and removal condition.
+    - Migration bridges may normalize legacy facts into the authoritative bus or table, but must not become a second source of truth or keep read-time dual-path fallback after the authoritative path is ready.
+  - Multi-Repo Deployment Sync
+    - The main server repository, D601 deployment tree, provider-local worktrees, and other live copies are working or deployment instances; the Git remote is the long-term project source of truth.
+    - Any source, document, or persistent configuration change intended to survive the current task must be committed and pushed to the remote promptly after required self-tests or deployment validation, following `git-spec`.
+    - Live deployment should run from a known commit or from a change set that is immediately committed and pushed; local-only hotfixes must not become the implicit dependency for later tasks.
+    - Secrets, tokens, generated runtime state, and node-local env files stay outside Git, but their required contract, storage location, and recovery path must be documented so pushing source changes is not blocked by runtime-only data.
   - Critical Task Deployment Principles
     - Single-point components such as the database, core scheduler logic, and API gateway are deployed on the main server
     - The high-availability environment of the main server ensures the critical scheduling path never breaks