Merge pull request 'Pin the documents gitlink to the delivery lessons; align gate guards' (#9) from feature/pin-documents-lessons into main

.task/delivery-mechanism.md

@@ -27,3 +27,4 @@
 | 同步前验收 | 428628ffe2a1b73a86299716853f52abdbd16291 | 6fa07f3d15ad4a59f11a53cabc39c5edf3bba2bf | 2026-09-30T03:35:08Z |
 | 同步前验收 | 1e08eb6ba22c82a1e87afbabe9a15f3e0a46a671 | ccddcc2b2b245745a38381cf50cdea3f39b45e5b | 2026-09-30T03:43:26Z |
 | 同步前验收 | 20727a8fd3adeafee6fb37383948e2a9c5a004b0 | c2da46e4d2afbf41bce34dece2d04d2bcaa59b98 | 2026-09-30T03:47:24Z |
+| 同步前验收 | 8f7cf2d9b9f45ab7c498b753e436e38fbc7726b1 | 7856d980dae4ee37e0661ce1917a722a41fd2c14 | 2026-09-30T03:49:32Z |

.task/feature-pin-documents-lessons.md

@@ -0,0 +1,25 @@
+# feature/pin-documents-lessons 任务卡
+
+任务主记录：<PR 链接，task-finish 时填写>；状态：进行中；owner：weichen
+
+## 基线与授权
+
+- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 8f7cf2d9b9f45ab7c498b753e436e38fbc7726b1
+- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-pin-documents-lessons（worktree）；分支：feature/pin-documents-lessons
+- 授权与交付终点：<本次允许的动作与终点；未授权事项写明>
+
+## 目标与非目标
+
+<预期结果、受影响入口/模块/契约；明确不做什么。>
+
+## 同步记录
+
+| 节点 | sync_base_sha | tested_head_sha | checked_at |
+|---|---|---|---|
+| 启动 | 8f7cf2d9b9f45ab7c498b753e436e38fbc7726b1 | 8f7cf2d9b9f45ab7c498b753e436e38fbc7726b1 | 2026-09-30T03:49:31Z |
+
+## 结果与验证（完成后填写）
+
+- 结果：
+- 验证：
+- 影响与剩余项：

scripts/task.sh

@@ -12,26 +12,28 @@ width() { python3 -c 'import sys,unicodedata;print(sum(2 if unicodedata.east_asi
 cmd_precheck() {
   need_repo
   git fetch -q origin "${TARGET_BRANCH}" 2>/dev/null || true
-  local branch head rmain dirty sub_dirty
+  local branch head rmain dirty sub_drift sub_uninit
   branch=$(git rev-parse --abbrev-ref HEAD)
   head=$(git rev-parse HEAD)
   rmain=$(git rev-parse --verify -q "origin/${TARGET_BRANCH}" 2>/dev/null || echo "$head")
   dirty=$(git status --porcelain | { grep -v '^.. \.zcode/' || true; } | wc -l)
-  sub_dirty=$(git submodule status --recursive 2>/dev/null | { grep -cE '^-|^\+|^U' || true; })
+  sub_drift=$(git submodule status --recursive 2>/dev/null | { grep -cE '^\+|^U' || true; })
+  sub_uninit=$(git submodule status --recursive 2>/dev/null | { grep -cE '^-' || true; })
   local behind ahead
   behind=$(git rev-list --count "HEAD..origin/${TARGET_BRANCH}" 2>/dev/null || echo 0)
   ahead=$(git rev-list --count "origin/${TARGET_BRANCH}..HEAD" 2>/dev/null || echo 0)
   echo "[repo]   branch=${branch} head=$(echo "$head" | cut -c1-10)"
   echo "[remote] origin/${TARGET_BRANCH}=$(echo "$rmain" | cut -c1-10) ahead=${ahead} behind=${behind}"
-  echo "[tree]   $([ "$dirty" -eq 0 ] && echo clean || echo "dirty(${dirty})") submodules_dirty=${sub_dirty}"
+  echo "[tree]   $([ "$dirty" -eq 0 ] && echo clean || echo "dirty(${dirty})") submodules_drift=${sub_drift} uninit=${sub_uninit}"
   local wt merged
   wt=$(git worktree list | tail -n +2 | wc -l)
   merged=$(git branch --merged "origin/${TARGET_BRANCH}" 2>/dev/null | { grep -vE 'main|master|\*' || true; } | tr -d ' +')
+  [ "${sub_uninit:-0}" -gt 0 ] && echo "[warn] ${sub_uninit} 个子模块未初始化——构建/测试前需物化（不阻断写入）"
   echo "[worktrees] linked=${wt}"
   [ -n "$merged" ] && echo "[recycle] merged un-recycled branches: $(echo $merged)"
   echo "[required-reading] core/baseline.md, workflows/delivery.md §1$([ "$dirty" -gt 0 ] && echo ", standards/collaboration.md（树脏=他人或未收尾现场，不得写入）")"
   echo "[R0] $(echo "$rmain" | cut -c1-10)（完整：$rmain）"
-  if [ "$dirty" -gt 0 ] || [ "$sub_dirty" -gt 0 ]; then
+  if [ "$dirty" -gt 0 ] || [ "${sub_drift:-0}" -gt 0 ]; then
     echo "[verdict] SHARED_WORKSPACE_BUSY — 工作树不干净，不得写入；先收尾或经 owner 确认"
     exit 3
   fi
@@ -47,7 +49,8 @@ cmd_start() {
   local name="${1:-}"; [ -n "$name" ] || die "usage: task.sh start <feature|fix|hotfix>/<slug>"
   echo "$name" | grep -qE '^(feature|fix|hotfix|release)/[A-Za-z0-9._-]+$' || die "branch name must match (feature|fix|hotfix|release)/<slug>"
   git fetch -q origin "${TARGET_BRANCH}" 2>/dev/null || true
-  [ "$(git status --porcelain | grep -v '^.. \.zcode/' | wc -l)" -eq 0 ] || die "dirty tree — resolve first (precheck verdict BUSY)"
+  [ "$(git status --porcelain | { grep -v '^.. \.zcode/' || true; } | wc -l)" -eq 0 ] || die "dirty tree — resolve first (precheck verdict BUSY)"
+  [ "$(git submodule status --recursive 2>/dev/null | { grep -cE '^\+|^U' || true; })" -eq 0 ] || die "submodule drift/conflict — resolve first (precheck verdict BUSY)"
   git merge-base --is-ancestor "origin/${TARGET_BRANCH}" HEAD || die "local ${TARGET_BRANCH} behind origin — pull --ff-only first"
   local rmain slug wt
   rmain=$(git rev-parse "origin/${TARGET_BRANCH}")