agentic-flow-kit 0.2.0 → 0.2.1

package/README.md

@@ -46,7 +46,7 @@ modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考
 
 **两态文件模型**：`.agents/kit.json` 记录 managed（引擎件，随包升级）与 owned（项目内容，永不覆盖）清单及 sha256；`doctor` 会校验漂移。已存在的文件 init 保守跳过（`--force` 覆盖）。
 
-**升级语义（sync）**：managed 文件三方比对（台账 sha / 磁盘 sha / 新版渲染 sha）——未改动 → 直接覆盖新版；本地已改 → 跳过并报告（`--force` 才覆盖，git diff 自查差异）；改动恰好等于新版 → 视为已最新。包内新增文件自动安装；包内已删文件仅报告不删盘；缺失的 managed 文件自动恢复。INDEX / wiki 看板等生成器目标不比对 sha，收尾重跑生成器走锚点重写。门禁模块（add-gate 装入）归项目所有，sync 永不覆盖。
+**升级语义（sync）**：managed 文件三方比对（台账 sha / 磁盘 sha / 新版渲染 sha）——未改动 → 直接覆盖新版；本地已改 → 跳过并报告（`--force` 才覆盖，git diff 自查差异；跳过件的台账保持包侧基线，后续每次 sync 持续报告，不会在下次升级被静默覆盖——消除报告的办法：`--force` 覆盖，或把本地内容改回与新版一致）；改动恰好等于新版 → 视为已最新。包内新增文件自动安装；包内已删文件仅报告不删盘；缺失的 managed 文件自动恢复。INDEX / wiki 看板等生成器目标不比对 sha，收尾重跑生成器走锚点重写。门禁模块（add-gate 装入）归项目所有，sync 永不覆盖。add-host 对已存在的宿主文件保守跳过且不入台账——后续 sync 不升级（仅报告「已存在未入台账」），要纳入包管理用 `--force` 覆盖。owned 件归项目所有、sync 永不覆盖；其台账哈希仅记账不约束，sync 每次按盘面自愈刷新（手改后无须手工对账），add-gate 接线 local-pre-commit 后同步刷新其记账。
 
 ## 设计原则
 
@@ -59,4 +59,5 @@ modules/gates/      可选门禁模块（dotnet-ca：Clean Architecture 参考
 
 - [x] v0.1.0：init（flags 模式）+ doctor + 4 宿主适配 + dotnet-ca 门禁模块
 - [x] v0.2.0：sync 升级（未动覆盖 / 已改跳过报告 + `--force` / 生成器锚点重写）+ add-host / add-gate
-- [ ] npm 发布
+- [x] v0.2.0 已发布：npm view agentic-flow-kit（npx agentic-flow-kit init 即用；默认镜像源用户需等 npmmirror 同步或 --registry npmjs）
+- [x] v0.2.1：Shipyard 回流第二笔（模板引用去死链 + owned 台账记账策略：add-gate 接线刷新 + sync 盘面自愈）+ 全项目审查修复（量化台账 fail-loud / 生成器锚点与 ENOENT 守卫 / sync 跳过件持续报告 / P4 清账 / metrics glob 词表收口）——npm publish 待执行

package/modules/gates/dotnet-ca/check-architecture.sh

@@ -78,6 +78,8 @@ if [ -z "$PY_BIN" ]; then
   violations="$violations
 - 红线 4.3 无法执行：未找到 python/python3/py（Domain 导航属性扫描依赖 Python；门禁 fail-closed，不静默放行）"
 else
+    # 2026-09-24：①python 运行期报错也 fail-closed（原只对「没装 python」兜底，脚本报错时 nav_hits 为空即放行）；
+    # ②属性匹配改全文 finditer——支持「{ 换行」与 expression-bodied（=>）形态，先剥注释防误报
     nav_hits=$(DOMAIN_ENTITIES_DIR="$DOMAIN_ENTITIES_DIR" SHARED_TYPES="$SHARED_TYPES" "$PY_BIN" - <<'PYEOF'
 import re, glob, os
 from os import environ
@@ -91,19 +93,20 @@ for f in files:
 hits = []
 for f in files:
     with open(f, encoding='utf-8-sig') as fh:
-        for i, line in enumerate(fh, 1):
-            m = re.match(r'\s*public\s+(?:virtual\s+)?([\w<>,\s\.\?]+?)\s+(\w+)\s*\{', line)
-            if not m:
-                continue
-            typ = m.group(1).strip()
-            mm = re.search(r'(?:ICollection|List|IEnumerable|IReadOnlyCollection|IReadOnlyList)<\s*(\w+)\s*>', typ)
-            core = mm.group(1) if mm else (typ.rstrip('?') if re.fullmatch(r'\w+\??', typ) else None)
-            if core and (core in names or core in shared):
-                hits.append(f"{os.path.basename(f)}:{i} {m.group(2)} : {typ}")
+        src = re.sub(r'/\*.*?\*/', '', fh.read(), flags=re.S)
+    src = re.sub(r'//[^\n]*', '', src)
+    for m in re.finditer(r'\bpublic\s+(?:virtual\s+)?([\w<>, \t.\?]+?)\s+(\w+)\s*(?:\{|=>)', src):
+        typ = m.group(1).strip()
+        mm = re.search(r'(?:ICollection|List|IEnumerable|IReadOnlyCollection|IReadOnlyList)<\s*(\w+)\s*>', typ)
+        core = mm.group(1) if mm else (typ.rstrip('?') if re.fullmatch(r'\w+\??', typ) else None)
+        if core and (core in names or core in shared):
+            ln = src.count('\n', 0, m.start()) + 1
+            hits.append(f"{os.path.basename(f)}:{ln} {m.group(2)} : {typ}")
 if hits:
     print('\n'.join(hits))
 PYEOF
-    )
+    ) || violations="$violations
+- 红线 4.3 无法执行：python 扫描异常退出（fail-closed，不静默放行；诊断见上方 stderr）"
 fi
 if [ -n "$nav_hits" ]; then
   violations="$violations
@@ -112,6 +115,7 @@ $nav_hits"
 fi
 
 # 红线 5：Controller 禁把 InnerException 原文透传进响应体（详情只许进日志）
+# 已知天花板：grep 按整行排除 Log 调用——透传与 Log 写在同一行可绕过；语义级排除需 AST 工具，参考实现门禁按接受记录（2026-09-24）
 inner_hits=$(grep -rn "InnerException" "$CONTROLLERS_DIR" --include="*.cs" 2>/dev/null \
   | grep -v -e "/obj/" -e "/bin/" \
   | grep -vE "Log(Warning|Error|Information|Debug|Trace)")

package/modules/hosts/trae/commands/wf-build.md

@@ -1,14 +1,14 @@
----
-name: wf-build
-description: Build 阶段 · 起 plan + 实现代码 + 自验（两道确认门，确认后才动代码）
----
-
-严格按 AGENTS.md 与 .agents/commands/build.md 执行：Build 阶段 · 起 plan + 实现代码 + 自验。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 两道确认门：① plan 草稿确认（draft→approved）② 计划模式列改动文件清单确认——两道全过才动代码。
-- 范围明确的工作包可委派 implementer（.trae/agents/implementer.md）；子智能体未开启时按 fallback: main 由主智能体按同一角色契约执行。
-- 实现中需偏离已确认 plan（公共接口 / 未列文件 / 新依赖 / 判据影响）→ 停下向用户说明，确认后再继续。
-- 完成后进 wf-test。
+---
+name: wf-build
+description: Build 阶段 · 起 plan + 实现代码 + 自验（两道确认门，确认后才动代码）
+---
+
+严格按 AGENTS.md 与 .agents/commands/build.md 执行：Build 阶段 · 起 plan + 实现代码 + 自验。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 两道确认门：① plan 草稿确认（draft→approved）② 计划模式列改动文件清单确认——两道全过才动代码。
+- 范围明确的工作包可委派 implementer（.trae/agents/implementer.md）；子智能体未开启时按 fallback: main 由主智能体按同一角色契约执行。
+- 实现中需偏离已确认 plan（公共接口 / 未列文件 / 新依赖 / 判据影响）→ 停下向用户说明，确认后再继续。
+- 完成后进 wf-test。

package/modules/hosts/trae/commands/wf-deploy.md

@@ -1,13 +1,13 @@
----
-name: wf-deploy
-description: Deploy 阶段 · prod 上线清单（静态门 / 配对 / 回归 / DB / 授权 / 24h 观察；关单在 wf-test）
----
-
-严格按 AGENTS.md 与 .agents/commands/deploy.md 执行：Deploy 阶段 · prod 上线清单（静态门 / 配对检查 / 回归 / DB / 授权 / 24h 观察；文档关单在 wf-test，本阶段不重复关单）。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 确认门：上线授权 = 用户对话内一句确认 + release/<日期> tag 留痕；无第二审批人，AI 不得自行上线。
-- 本阶段不委派子智能体；回滚 SQL 等数据安全判断由主智能体做、用户拍板。
-- 异常进 wf-maintain；用户确认无异常 = prod 闭环，AI 不得自行宣告。
+---
+name: wf-deploy
+description: Deploy 阶段 · prod 上线清单（静态门 / 配对 / 回归 / DB / 授权 / 24h 观察；关单在 wf-test）
+---
+
+严格按 AGENTS.md 与 .agents/commands/deploy.md 执行：Deploy 阶段 · prod 上线清单（静态门 / 配对检查 / 回归 / DB / 授权 / 24h 观察；文档关单在 wf-test，本阶段不重复关单）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：上线授权 = 用户对话内一句确认 + release/<日期> tag 留痕；无第二审批人，AI 不得自行上线。
+- 本阶段不委派子智能体；回滚 SQL 等数据安全判断由主智能体做、用户拍板。
+- 异常进 wf-maintain；用户确认无异常 = prod 闭环，AI 不得自行宣告。

package/modules/hosts/trae/commands/wf-design.md

@@ -1,13 +1,13 @@
----
-name: wf-design
-description: Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 wf-build）
----
-
-严格按 AGENTS.md 与 .agents/commands/design.md 执行：Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 wf-build）。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 确认门：spec 草稿经用户确认；L3 另有独立复核门，复核未过不得确认。
-- L3 独立复核委派 independent-reviewer（.trae/agents/independent-reviewer.md）；子智能体未开启时按 fallback: new-session 另开新会话，不得由原会话自查冒充。
-- 确认后进 wf-build。
+---
+name: wf-design
+description: Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 wf-build）
+---
+
+严格按 AGENTS.md 与 .agents/commands/design.md 执行：Design 阶段 · 起 spec（L2/L3 强制，L1 可省略直接进 wf-build）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：spec 草稿经用户确认；L3 另有独立复核门，复核未过不得确认。
+- L3 独立复核委派 independent-reviewer（.trae/agents/independent-reviewer.md）；子智能体未开启时按 fallback: new-session 另开新会话，不得由原会话自查冒充。
+- 确认后进 wf-build。

package/modules/hosts/trae/commands/wf-maintain.md

@@ -1,13 +1,13 @@
----
-name: wf-maintain
-description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物）
----
-
-严格按 AGENTS.md 与 .agents/commands/maintain.md 执行：Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物，不必另造 intent）。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 确认门：止血方案由用户拍板（AI 只执行选定方案）；三件套草稿经用户确认后才落地。
-- 配 plan 的时点与形态以权威文件为准——incident≡intent 免掉的是 intent，plan 不可免（commit / push 两处门禁按同名硬拦）。
-- 复现路径与验收明确的局部热修可委派 implementer（.trae/agents/implementer.md）；事故诊断、根因定性与三件套起草不委派。
+---
+name: wf-maintain
+description: Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物）
+---
+
+严格按 AGENTS.md 与 .agents/commands/maintain.md 执行：Maintain 阶段 · 立 incident + 复盘三件套（incident 在 L1+ 即 intent 等价物，不必另造 intent）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：止血方案由用户拍板（AI 只执行选定方案）；三件套草稿经用户确认后才落地。
+- 配 plan 的时点与形态以权威文件为准——incident≡intent 免掉的是 intent，plan 不可免（commit / push 两处门禁按同名硬拦）。
+- 复现路径与验收明确的局部热修可委派 implementer（.trae/agents/implementer.md）；事故诊断、根因定性与三件套起草不委派。

package/modules/hosts/trae/commands/wf-new-task.md

@@ -1,13 +1,13 @@
----
-name: wf-new-task
-description: 闭环总入口 · 路由判断（新需求 → wf-plan / 修复 → wf-maintain）+ 级别判断（L0-L3）
----
-
-严格按 AGENTS.md 与 .agents/commands/new-task.md 执行：闭环总入口 · 路由判断（新需求 intent → wf-plan / 修复 incident → wf-maintain）+ 级别判断（L0-L3）。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 输出路由结论与级别，指明进入哪个 wf-*.md；不并阶段、不跳阶段。
-- approval_required 阶段产出未经用户对话内一句话确认，不得进入下一阶段。
-- 宿主级差异（规则惰性加载 / 终端 shell / 子智能体开关 / 门禁冗余）见 alwaysApply 规则 `.trae/rules/project-workflow.md`，不在此重复。
+---
+name: wf-new-task
+description: 闭环总入口 · 路由判断（新需求 → wf-plan / 修复 → wf-maintain）+ 级别判断（L0-L3）
+---
+
+严格按 AGENTS.md 与 .agents/commands/new-task.md 执行：闭环总入口 · 路由判断（新需求 intent → wf-plan / 修复 incident → wf-maintain）+ 级别判断（L0-L3）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 输出路由结论与级别，指明进入哪个 wf-*.md；不并阶段、不跳阶段。
+- approval_required 阶段产出未经用户对话内一句话确认，不得进入下一阶段。
+- 宿主级差异（规则惰性加载 / 终端 shell / 子智能体开关 / 门禁冗余）见 alwaysApply 规则 `.trae/rules/project-workflow.md`，不在此重复。

package/modules/hosts/trae/commands/wf-plan.md

@@ -1,13 +1,13 @@
----
-name: wf-plan
-description: Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不委派子智能体）
----
-
-严格按 AGENTS.md 与 .agents/commands/plan.md 执行：Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不委派子智能体）。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 确认门：intent 草稿全文输出给用户过目，一句"可以"即确认（draft→approved），确认前不进下一阶段。
-- 已有 approved intent 时按级别跳转：L1 → wf-build；L2/L3 → wf-design。
-- 本阶段不委派子智能体，由主智能体起草；任务入口动作与红线勾选口径以权威文件为准。
+---
+name: wf-plan
+description: Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不委派子智能体）
+---
+
+严格按 AGENTS.md 与 .agents/commands/plan.md 执行：Plan 阶段 · 立 intent（AI 起草、用户确认；本阶段不委派子智能体）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：intent 草稿全文输出给用户过目，一句"可以"即确认（draft→approved），确认前不进下一阶段。
+- 已有 approved intent 时按级别跳转：L1 → wf-build；L2/L3 → wf-design。
+- 本阶段不委派子智能体，由主智能体起草；任务入口动作与红线勾选口径以权威文件为准。

package/modules/hosts/trae/commands/wf-review.md

@@ -1,13 +1,13 @@
----
-name: wf-review
-description: Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）
----
-
-严格按 AGENTS.md 与 .agents/commands/review.md 执行：Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 顺序：机器门禁自动拦 → independent-reviewer 复核（L2/L3 强制独立，子智能体未开启时另开新会话）→ 分级清单交用户定性与决定合入时机。
-- 确认门：P0/P1 未清回 wf-build；清零且用户确认后才可合入。
-- finding 报告门（防误报）与机器兜底清单以权威文件为准。
+---
+name: wf-review
+description: Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）
+---
+
+严格按 AGENTS.md 与 .agents/commands/review.md 执行：Review · 代码评审（横切，合入前使用；P0/P1/P2 分级清单 + 用户定性与合入时机）。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 顺序：机器门禁自动拦 → independent-reviewer 复核（L2/L3 强制独立，子智能体未开启时另开新会话）→ 分级清单交用户定性与决定合入时机。
+- 确认门：P0/P1 未清回 wf-build；清零且用户确认后才可合入。
+- finding 报告门（防误报）与机器兜底清单以权威文件为准。

package/modules/hosts/trae/commands/wf-test.md

@@ -1,14 +1,14 @@
----
-name: wf-test
-description: Test 阶段 · 静态门 + 切库冒烟 + UI 实测 + L2/L3 独立复核（关单在本阶段）
----
-
-严格按 AGENTS.md 与 .agents/commands/test.md 执行：Test 阶段 · 静态门全过 + 切库冒烟（如触发）+ UI 实测 + L2/L3 独立复核。
-
-先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
-
-【Trae 宿主注记】
-- 确认门：全过后用户确认才关单；**关单在本阶段**（勾验收 / incident 状态 / 委派留痕的口径以权威文件为准）。
-- UI 实测委派 ui-verifier（.trae/agents/ui-verifier.md）；L2/L3 独立复核委派 independent-reviewer，子智能体未开启时另开新会话。
-- 失败项修复仍回 wf-build，不在本阶段顺手改代码。
-- L1 到此结束；L2/L3 仅当用户确认要上 prod 才进 wf-deploy。
+---
+name: wf-test
+description: Test 阶段 · 静态门 + 切库冒烟 + UI 实测 + L2/L3 独立复核（关单在本阶段）
+---
+
+严格按 AGENTS.md 与 .agents/commands/test.md 执行：Test 阶段 · 静态门全过 + 切库冒烟（如触发）+ UI 实测 + L2/L3 独立复核。
+
+先完整读取上述两个文件并完全遵循，读不到即停下报告阻塞；本文件不内联步骤副本，避免与权威版本漂移。
+
+【Trae 宿主注记】
+- 确认门：全过后用户确认才关单；**关单在本阶段**（勾验收 / incident 状态 / 委派留痕的口径以权威文件为准）。
+- UI 实测委派 ui-verifier（.trae/agents/ui-verifier.md）；L2/L3 独立复核委派 independent-reviewer，子智能体未开启时另开新会话。
+- 失败项修复仍回 wf-build，不在本阶段顺手改代码。
+- L1 到此结束；L2/L3 仅当用户确认要上 prod 才进 wf-deploy。

package/modules/hosts/trae/hooks/post-edit-check.cjs

@@ -75,6 +75,16 @@ try {
     }));
     process.exit(0);
   }
+  // 门禁脚本未装（未跑 add-gate dotnet-ca）≠ 发现违例——区分口径，对齐 pre-shell-check 的 ENOENT 处理（2026-09-24）
+  if (e.code === 'ENOENT') {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: '⚠️ 架构红线检查未执行：check-architecture.sh 未安装（flow-kit add-gate dotnet-ca 装入）——本次编辑未验证。'
+      }
+    }));
+    process.exit(0);
+  }
   const err = String((e.stderr || '') + (e.stdout || '')).slice(0, 800);
   console.log(JSON.stringify({
     hookSpecificOutput: {

package/modules/hosts/trae/hooks/pre-shell-check.cjs

@@ -4,7 +4,7 @@
  * 1) deny/ask 命令门禁（口径同 .agents/settings.json 的 deny/ask 策略）
  * 2) git commit / git push 前置检查：直接调 .githooks/pre-commit / pre-push
  *
- * 为什么调 .githooks/*：那是项目唯一的门禁权威（pre-commit 六项 + pre-push 闭环断档）。
+ * 为什么调 .githooks/*：那是项目唯一的门禁权威（pre-commit 门禁链 + pre-push 闭环断档）。
  * 本钩子是**宿主侧冗余**——core.hooksPath 漏配时 git 侧门禁静默失效（2026-09-16 Trae 侧缺档事故），
  * 由这里在命令执行前拦下；门禁清单只维护 .githooks/ 一份，本文件不复制。
  *
@@ -90,13 +90,23 @@ const askList = [
   { pat: 'rm -rf',        reason: '可能递归删除文件' }
 ];
 
+// gateMatch：比裸 includes 收紧两处（2026-09-24）——
+//   ① token 边界：'git push --force' 不再误拦 '--force-with-lease'、'git commit' 不再误吃 'git commit-msg'
+//   ② 剥离 git 全局参 -c <k=v> 与 -m <msg> 后以剥后文本为准——堵 'git -c x=y push --force' 绕过，
+//     也免得消息字样误触发；剥不出（norm===cmd）再按原文匹配
+function gateMatch(cmd, pat) {
+  const re = new RegExp(pat.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?![\\w-])');
+  const norm = cmd.replace(/(^|\s)-[cm]\s+\S+(?=\s|$)/g, ' ').replace(/\s+/g, ' ').trim();
+  return norm !== cmd ? re.test(norm) : re.test(cmd);
+}
+
 for (const d of denyList) {
-  if (command.includes(d.pat)) {
+  if (gateMatch(command, d.pat)) {
     deny(`禁止执行: ${d.pat}（项目红线：${d.reason}）`);
   }
 }
 for (const a of askList) {
-  if (command.includes(a.pat)) {
+  if (gateMatch(command, a.pat)) {
     ask(`需确认: ${a.pat}（项目 ask 策略：${a.reason}）`);
   }
 }
@@ -135,7 +145,7 @@ function runGate(scriptRelPath, label, budgetMs) {
 }
 
 if (isCommit) {
-  // pre-commit 六项：架构红线 + 审计字段 + 删除拦截 + 闭环配对（增量）+ 敏感信息 + 条件编译
+  // pre-commit 门禁链（通用包口径）：闭环配对（增量）+ wiki 台账（增量）+ 常驻面预算 + 项目门禁（local-pre-commit）+ 敏感信息扫描与条件构建
   // 预算 5 分钟覆盖 dotnet build / npm run build（.githooks/pre-commit 内部无超时）
   runGate('.githooks/pre-commit', '提交前门禁', 300000);
 }

package/modules/hosts/trae/hooks/resolve-shell.cjs

@@ -1,21 +1,30 @@
-// shell 探测（供 .trae/hooks/ 各钩子共用）
-// Windows 下 bash 常不在 PATH：优先 Git Bash 绝对路径，回退 PATH 的 bash/sh。
-// 返回 null 表示不可用——调用方须 fail-closed 报告「门禁未执行」，不要当成检查通过。
-const { execFileSync } = require('child_process');
-const fs = require('fs');
-
-function resolveShell() {
-  const candidates = [
-    'C:\\Program Files\\Git\\bin\\bash.exe',
-    'C:\\Program Files (x86)\\Git\\bin\\bash.exe'
-  ];
-  for (const p of candidates) {
-    try { fs.accessSync(p); return p; } catch { /* 尝试下一个 */ }
-  }
-  for (const c of ['bash', 'sh']) {
-    try { execFileSync(c, ['-c', 'exit 0'], { stdio: 'pipe', timeout: 5000 }); return c; } catch { /* 尝试下一个 */ }
-  }
-  return null;
-}
-
-module.exports = { resolveShell };
+// shell 探测（供 .trae/hooks/ 各钩子共用）
+// Windows 下 bash 常不在 PATH：优先 Git Bash 绝对路径，回退 PATH 的 bash/sh。
+// 返回 null 表示不可用——调用方须 fail-closed 报告「门禁未执行」，不要当成检查通过。
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+
+function resolveShell() {
+  const candidates = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe'
+  ];
+  for (const p of candidates) {
+    try { fs.accessSync(p); return p; } catch { /* 尝试下一个 */ }
+  }
+  // PATH 回退须避开 WSL 启动器：C:\Windows\System32\bash.exe 能过 exit 0 探测，但路径/行尾语义是 Linux 侧的（2026-09-24）
+  for (const c of ['bash', 'sh']) {
+    let cand = c;
+    try {
+      const hits = execFileSync('where.exe', [c], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+        .split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+      const good = hits.find((p) => !/system32/i.test(p)); // 全部命中都在 System32（纯 WSL）→ 跳过该候选
+      if (good) cand = good;
+      else continue;
+    } catch { /* where 不可用（非 Windows）：按原名探测，保持旧行为 */ }
+    try { execFileSync(cand, ['-c', 'exit 0'], { stdio: 'pipe', timeout: 5000 }); return cand; } catch { /* 尝试下一个 */ }
+  }
+  return null;
+}
+
+module.exports = { resolveShell };

package/modules/hosts/trae/rules/beautify-input-chinese.md

@@ -1,6 +1,6 @@
----
-alwaysApply: false
-scene: beautify_input
----
-
-请使用中文回复。所有解释、说明、注释和对话均使用中文。
+---
+alwaysApply: false
+scene: beautify_input
+---
+
+请使用中文回复。所有解释、说明、注释和对话均使用中文。

package/modules/hosts/trae/rules/git-commit-message.md

@@ -1,10 +1,10 @@
----
-alwaysApply: false
-scene: git_message
----
-
-提交信息一律中文，遵循 Conventional Commits：`<类型>(<范围>): <说明>`，例如 `fix(采购订单): 页签切换浮层收纳`、`docs(trae): 同步工作流适配层`。
-
-- 类型枚举：feat / fix / docs / style / refactor / perf；`.githooks/commit-msg` 按此硬校验首行，非枚举前缀会被拦下，merge / revert 提交豁免。
-- 范围可省：`fix: 说明` 同样合法；分隔符 `:` 或 `（` 均可。
-- 禁止 `[feat] 说明` 这类方括号写法。
+---
+alwaysApply: false
+scene: git_message
+---
+
+提交信息一律中文，遵循 Conventional Commits：`<类型>(<范围>): <说明>`，例如 `fix(采购订单): 页签切换浮层收纳`、`docs(trae): 同步工作流适配层`。
+
+- 类型枚举：feat / fix / docs / style / refactor / perf；`.githooks/commit-msg` 按此硬校验首行，非枚举前缀会被拦下，merge / revert 提交豁免。
+- 范围可省：`fix: 说明` 同样合法；分隔符 `:` 或 `（` 均可。
+- 禁止 `[feat] 说明` 这类方括号写法。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow-kit",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {
@@ -30,5 +30,13 @@
     "closed-loop"
   ],
   "license": "MIT",
-  "private": false
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerosloney/agentic-flow-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zerosloney/agentic-flow-kit/issues"
+  },
+  "homepage": "https://github.com/zerosloney/agentic-flow-kit#readme"
 }

package/src/add-gate.mjs

@@ -52,6 +52,7 @@ export function addGate(args, pkgRoot) {
   if (skipped.length) console.log(`  跳过（已存在，--force 覆盖）：${skipped.join('、')}`);
 
   // 接线 local-pre-commit（幂等：挂载行已存在不重复；旧装态尾部 exit 0 会吞掉其后门禁的失败——归一化剥掉）
+  let wiredLp = false;
   if (wireLine) {
     const lpPath = path.join(hooksDir, 'local-pre-commit');
     const cur = fs.existsSync(lpPath) ? fs.readFileSync(lpPath, 'utf8') : '';
@@ -67,15 +68,21 @@ export function addGate(args, pkgRoot) {
       const body = lines.length ? `${lines.join('\n')}\n` : '#!/bin/sh\nset -e\n';
       fs.writeFileSync(lpPath, `${body}${wireLine}\n`);
       console.log(`  local-pre-commit 接线：+ ${wireLine}`);
+      wiredLp = true;
     }
   }
 
-  // owned 台账补记（归项目所有，sync 永不覆盖）
+  // owned 台账补记（归项目所有，sync 永不覆盖）。接线改写了 local-pre-commit（init 时按模板态记账）——
+  // 须同步刷新其 owned 哈希，否则台账停在模板态（Shipyard 回流发现的漂移根因，2026-09-24）
   const ownedLedger = new Map((kit.owned || []).map((f) => [f.rel, f]));
   for (const name of installed) {
     const rel = `.agents/hooks/${name}`;
     ownedLedger.set(rel, { rel, sha256: sha256(fs.readFileSync(path.join(hooksDir, name))) });
   }
+  if (wiredLp) {
+    const lpRel = '.agents/hooks/local-pre-commit';
+    ownedLedger.set(lpRel, { rel: lpRel, sha256: sha256(fs.readFileSync(path.join(hooksDir, 'local-pre-commit'))) });
+  }
   kit.owned = [...ownedLedger.values()].sort((a, b) => a.rel.localeCompare(b.rel));
   fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
 

package/src/add-host.mjs

@@ -39,6 +39,10 @@ export function addHost(args, pkgRoot) {
   const r = renderTree(path.join(pkgRoot, 'modules', 'hosts', host), path.join(target, HOSTS[host].dir), vars, { force });
   if (!r.written.length && r.skipped.length) console.log('  跳过（已存在，未覆盖）：' + r.skipped.join('、'));
   else console.log(`  安装 ${r.written.length} 份${r.skipped.length ? `，跳过已存在 ${r.skipped.length} 份` : ''}`);
+  if (r.skipped.length) {
+    // 跳过的文件不入 managed 台账（不接管既有内容）——后续 sync 只报「已存在未入台账」，永不升级；纳入包管理须 --force
+    console.log('  ⚠️ 跳过文件不入 managed 台账、后续 sync 不升级（每次仅报告）；纳入包管理用 --force 覆盖');
+  }
 
   // managed 台账按 rel 去重补记
   const ledger = new Map((kit.managed || []).map((f) => [f.rel, f]));

package/src/cli.mjs

@@ -15,9 +15,10 @@ export const HELP = `flow-kit — AI-Native 闭环工作流 + wiki 知识层脚
 
 用法：
   flow-kit init             安装到当前项目（裸跑无参数 → 交互确认环节；带参数直接执行）
-  flow-kit sync             升级 managed 文件（未改动→覆盖新版；本地已改→跳过并报告，--force 才覆盖；
-                            INDEX/看板等生成器目标重跑锚点重写；owned 文件永不触碰）
-  flow-kit add-host <宿主>  后补宿主适配层：zcode | opencode | trae | omp
+  flow-kit sync             升级 managed 文件（未改动→覆盖新版；本地已改→跳过并持续报告——台账不基线化，
+                            不会被下次升级静默覆盖；--force 才覆盖；INDEX/看板等生成器目标重跑锚点重写；
+                            owned 文件永不触碰）
+  flow-kit add-host <宿主>  后补宿主适配层：zcode | opencode | trae | omp（已存在文件跳过且不入台账，--force 接管）
   flow-kit add-gate <门禁>  装门禁模块并接线 local-pre-commit（当前：dotnet-ca；装后归项目所有）
   flow-kit doctor           体检：目录布局 / git 钩子 / managed 清单 / 索引漂移 / check-loop
 

package/src/doctor.mjs

@@ -120,6 +120,13 @@ export function doctor(args, pkgRoot) {
   if (idx.status === 0) add('PASS', 'workflow/INDEX.md 无漂移');
   else add('WARN', `workflow/INDEX.md 漂移——跑 node .agents/scripts/gen-workflow-index.mjs 重生成`);
 
+  // 6.5 delegations 台账结构（量化层非门禁：结构漂移曾静默吞掉全部记录，2026-09-24）
+  if (fs.existsSync(path.join(target, '.agents/scripts/agg-delegations.cjs'))) {
+    const agg = spawnSync(process.execPath, ['.agents/scripts/agg-delegations.cjs'], { cwd: target, encoding: 'utf8' });
+    if (agg.status === 0) add('PASS', 'delegations 台账结构有效（agg 可解析）');
+    else add('WARN', `delegations 台账结构漂移——${String(agg.stderr || agg.stdout || '').split('\n')[0]}`);
+  }
+
   // 7. check-loop
   const cl = spawnSync('sh', ['.agents/scripts/check-loop.sh'], { cwd: target, encoding: 'utf8' });
   if (cl.status === 0) {
@@ -135,8 +142,8 @@ export function doctor(args, pkgRoot) {
   portInUse(port).then((inUse) => {
     print(results);
     console.log(inUse
-      ? `ℹ️  看板端口 ${port} 已有监听（幂等拉起会探活复用；他人进程不 kill，见 workflow/README.md）`
-      : `ℹ️  看板端口 ${port} 空闲（首次访问任务入口时由 ensure-board 拉起，或手动 node .agents/scripts/workflow-board-server.mjs）`);
+      ? `ℹ️  看板端口 ${port} 已有监听（ensure-board 探活复用；他人进程不 kill，见 workflow/README.md）`
+      : `ℹ️  看板端口 ${port} 空闲（看板默认不拉起；需要时手动 .agents/scripts/ensure-board.ps1 或 node .agents/scripts/workflow-board-server.mjs）`);
     process.exit(results.some((r) => r.level === 'FAIL') ? 1 : 0);
   });
 }

package/src/render.mjs

@@ -27,6 +27,8 @@ export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       const abs = path.join(dir, entry.name);
       if (entry.isDirectory()) {
+        // 运行时缓存不是模板（包源跑测试会在 templates/_agents/cache/ 落盘残留）——init/sync 一律跳过
+        if (relOf(abs, srcRoot) === '.agents/cache') continue;
         dirs.push(relOf(abs, srcRoot));
         walk(abs);
         continue;

package/src/sync.mjs

@@ -1,5 +1,6 @@
 // flow-kit sync：按 .agents/kit.json 台账升级 managed 文件。
-// 三态：未改动（磁盘 sha==台账）→ 覆盖新版；本地已改 → 跳过并报告（--force 覆盖）；
+// 三态：未改动（磁盘 sha==台账）→ 覆盖新版；本地已改 → 跳过并报告（--force 覆盖；台账保持包侧基线，
+//       每次持续报告直至 --force 或本地对齐新版——防跳过一次后下次升级被静默覆盖，2026-09-24 语义修正）；
 //       生成器目标（INDEX.md / wiki 看板）→ 不比对，收尾重跑生成器走锚点重写。
 // 附带：包内新增 managed 文件 → 安装；包内已删 → 仅报告不删盘、出台账；managed 缺失 → 恢复。
 // owned 文件永不触碰（两态模型，见 profiles.isOwned）。
@@ -86,7 +87,7 @@ export function sync(args, pkgRoot) {
       // 本地已改
       if (freshFile.sha === diskSha) { unchanged++; managedNew.push({ rel, sha256: diskSha }); continue; } // 改动恰好等于新版
       if (force) { fs.copyFileSync(freshFile.abs, disk); updated.push(`${rel}（--force 覆盖本地改动）`); managedNew.push({ rel, sha256: freshFile.sha }); }
-      else { skipped.push(rel); managedNew.push({ rel, sha256: diskSha }); } // 台账跟随磁盘，下次以当前盘面为基线
+      else { skipped.push(rel); managedNew.push({ rel, sha256: ledgerSha }); } // 台账保持包侧基线：持续报告「本地已改」，直到 --force 或本地对齐新版
     }
 
     // 台账外的新文件：managed 类安装；owned 类只对「盘上缺失」的起步文档报告（已装的不动不报）
@@ -109,7 +110,7 @@ export function sync(args, pkgRoot) {
     list('恢复缺失', restored);
     list('新增安装', added);
     list('本地已改，跳过', skipped);
-    if (skipped.some((s) => !s.includes('未入台账'))) console.log('    ↑ --force 覆盖本地改动；git diff 自查差异');
+    if (skipped.some((s) => !s.includes('未入台账'))) console.log('    ↑ --force 覆盖本地改动；git diff 自查差异；台账保持包侧基线，后续 sync 持续报告直至处理');
     list('包内已移除（文件保留在盘上，可手动删除）', removed);
     list('新增 owned 起步文档（项目自持，未自动安装）', newOwned);
     if (!updated.length && !restored.length && !added.length && !removed.length && !skipped.length && !newOwned.length) {
@@ -118,7 +119,22 @@ export function sync(args, pkgRoot) {
       console.log(`  无变化 ${unchanged} 份`);
     }
 
-    // 台账重写：版本对齐当前包；removed 出册；skipped 盘面基线化
+    // owned 台账按盘面自愈：owned 归项目所有，哈希只是记账不是约束——手改后无须手工刷 kit.json
+    // （Shipyard 回流策略，2026-09-24：曾在消费仓被迫手工刷新 owned 哈希，根因收敛到此处）
+    let ownedRefreshed = 0;
+    if (Array.isArray(kit.owned)) {
+      kit.owned = kit.owned.map((f) => {
+        const p = path.join(target, f.rel);
+        if (!fs.existsSync(p)) return f;
+        const disk = sha256(fs.readFileSync(p));
+        if (disk === f.sha256) return f;
+        ownedRefreshed++;
+        return { ...f, sha256: disk };
+      });
+    }
+    if (ownedRefreshed) console.log(`  owned 台账哈希按盘面刷新 ${ownedRefreshed} 份（owned 归项目所有，仅记账不约束）`);
+
+    // 台账重写：版本对齐当前包；removed 出册；skipped 保持包侧基线持续报告
     kit.managed = managedNew.sort((a, b) => a.rel.localeCompare(b.rel));
     kit.version = pkg.version;
     fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);