fix(push): stop reverting a teammate's update from HOME or a stale .teamai copy (#823)

docs/designs/data-directory-layout.md

@@ -93,7 +93,22 @@ through. Every full sync keeps only the
 entries of checkouts `git worktree list` still reports, so a deleted or
 re-created worktree's entry goes with the next full sync in any checkout. A
 state.json written before this field has no entry, so each checkout does one
-full sync after the upgrade.
+full sync after the upgrade. The user scope's pull records its one checkout,
+HOME, the same way, for push's bases alone: its fast path still reads the
+shared fields, and an install with no entry yet (upgraded, and not fully
+synced since) compares with `lastPullRev` and `lastInheritedPullRev`, which
+only HOME's pulls move and either of which may have run last, so push does not
+stop there; its first push creates the entry from `lastPullRev`, with
+`lastInheritedPullRev` as a push base, and adds the revision its sync reached.
+A project pull that inherits the user scope (`inheritUserScope`) moves HOME's
+skills, rules and agents too, so it adds its revision to that entry's push
+bases, creating the entry the same way if there is none, and leaves the entry's
+`rev` alone. So does any pull whose docs mirror or submodule update fails: it
+leaves its revision marker for the retry, but the skills, rules and agents it
+delivered are at the new revision. A full pull that holds skills or agents on a
+namespace collision writes its revision as `rev` but keeps the entry's earlier
+bases as push bases, since the held copies stay at them. Like a full pull, an
+inherited pull already synced at the team's revision writes nothing (#823).
 
 ### Why the main worktree, not `git-common-dir` (verified)
 

docs/usage-guide.md

@@ -494,7 +494,7 @@ knowledge on main is left exactly in place).
    - `.teamai/agents/` — subagent definitions (`<name>.yaml`, or legacy `<name>.md`)
    - `.teamai/env/env.yaml` — shared env vars
 
-   `teamai push` scans all of these plus your AI tool dirs, and only surfaces genuine additions or edits (already-committed content is skipped). If you rename an agent's extension (e.g. `helper.md` → `helper.yaml`), delete the old file — `teamai push` won't remove it for you, and two files with the same stem would collide on pull.
+   `teamai push` scans all of these plus your AI tool dirs, and only surfaces genuine additions or edits (already-committed content is skipped). A rule or skill under `.teamai/` that matches an older version of the team's file, as it does when your branch is behind the default branch, is not an edit either: push skips it with a warning rather than revert a teammate's update. If you rename an agent's extension (e.g. `helper.md` → `helper.yaml`), delete the old file — `teamai push` won't remove it for you, and two files with the same stem would collide on pull.
 4. **docs / hooks / mcp** are contributed by editing their file directly — they don't go through `teamai push`; a normal `git commit` + push ships them:
    - `.teamai/docs/` — team docs
    - `.teamai/hooks/hooks.yaml` — team hooks

docs/usage-guide.zh-CN.md

@@ -435,7 +435,7 @@ main 的团队知识 —— `git status` 保持干净。旧版单仓装升级后
    - `.teamai/agents/` —— subagent 定义（`<name>.yaml`，或旧版 `<name>.md`）
    - `.teamai/env/env.yaml` —— 共享环境变量
 
-   `teamai push` 会同时扫描这些目录和你的 AI 工具目录，只呈现真正的新增或修改（已提交的内容会被跳过）。如果你改了某个 agent 的扩展名（如 `helper.md` → `helper.yaml`），请手动删掉旧文件 —— `teamai push` 不会替你删除，同 stem 的两个文件会在 pull 时冲突。
+   `teamai push` 会同时扫描这些目录和你的 AI 工具目录，只呈现真正的新增或修改（已提交的内容会被跳过）。`.teamai/` 下的规则或 skill 如果与团队文件的某个旧版本一致（你的分支落后于默认分支时就会这样），也不算修改：push 会给出警告并跳过它，而不会覆盖队友的更新。如果你改了某个 agent 的扩展名（如 `helper.md` → `helper.yaml`），请手动删掉旧文件 —— `teamai push` 不会替你删除，同 stem 的两个文件会在 pull 时冲突。
 4. **docs / hooks / mcp** 通过直接编辑对应文件来贡献 —— 它们不走 `teamai push`，用普通的 `git commit` + push 即可分发：
    - `.teamai/docs/` —— 团队文档
    - `.teamai/hooks/hooks.yaml` —— 团队 hooks

skill-data/core/references/contribute-member.md

@@ -104,6 +104,13 @@ The doc lands in the team's `learnings/` and appears for teammates on their next
    to reset a team-repo clone with user changes, so commit or stash unrelated
    modified, staged, untracked, or conflicted files before retrying.
 
+   In single-repo mode, a skill or rule under `.teamai/` that matches an older
+   version of the team's file, as it does when the branch is behind the default
+   branch, is skipped with a warning that it "is an older version of" that file:
+   pushing it would revert a teammate's update. To publish an edit of it, bring
+   the current version in first (`git fetch origin && git merge origin/<default>`,
+   or copy the team's current file over it), redo the edit on top, and push again.
+
 ## After contributing
 
 - Confirm it landed: `teamai list skills` (or `teamai status`).