From harness-flow
Verifies if user-facing docs (READMEs, API docs, OpenAPI, i18n, CONTRIBUTING) sync with feature changes after hf-regression-gate, before hf-completion-gate. Outputs verdict and evidence.
npx claudepluginhub hujianbest/harness-flow --plugin harness-flowThis skill uses the workspace's default tool permissions.
判定本任务 / 本 feature 引入的 user-visible behavior change 是否已在**对外可见文档**中同步刷新,并按 sync-on-presence + profile 分级 + 与 `hf-completion-gate` / `hf-finalize` / `hf-increment` / `hf-code-review` / `hf-traceability-review` 显式分工的纪律输出 `verdict + fresh evidence`。
Updates README, .correctless/AGENT_CONTEXT.md, ARCHITECTURE.md, and feature docs after features land. Intensity-aware with Mermaid diagrams at high level and fact-checking subagent at critical. Run before merging.
Audits documentation staleness via git history and maintains quality with auto-fixes. Maps code paths to docs in $JAAN_DOCS_DIR. Use for reviewing or updating docs.
Audits repo documentation under doc/ and READMEs (README.md, README-EN.md, README-ZH.md, mcp/README.md) for drift, stale statements, broken references, and mismatches during maintenance or before PRs.
Share bugs, ideas, or general feedback.
判定本任务 / 本 feature 引入的 user-visible behavior change 是否已在对外可见文档中同步刷新,并按 sync-on-presence + profile 分级 + 与 hf-completion-gate / hf-finalize / hf-increment / hf-code-review / hf-traceability-review 显式分工的纪律输出 verdict + fresh evidence。
职责边界:本 gate 只负责"对外可见文档的同步 verdict"。同 tier 的 hf-regression-gate 负责"行为不回归";下游 hf-completion-gate 消费本 gate verdict 作为 evidence bundle 一项;hf-finalize 在 closeout 阶段同步既有合同覆盖的长期资产(CHANGELOG / ADR 状态翻转 / 顶层导航 / docs/architecture / docs/runbooks 等),不重叠本 gate 负责的对外可见文档维度。完整责任划分见 references/responsibility-matrix.md。
本 skill 融合以下已验证方法。每条方法在 Workflow 中有对应落地步骤。
| 方法 | 核心原则 | 落地步骤 |
|---|---|---|
| Three-Section Skill Contract (HF native) | 与 hf-regression-gate / hf-completion-gate 同形态:Hard Gates + Verification + fresh evidence | 整 SKILL 段落布局 |
| Sync-on-Presence | 未启用文档载体不构成 blocked;档 0/1/2 任一档下,未启用的 docs/ 子目录视为 N/A,不计入扣分维度 | 步骤 3 §维度判定 + FR-003 / NFR-004 |
| Profile-Aware Rigor | lightweight / standard / full 三档强制维度按 references/profile-rubric.md 激活;profile 升档不会回填已通过的轻档维度,但要求新增维度全部覆盖 | 步骤 2 §profile 激活 + FR-004 |
| Author/Reviewer/Gate Separation | gate 由独立 readonly reviewer subagent 派发;不自审自交;author / reviewer / gate 三层独立、verdict 由 reviewer 给出,gate 只汇总并落盘 | 步骤 1 §dispatch + FR-008 |
| Evidence Bundle Pattern | verdict 路径作为 hf-completion-gate evidence bundle 一项被 reference;evidence 必须具备 fresh 性(绑定上游 record / artifact hash),不能引用历史结论 | 步骤 4 §evidence 落盘 + FR-005 |
适用:
hf-regression-gate,即将进入 hf-completion-gate,需要本 gate verdict 作为 evidence bundle 一项references/reviewer-dispatch-handoff.md 派发执行本 gate不适用:
hf-regression-gate → 回 hf-test-driven-dev 或上游 review skillRed Flags 列出的"误以为强制 lint 工具"模式自纠hf-workflow-routerhf-test-driven-dev) 自评(FR-008 + CON-006){pass, partial, N/A, blocked},不允许其他词表值(FR-002)features/<active>/verification/doc-freshness-YYYY-MM-DD.md(FR-002 + CON-007)N/A,不构成 blocked(FR-003 + NFR-004)hf-traceability-review(FR-001 负路径)hf-increment(FR-007 负路径)hf-finalize 既有合同覆盖的同步动作(ADR 状态翻转 / CHANGELOG / 顶层导航 / docs/architecture / docs/runbooks 等);不修改 hf-finalize / hf-completion-gate / hf-code-review / hf-traceability-review / hf-increment 的 SKILL.md(CON-001 + FR-006 + FR-007)lightweight profile 不允许退化为跳过;至少强制仓库根 README 产品介绍段 + Conventional Commits docs: 标记自检(FR-004 + CON-005)按 references/reviewer-dispatch-handoff.md(复用既有 hf-workflow-router/references/review-dispatch-protocol.md 的本 gate 适配点)派发独立 reviewer subagent,readonly 模式。
reviewer 按以下顺序读取输入(FR-001 + FR-004):
features/<active>/spec.md 中本任务 / 本 feature 关联 FR / NFR 条目features/<active>/tasks.md 中本任务 Acceptance(如适用)feat: / fix: / BREAKING CHANGE: / docs: 条目features/<active>/progress.md 中 Workflow Profile 字段references/responsibility-matrix.md(spec §6.2 责任矩阵权威 cold-link)references/profile-rubric.md(按上一步读到的 profile 激活强制维度)references/responsibility-matrix.md 本 gate ✅ 行清单逐项检查)判定优先级:spec FR/NFR 关联 > tasks Acceptance > Conventional Commits(按可信度)。
形成 user-visible behavior change list(FR-001)。若三类来源全缺 → 进入步骤 4 输出 verdict = blocked,next = hf-traceability-review。
按 references/profile-rubric.md 激活的强制维度逐项判定,每个维度的 verdict ∈ {pass, partial, N/A, blocked}:
| 判定情形 | 维度 verdict | evidence 标注 |
|---|---|---|
| 项目载体不存在(FR-003 sync-on-presence + NFR-004) | N/A | "项目当前未启用此资产" |
| 本任务未触发该载体的同步需求(user-visible change list 与该载体无关) | N/A | "本 task / feature 未触发该资产变化" |
| 文档已同步 | pass | 引用 commits / file diff |
| 部分维度未同步且不阻塞 closeout | partial | 列出未同步项 + 影响评估 |
| 关键维度漂移(如仓库根 README 产品介绍段与本次行为相关部分明显过期) | blocked | next = hf-test-driven-dev(补文档变更) |
| spec 与 commits 实质不一致 | blocked | next = hf-increment(FR-007) |
整体 verdict 聚合规则:
blocked → 整体 verdict = blockedpartial → 整体 verdict = partial{pass, N/A} → 整体 verdict = pass(如果至少一个 pass)或 N/A(全部 N/A)按 templates/verdict-record-template.md 写入 features/<active>/verification/doc-freshness-YYYY-MM-DD.md,至少包含:
references/reviewer-dispatch-handoff.md)可选 diff log 落到 features/<active>/evidence/doc-freshness-diff-*.log。
lightweight profile 下使用 templates/lightweight-checklist-template.md,verdict 文件 ≤ 30 行(NFR-002)。
按 reviewer-return JSON 中 next_action_or_recommended_skill 路由:
pass / partial / N/A → next = hf-completion-gate(verdict 路径作为 evidence bundle 一项被 reference;FR-005)blocked (内容) → next = hf-test-driven-dev(补文档变更;FR-005 第三条 acceptance)blocked (workflow) → next = hf-workflow-router (reroute_via_router=true)重要:blocked verdict 不进入 hf-completion-gate evidence bundle;由本 gate 直接路由回 hf-test-driven-dev,避免 completion-gate 引入 doc-freshness blocked 的额外判定分支(design §11 boundary constraints)。
完成时产出:
features/<active>/verification/doc-freshness-YYYY-MM-DD.mdfeatures/<active>/evidence/doc-freshness-diff-*.logconclusion / next_action_or_recommended_skill / record_path / dimension_breakdown / reroute_via_routerhf-completion-gate evidence bundle(仅当 verdict ∈ {pass, partial, N/A}):verdict 路径作为 evidence bundle 一项被 referencereviewer-return JSON 不得伪造 verdict;不得为让本 gate "看起来通过" 而擅自把 partial / blocked 改写成 pass。
按需加载详细参考内容。
| 主题 | Reference | 加载时机 | 最小 profile |
|---|---|---|---|
| 责任矩阵权威 cold-link | references/responsibility-matrix.md | 每次 reviewer dispatch;判定每个维度归属时 | 全档必读 |
| Profile 强制维度判定细则 | references/profile-rubric.md | 步骤 2 激活 profile 时 | 全档必读 |
| Reviewer dispatch 适配点 | references/reviewer-dispatch-handoff.md | 步骤 1 父会话派发时 | 全档必读 |
| verdict 文件模板 | templates/verdict-record-template.md | 步骤 4 写 evidence 时 | standard / full 必读;lightweight 用下行模板 |
| Lightweight checklist 模板 | templates/lightweight-checklist-template.md | lightweight profile 步骤 4 | lightweight 必读 |
| 测试 prompts | evals/test-prompts.json | reviewer 派发前回归测试 | 全档可选 |
加载策略:
lightweight:默认读 responsibility-matrix.md + profile-rubric.md + lightweight-checklist-template.md + reviewer-dispatch-handoff.mdstandard / full:在 lightweight 基础上加 verdict-record-template.md| 易混淆 skill | 区别 |
|---|---|
hf-completion-gate | completion-gate 判断"任务是否真的可以宣告完成"(含本 gate verdict 作为 evidence bundle 一项);本 gate 只回答"对外可见文档是否同步"这一窄问题 |
hf-finalize | finalize 在 closeout 阶段同步既有合同覆盖的长期资产(CHANGELOG / ADR / 顶层导航 / docs/architecture / docs/runbooks 等);本 gate 不重叠这些维度(spec §6.2 责任矩阵) |
hf-increment | increment 处理范围变更与工件失效;本 gate 在 spec 与 commits 实质不一致时显式 next = increment(FR-007),但本 gate 不做范围变更分析 |
hf-code-review | code-review 检查实现层正确性 / 设计 conformance / Two Hats 纪律;本 gate 不评估代码本身,只评估对外可见文档是否同步 |
hf-traceability-review | traceability-review 反查 spec ↔ design ↔ tasks ↔ code ↔ tests 追溯链;本 gate 在 user-visible change list 三类来源全缺时显式 next = traceability-review(FR-001),但本 gate 不做追溯链反查 |
{pass, partial, N/A, blocked} 严格闭集{pass, partial, N/A, blocked}features/<active>/verification/doc-freshness-YYYY-MM-DD.mdreferences/profile-rubric.md 激活N/A + 显式标注理由(FR-003 + NFR-004)lightweight profile 下 verdict 文件 ≤ 30 行(NFR-002)+ 至少含仓库根 README 维度pass / partial / N/A → next = hf-completion-gate,verdict 路径已 reference 到 completion-gate evidence bundleblocked → next = hf-test-driven-dev(FR-005 第三条)或 hf-increment(FR-007)或 hf-workflow-router(precheck workflow 阻塞)hf-finalize / hf-code-review / hf-traceability-review / hf-increment 既有职责