| name | harness-gardening |
| slug | harness-gardening |
| version | 1.6.5 |
| description | 文档园艺——持续维护 harness-engineering 产出的文档与项目实际状态的一致性。
支持 PR 轻量检查（代码变更后按需触发受影响维度）、全量深度扫描（十二维度完整检测）
和定向检测（targeted，指定单个组件/维度进行针对性巡检）。
完整扫描后：若存在 P1，向用户列出方案并请求确认，确认后与 P0 一并修复并提交；仅有 P0 时自动修复提交。
由 harness-engineering 按维护类触发词路由调用，不独立触发。
|
文档园艺（Harness Gardening）
路径约定：references/ = 本子 skill 私有资源（harness-gardening/references/）；../references/ = 父 skill 共享资源（harness-engineering/references/）；../assets/ = 父 skill 预设库。
维度 1 红线（2026-08）： 路径失效时只改文档引用或提 P1；禁止 git checkout/git restore 把已删除路径加回工作区（除非用户在 P1 中明确确认恢复）。详见 references/detection-dimensions.md。
维度 9： 清理 AGENTS 强制 workflow 措辞时无治理仓例外。
维度 12： 根 AGENTS 项目记忆保留 + 工作单元索引（未索引 → P1；误改非根 AGENTS → 报告，默认不自动 restore）；规程见 ../references/agents-merge.md、../references/agents-work-units.md。
核心职责
持续维护目标项目中 harness-engineering 产出的文档与项目代码/结构的一致性：
- 检测 Harness 文档（
AGENTS.md / docs/harness/ / docs/standards/ / docs/glossary.md / docs/dev-map/）与实际状态的偏差
- P0 偏差（确定性、无歧义）自动修复
- P1 偏差（语义级、需人判断）向用户列出修复方案并请求确认；确认后与 P0 一并提交，拒绝/延迟的写入 proposals 文件备用
docs/standards/ 同步策略：单向从预设库同步，不支持用户定制。
docs/standards/ 下的文件以 ../assets/standards/ 预设为权威来源，gardening 负责将预设覆写到项目（入口 .md + 同名 {stem}/ 分册目录）：
- 若项目文件与同名预设文件存在差异 → 用预设覆写项目文件（P0 自动修复）
- 若检测到新技术栈且预设库有对应文件 → 将预设复制到
docs/standards/（P0 自动修复）
因此 docs/standards/ 下的文件不应手动修改，任何改动在下次 gardening 时都会被预设覆盖。
如需定制规范内容，应修改 ../assets/standards/ 中的对应预设文件。
执行清单
开始执行前，根据 mode 使用 TodoWrite 创建对应清单（全部状态 pending）：
PR 模式（mode=pr）：
| ID | 清单项 |
|---|
grd-pr-1 | 获取变更文件列表（调用 harness-changed-files.sh，切出点 diff 或 last-commit diff） |
grd-pr-2 | 推断受影响维度 |
grd-pr-3 | 汇总并处置（P0/P1 分类、P1 确认、修复、commit） |
grd-pr-2 完成后，为每个被触发的维度用 TodoWrite 追加 todo 项（插入在 grd-pr-3 之前），ID 格式 grd-pr-dim-N（N 为维度编号，如 grd-pr-dim-1、grd-pr-dim-8）。
全量模式（mode=full）：
| ID | 清单项 |
|---|
grd-full-1 | 读取所有 Harness 文档 |
grd-full-3 | 汇总检测结果（P0 / P1 / Skip 分类） |
grd-full-4 | P1 确认（若有 P1；无则直接标记 completed） |
grd-full-5 | 执行修复（P0 自动 + 用户确认的 P1） |
grd-full-6 | 生成 gardening-report.md 并 commit |
grd-full-7 | 输出总结报告 |
grd-full-1 完成后，按 references/detection-dimensions.md 的维度列表，为每个维度用 TodoWrite 追加 todo 项（插入在 grd-full-3 之前），ID 格式 grd-full-dim-N。
定向模式（mode=targeted）：
| ID | 清单项 |
|---|
grd-tgt-1 | 解析 target 参数，确定目标维度 |
grd-tgt-dim-N | 执行目标维度 N 检测（N 为实际维度编号） |
grd-tgt-2 | 汇总并处置（P0/P1 分类、P1 确认、修复、commit） |
每完成一步（含每个维度）：立即调用 TodoWrite 将对应条目标记为 completed，再继续下一步。
前置条件
- 目标项目已运行过 harness-generating（存在
AGENTS.md 和 docs/harness/ 目录）
- 当前处于目标项目的仓库根目录
- 执行前须识别项目类型：读取
../references/project-type-detection.md，确定 $SKILL_ROOT。
识别项目类型后，执行以下两个自动化前置步骤：
步骤 A：环境配置（幂等，每次执行自动完成）
eval $(bash "$SKILL_ROOT/harness-engineering/scripts/harness-setup-git.sh")
- 自动检查并写入
.gitattributes 两条条目（缺失时追加）：
docs/dev-map/graph.json merge=graphifydocs/harness/gardening-report.md merge=ours
- 自动检查并注册 git config merge driver（
graphify merge-driver %O %A %B）
- 若
GITATTR_MODIFIED=true，将 .gitattributes 纳入本次最终 commit（git add .gitattributes）
步骤 B：报告路径与 diff 基线（每次执行自动确定）
eval $(bash "$SKILL_ROOT/harness-engineering/scripts/harness-diff-base.sh")
$REPORT_PATH：功能分支（feature/issue-N）→ workflows/issue-N/gardening-report.md；其他 → docs/harness/gardening-report.md$DIFF_BASE：功能分支 → 沿 HEAD 遍历找切出点（首个被其他远端分支包含的 commit）；其他 → 空（由 last-commit 字段决定）
后续所有"生成/更新 gardening-report.md"步骤均使用 $REPORT_PATH 作为写入目标。
执行流程
PR 轻量检查（mode=pr）
1. 获取变更文件列表（增量 diff）
执行：CHANGED=$(bash "$SKILL_ROOT/harness-engineering/scripts/harness-changed-files.sh" "$DIFF_BASE" "$REPORT_PATH")
- 若输出含 UPGRADE_TO_FULL → 自动升级为全量扫描（执行 mode=full 流程）
- 若输出为空 → 输出"无新变更，无需检查"并退出
2. 根据变更文件推断受影响维度：
- 新增/删除 `$SKILL_ROOT/` 下目录 → 维度 2（Skill 清单）+ 维度 7（工具依赖）
- 修改 `$SKILL_ROOT/harness-engineering/references/tool-dependencies.md` → 维度 7（工具依赖）
- 修改 `agents/*.md`（开发仓）或 `{SKILL_ROOT}/../agents/*.md`（接入仓） → 维度 7（工具依赖）
- 修改 go.mod / package.json → 维度 4（技术规范同步）[仅 code-project / mixed]：检测新增技术栈，对比并同步预设
- 新增/删除 `docs/standards/` 下文件 → 维度 4（技术规范同步）：对比并同步预设
- 新增/移动/删除文件 → 维度 1（路径有效性）+ 维度 6（目录结构）+ 维度 8（Dev Map 与 IDE 集成一致性）
- 修改 internal/ 或分层相关目录 → 维度 3（架构描述）
- （已移除）修改 `../assets/workflow-template.md` → 维度 9 已 Skip，不再触发
- 新增/删除 `.cursor/` / `.codebuddy/` / `.claude/` 目录 → 维度 8（Dev Map 与 IDE 集成一致性）
- 新增/删除/修改 `**/rules/graphify.mdc` / `**/rules/graphify.md` → 维度 8
- 新增/删除/修改 `docs/business-standards/` 下文件 → 维度 10（业务规范一致性）
- 修改根 `AGENTS.md` / `docs/standards/` / 任意 `standards-*.mdc` / `standards-*.md` → 维度 11（Standards Rules 一致性）+ 维度 12（AGENTS 项目记忆 / 工作单元索引；根 AGENTS 变更时）
- 新增/删除/修改任意非根 `**/AGENTS.md` → 维度 12（工作单元索引与误改局部检测）
- 新增/删除 `.agents/`（或与 Rules 相关的 `.cursor` / `.codebuddy`）→ 维度 11
- 若无维度被触发 → 输出"无需检查"并退出
3. 仅运行被触发的维度
读取 references/detection-dimensions.md 获取各维度的检测规则
4. 汇总并处置
a. 按 P0 / P1 / Skip 分类所有检测结果
b. 若存在 P1：向用户逐条列出 P1 修复方案，等待确认
- 用户确认：纳入本次执行
- 用户拒绝/延迟：追加到 docs/harness/gardening-proposals.md 备用
c. 执行全部 P0 修复 + 用户确认的 P1 修复
d. 生成/更新 $REPORT_PATH（last-commit 字段先填占位值 "pending"）
git add <所有修复文件> $REPORT_PATH [.gitattributes（若步骤 A 有修改）]
git commit -m "docs(gardening): ..."（新建独立 commit，不 amend 已有提交）
e. 写入 last-commit（仅 $DIFF_BASE 为空时执行，即 master/非 issue 分支）：
1. git rev-parse HEAD → 获取步骤 d 产生的 commit SHA
2. 更新 $REPORT_PATH 中 "> last-commit: " 行的值为该 SHA
3. git add $REPORT_PATH && git commit --amend --no-edit
f. Skip：记录到报告但不处理
g. 若无 P1（仅 P0）：跳过步骤 b，直接执行 c → d → e
全量深度扫描（mode=full）
1. 读取目标项目的所有 Harness 文档
- AGENTS.md
- docs/harness/*.md
- docs/standards/*.md
- docs/glossary.md
- docs/dev-map/*.md（若存在）
- docs/workflow.md（若存在）
2. 依次运行十二个检测维度
读取 references/detection-dimensions.md 获取详细规则
3. 汇总检测结果，按 P0/P1/Skip 分类
4. 处置
a. 若存在 P1：向用户逐条列出 P1 修复方案，等待确认
- 用户确认：纳入本次执行
- 用户拒绝/延迟：写入 docs/harness/gardening-proposals.md 备用
b. 执行全部 P0 修复 + 用户确认的 P1 修复
c. 生成 $REPORT_PATH（last-commit 字段先填占位值 "pending"）
d. git add <所有修复文件> $REPORT_PATH [.gitattributes（若步骤 A 有修改）]
git commit -m "docs(gardening): ..."（新建独立 commit，包含修复 + 报告）
然后写入 last-commit（仅 $DIFF_BASE 为空时执行）：
1. git rev-parse HEAD → 获取步骤 d commit 的 SHA
2. 更新 $REPORT_PATH 中 "> last-commit: " 行的值为该 SHA
3. git add $REPORT_PATH && git commit --amend --no-edit
e. Skip：记录到 $REPORT_PATH 但不处理
f. 若无 P1（仅 P0）：跳过步骤 a，直接执行 b → c → d
5. 输出总结报告给用户（已修复项、延迟 P1 项、Skip 项）
定向检测（mode=targeted）
1. 解析 target 参数，确定目标维度：
- dim-N 格式（N=1~12）→ 直接取维度 N
- 具名 target → 按以下映射转换：
paths → 维度 1（路径有效性）
skills → 维度 2（Skill 清单一致性）
architecture → 维度 3（架构描述一致性）
standards → 维度 4（技术规范同步）
glossary → 维度 5（词汇表完整性）
structure → 维度 6（目录结构一致性）
tooling → 维度 7（工具依赖一致性）
dev-map → 维度 8（Dev Map 与 IDE 集成一致性）
workflow → 维度 9（工作流文档同步）
business-standards → 维度 10（业务规范一致性）
standards-rules → 维度 11（Standards Rules 一致性）
agents-merge / agents-memory → 维度 12（AGENTS 项目记忆保留）
- 无法识别 → 列出所有合法 target 值并退出
2. 仅读取该维度所需的 Harness 文档（按 references/detection-dimensions.md 中维度扫描范围定义），
读取 references/detection-dimensions.md 获取该维度的检测规则
3. 执行目标维度检测
4. 汇总并处置（流程同全量模式步骤 4，新增 h：无偏差时不 commit）：
a. 按 P0 / P1 / Skip 分类检测结果
b. 若存在 P1：向用户逐条列出 P1 修复方案，等待确认
- 用户确认：纳入本次执行
- 用户拒绝/延迟：写入 docs/harness/gardening-proposals.md 备用
c. 执行全部 P0 修复 + 用户确认的 P1 修复
d. 生成/更新 $REPORT_PATH：
- 在报告中注明本次为 targeted 扫描，记录 target 值与对应维度编号
- last-commit 字段先填占位值 "pending"
git add <所有修复文件> $REPORT_PATH [.gitattributes（若步骤 A 有修改）]
git commit -m "docs(gardening): targeted <target> ..."（新建独立 commit）
e. 写入 last-commit（仅 $DIFF_BASE 为空时执行）：
1. git rev-parse HEAD → 获取步骤 d 产生的 commit SHA
2. 更新 $REPORT_PATH 中 "> last-commit: " 行的值为该 SHA
3. git add $REPORT_PATH && git commit --amend --no-edit
f. Skip：记录到报告但不处理
g. 若无 P1（仅 P0）：跳过步骤 b，直接执行 c → d → e
h. 若无任何偏差：输出"目标组件 <target> 未检测到偏差"并退出（不 commit）
处置分级
| 级别 | 判定条件 | 处置方式 | 示例 |
|---|
| P0 | 确定性偏差，修复无歧义 | 自动修复；若同批次有 P1 则与确认的 P1 一并提交，否则单独 commit | 路径重命名、Skill 清单新增、词汇表补条目、standards 预设同步覆写 |
| P1 | 语义级偏差，需人判断 | 向用户展示方案并请求确认；确认后与 P0 一并提交，拒绝/延迟则写入 proposals 备用 | 架构描述不一致、新技术栈预设不在预设库中需降级处理 |
| Skip | 无法确定是否为偏差 | 记录到报告但不处理 | 文档描述的是规划中架构 |
产出文件
docs/harness/
├── gardening-report.md # 非 workflow 场景报告（merge=ours 兜底，master 周期扫描用）
└── gardening-proposals.md # 用户拒绝/延迟的 P1 方案（执行后由下次扫描清空）
workflows/issue-N/
└── gardening-report.md # workflow 场景报告（随 PR diff 可见，路径隔离无冲突）
报告路径由前置条件步骤 B（harness-diff-base.sh）动态确定，写入 $REPORT_PATH。
产出文件的 Markdown 格式模板见 references/output-templates.md。
参考资源
| 文件 | 用途 | 何时读取 |
|---|
../references/project-type-detection.md | 项目类型识别与 $SKILL_ROOT 检测 | 前置条件检查时（必须最先） |
../scripts/harness-setup-git.sh | 配置 .gitattributes 和 git merge driver（运行时路径：$SKILL_ROOT/harness-engineering/scripts/） | 前置条件步骤 A |
../scripts/harness-diff-base.sh | 确定报告路径（$REPORT_PATH）和 diff 切出点（$DIFF_BASE） | 前置条件步骤 B |
../scripts/harness-changed-files.sh | 获取本次巡检的变更文件列表 | PR 模式步骤 1 |
references/detection-dimensions.md | 各维度详细检测规则和修复策略（文件开头有维度概览表） | 执行检测时 |
../references/agents-merge.md | 根 AGENTS 先理解再合并（维度 12） | 维度 12 |
../references/agents-work-units.md | 工作单元发现与根索引（维度 12） | 维度 12 |
../references/standards-compliance.md | Standards 门闩与 Rules 同步算法（维度 11 / generating 共用） | 维度 11 |
../scripts/sync-standards-rules.sh | 按选用表渲染/裁剪 IDE Rules | 维度 11 P0 修复 |
references/output-templates.md | gardening-report 和 gardening-proposals 格式模板 | 生成产出文件时 |
../assets/standards/index.yaml | 技术规范预设索引（维度 4 使用） | 检测规范版本时 |
../assets/harness-spec-template.md | 文档结构模板（维度 6 参照） | 检测目录结构时 |
../assets/dev-map-templates.md | 开发地图文档模板（维度 8 修复参照） | 修复 dev map 偏差时 |
../assets/dev-map.gitignore | 开发地图结果级 ignore（维度 8 写回 docs/dev-map/.gitignore） | 修复误 ignore / 缺失 ignore 时 |
../references/best-practices.md | 最佳实践（做法 9-12 直接相关） | 生成修复方案时参考 |
../references/tool-dependencies.md | Agent 工具依赖权威清单（维度 7） | 对比 tooling.md 时 |
../assets/workflow-template.md | |
清单验收
在输出总结报告后，检查 TodoWrite 清单：
- 全部
completed → 执行完毕，正常退出
- 有
pending / in_progress 项 → 立即补充执行对应步骤，直至清单全绿再退出
