Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 108 additions & 0 deletions TaskFlowDocs/achieved/2026-11-12-version-commits/plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# Plan — 仓库代码版本提交与回退点
> Task version: v1
> Status: completed

## Spec Pointers

- `spec.md`

## Reference Pointers

- `skills/taskflow/references/versioning-and-recovery.md`:逻辑版本与 Git 历史的关系。
- `hooks/task`、`hooks/version`、`hooks/archive`:版本起点与全部结束入口。
- `CONTRIBUTING.md`、`CODE_STYLE.md` 和 `TaskFlowDocs/repository-docs/index.md`:独立工作树、提交及项目规则。

## Related Tasks

- `TF-20261112-21a0ce`:能力选择与真实效果调查,独立实现与验收。
- `TF-20261008-ca2fce`:长程任务兼容性待办,本任务不更改其状态。

## Skills / Tools Used

- [PRD] Unaided — 根据用户决定界定仓库级需求;considered: requirements elicitation
- [Spec] Unaided — 对照现有生命周期入口和 Git 状态设计;considered: architecture and design
- [Plan] Unaided — 首次制定时自行拆解;considered: work breakdown
- [Test] Unaided — 设计真实 Git 场景;considered: testing strategy
- 复审时读取 `agent-skills:planning-and-task-breakdown`,按依赖和可验证性修订方案;首次阶段已登记 unaided,不将本次读取伪称宿主观察。

## Preconditions

- 工作区:`D:/WorkSpace/Agent/TaskFlow/.worktrees/task-version-commits`,分支 `feature/task-version-commits`。
- 用户明确批准本版本计划后才开始产品实现。

## Plan Review

- Verdict: sound
- Coverage: PRD 关于仓库提交、纯任务记录及保守路径边界由 Step 1 覆盖;阶段性提交指导和恢复边界由 Step 2 覆盖;自动验证和不破坏用户文件由两步的真实 Git 验证覆盖。
- Verifiability: 测试以实际 Git 提交、工作区与退出状态检查条件;包含提交前拒绝和提交后成功的对照,以及直接 archive 和失败后文档不变,避免仅凭字符串或标记通过。忽略文件与人为归属不可验证,作为限制而非保证。
- Layer ownership: 版本基线与检查由生命周期脚本负责;现有 fixture 若因新基线契约改变,只在真正代表合法任务时补真实 Git 初始状态,绝不通过放宽检查让测试绿。

## Approval

- Status: approved
- Approved by: user
- Approved at: 2026-11-12 16:05 +0800
- Approved version: v1
- Approved scope: PRD / Spec / Plan

## Steps

### Step 1 — 建立版本起点与 Git 检查

- Goal: 为各任务版本建立 Git 起点,并在升版、完成和直接归档前检查整个仓库。
- Dependencies: 本计划获得用户批准。
- Files: `hooks/task`、`hooks/version`、`hooks/archive`、共享 Git 检查脚本和现有 smoke tests。
- Implementation checklist:
- [x] 实现独立 worktree 的任务版本基线、出错回滚与仓库状态检查。
- [x] 将检查接入三个结束入口并保留纯任务记录免提交行为。
- [x] 以真实 Git 仓库覆盖提交、有未提交内容、版本切换、缺失基线、路径边界和并行 worktree。
- Acceptance: 当前任务记录以外的改动须在版本结束前提交;未提交、不可验证或已改写历史时不执行版本切换及归档,不更改用户文件。
- Verification: 对真实 Git 场景运行定向自动测试,断言实际提交范围、文件内容与失败前后的状态;运行相关 smoke。
- Rollback: 在任务分支回退本步骤提交。
- Status: done

### Step 2 — 规则和端到端复核

- Goal: 解释版本回退点和按影响增加提交的做法,明确用户数据、忽略文件和历史改写边界。
- Dependencies: Step 1。
- Files: `skills/taskflow/SKILL.md`、`skills/taskflow/references/versioning-and-recovery.md`、相关测试。
- Implementation checklist:
- [x] 更新版本、提交、恢复和失败处理指导。
- [x] 核对各入口及真实 Git 测试,运行适用项目检查并记录限制。
- Acceptance: 工作流规则与实际检查一致;Git 未能证明的归属和远端留存不被表述为已保证。
- Verification: 用户场景复核、针对性测试、项目规定的适用检查与差异审查。
- Rollback: 回退本步骤提交。
- Status: done

## Checkpoints

完成 Step 1 后核对失败不改用户文件;按变更影响创建聚焦提交。

## Verification / Review

- 已在 `hooks/version-baseline` 实现任务版本 Git 起点与工作区检查,接入 `promote`、`version`、`complete` 和 `archive`;当前任务在首次改代码前记录 v1 起点 `b502679ef2b517376336891a5524824c106e2c64`。
- 在 Git 元数据下保留真实仓库夹具:暂存、未暂存、未跟踪、其他任务文档、空格和中文路径、暂存删除、重命名、版本切换、直接归档、complete、worktree 隔离和非祖先历史均验证通过;每项拒绝均检查工作区或文档未被归档/升版。
- `bash -n` 覆盖六个修改或新增的 shell 脚本;`python evals/runner.py` 通过 6 项离线检查;`git diff --check` 通过。使用已有 torch Python 环境并设置 `PYTHONUTF8=1` 后,Skill 校验通过;默认 Python 缺少 PyYAML,未安装依赖。
- 用户同意清理测试自己新建的文件;在 WSL 私有内存挂载内移除 DAC 权限绕过能力后运行完整 `bash hooks/smoke-test`,结果 `ALL SMOKE PASSED`。该方式具备真实 Linux 不可写目录语义,Windows 专项子测试在前一轮单独通过;未运行 macOS CI。
- 采用 `agent-skills:code-review-and-quality` 自审 Git 入口、基线失败和数据保护;尚未有独立审查或三平台 CI。
- 审查中用真实 Git 夹具复现 `assume-unchanged` 会让已修改文件被普通状态检查漏掉;修复后拒绝隐藏索引路径,Windows 定向测试同时覆盖 `assume-unchanged` 与 `skip-worktree`,完整 Linux smoke 重跑 `ALL SMOKE PASSED`。
- 代码提交 `7fa00ab` 与 `1ddea08`;实际任务运行 `hooks/version-baseline check . 2026-11-12-version-commits v1` 通过,报告从 `b502679` 到 `1ddea08` 的提交范围。

- GitHub [Hooks CI](https://github.com/hkwuks/TaskFlow/actions/runs/43190832429) 在提交 `b3a90b7` 上通过 Ubuntu、macOS、Windows smoke、evals、Todo merge audit 和 CI 复用测试;release 按路径跳过。
- PR 模板 `.github/pull_request_template.md`:Summary 说明版本回退点及未提交变更拒绝;TaskFlow traceability 对应本任务、hooks/skill 范围、`hkwuks/TaskFlow:main`;Verification 对应 Hooks CI、`git diff --check`、Skill 校验及本 Plan;Review boundaries 对应秘密、文件范围、远端/基线和已知限制。
- 2026-11-12 只读核对 `origin` 为 `https://github.com/hkwuks/TaskFlow.git`,GitHub 默认分支 `main`,非 fork;`git ls-remote` 的 main 为 `b502679ef2b517376336891a5524824c106e2c64`,是当前任务分支祖先;远端状态会随时间变化。
- 已审查工作树变更只涉及本任务记录及已提交的 hooks / skill 文件;测试使用虚构 Git 夹具,不纳入凭据或用户文件。忽略文件、旧任务基线缺失和本地基线丢失的限制已写入 `spec.md`。

## Change Log

- 2026-11-12:用户明确检查整个仓库;复审补入可独立调用的 archive。
- 2026-11-12:用户确认 TaskFlow 任务记录以外的仓库路径采用保守提交规则;明确工作树起点、不可恢复历史与忽略文件边界。
- 2026-11-12:用户批准 v1;完成实现、定向 Git 验证和完整 Linux smoke,Windows 专项子测试通过;发现并修复 Git 隐藏索引标记绕过后重跑 smoke。

## Follow-ups

无。

## Version History

- v1 — ready,等待用户批准。
51 changes: 51 additions & 0 deletions TaskFlowDocs/achieved/2026-11-12-version-commits/prd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# 仓库代码版本提交与回退点
> Task version: v1
> Status: completed

## Goal

保证 Git 仓库的每个有代码迭代的 TaskFlow 任务版本至少有一个包含该版本仓库改动的提交,以便溯源和回退;根据改动影响适时增加聚焦提交。

## Task Kind

- Kind: capability

## Background / Confirmed Facts

现有版本工具仅检查选定任务文档,完成流程不检查仓库代码提交。用户明确检查范围是整个仓库,不是仅检查任务文档。

## Requirements

- 对所有使用 Git 的 TaskFlow 开发任务,以任务版本作为最低检查边界。
- 有仓库代码或运行配置等开发改动的版本,在进入下一版本或完成前至少有涵盖该版本改动的提交;任务文档提交不能单独充当代码提交。
- 基于改动影响合理增加提交;不自动提交或推送,不纳入不属于任务的改动。
- 当前任务目录与 Todo 的 TaskFlow 任务记录可免提交;仓库其他路径的改动(包括 README、配置及设计文档)均按用户确认的保守规则纳入检查。没有其他路径改动的版本无需空提交。检查无法确定时明确提示,不凭任务文档内容宣称代码已提交。
- 检查整个仓库的已提交和未提交变更,包含暂存与未跟踪文件;保留已有用户文件和任务数据。

## Acceptance Criteria

- 版本切换与任务完成路径能发现缺失代码提交或尚未提交的仓库开发改动,并在操作前阻止。
- 已提交开发改动可通过;纯设计版本可通过;纯文档提交不能冒充代码提交。
- 不依靠文件扩展名判断代码;对无法自动归属的变更提供清晰可核验的处理方式,不静默放行、不自动提交用户改动。
- 自动化验证覆盖多版本、已提交和未提交文件、纯设计版本以及边界和失败场景。

## External Facts

- Depends on external facts: no
- Why not: 任务生命周期由 `hooks/task`、`hooks/version` 和 `hooks/archive` 决定;提交边界由用户确定并以本地 Git 状态验证。

## In Scope

仓库级版本回退点、阶段检查、工作流说明与测试。

## Out of Scope

自动提交、推送、重写历史、对已有任务历史追溯补造提交。

## Risks / Deferred Items

Git 本身不能自动判断改动归属或文件语义;需要明确基线和对不确定情况的可审计处理,不能将任意提交视为充分证据。

## Open Questions

无。2026-11-12 用户确认仓库其他路径的设计文档也按保守规则要求提交。
43 changes: 43 additions & 0 deletions TaskFlowDocs/achieved/2026-11-12-version-commits/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Spec — 仓库代码版本提交与回退点
> Task version: v1

## Objective and Success Criteria

Git 任务的每个版本若修改当前任务记录以外的仓库路径,在升版或完成前必须将这些改动提交到该任务分支,形成可追溯的版本回退点。

## Architecture Boundaries and Responsibilities

`hooks/task promote` 为 v1 建立版本起点;`hooks/version` 在修改文档前检查旧版本,并为新版本建立起点;`hooks/task complete` 与可独立调用的 `hooks/archive` 在改变状态或移动文件前检查。共享检查只读取 Git 状态和版本起点,不提交、推送或清理文件。

## Project Structure / Affected Files

`hooks/task`、`hooks/version`、`hooks/archive`、共享检查脚本、现有 smoke tests、`skills/taskflow/SKILL.md` 和 `skills/taskflow/references/versioning-and-recovery.md`。

## Interfaces, Data Flow, and Contracts

- 版本起点是该 worktree 的 Git HEAD 提交,按任务 ID 与版本保存在 worktree 独立的 Git 元数据中;不得在结束时用当前 HEAD 补造起点。v1 在 promote 时建立;升版先验证旧版本,再以当前 HEAD 建立新版本起点。失败时不得留下被误认为有效的半成品或修改用户代码。
- 建立起点前,检查暂存、未暂存和未跟踪的非忽略文件;仅排除当前任务的 `TaskFlowDocs/<task-id>/` 与 `TaskFlowDocs/todo.md`。其他路径如已有未提交内容,列出并拒绝建立基线,不自动提交或删除。Git 忽略文件不纳入,须如实说明。
- 结束或升版前验证基线存在、指向有效提交且为 HEAD 的祖先;检查该 worktree 暂存、未暂存及未跟踪的非忽略文件。当前任务目录和 Todo 以外有未提交变更则拒绝;若基线后存在涉及这些路径的提交,记录可回溯的提交范围;仅有任务记录变更可通过,无需空提交。
- 必须检查整个仓库,不能按后缀判定代码。用户确认 TaskFlow 任务记录之外的 README 等设计文档也视作需要提交的改动;其他任务文件也不能作为本任务自动排除。
- 文件路径含空格、中文、换行、重命名和删除时必须正确处理;不可将其他人的未提交文件加入提交。路径归属无法由 Git 自动证明,隔离分支与清晰提示是前提;不得声称排他归属已被机器证明。
- 版本状态和文档在任一检查失败时保持原状。不存在有效基线、提交已被历史改写移除、Git 错误或存在不明未提交内容时拒绝并说明原因;不静默建立补造基线。非 Git 仓库按现行行为处理。

## Invariants and Compatibility

基线按 worktree、任务、版本隔离;检查不修改 Git 用户内容。旧活动任务或丢失本机基线的任务没有可靠起点时明确阻止,不能伪造过去版本的提交;不引入自动兼容或绕过逻辑。Git 忽略文件不受保护,本地提交也不保证后续 squash/rebase 或远端仍保留同一提交点。

## Validation and Error Semantics

以独立的真实 Git 仓库验证:仓库文件提交后通过;仅任务记录无需提交;非任务文档路径也要求提交;暂存、未暂存、未跟踪、重命名、删除、空格与中文路径正确判断;缺失基线、无祖先关系、版本切换、直接 archive 和失败不改状态;并行 worktree 互不串扰。断言 Git 内容和状态而非单纯匹配标记。

## Code and Test Constraints

沿用 shell 和项目现有 smoke 测试,无新增依赖;不写自动提交或推送代码;跨平台处理 Git 路径及错误。

## Design Decisions and Alternatives

用户选择将 TaskFlow 任务记录以外的仓库路径保守视为需要提交,避免不可靠的代码后缀推断。Git 可验证范围和内容,不能证明每个提交是否由该任务创造;不应把无关提交、忽略文件或远端留存视为已受保证。

## Open Questions

无;如果实现验证显示无法可靠记录版本起点或保持失败无副作用,停止并重新设计。
8 changes: 8 additions & 0 deletions TaskFlowDocs/todo.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ has an issue number or URL.

<!-- Add new items at the top using the template below. -->

## 长程任务的每个代码迭代版本至少一次 Git 提交,并按改动影

- ID: TF-20261112-8dd98e
- Status: done
- Goal: 长程任务的每个代码迭代版本至少一次 Git 提交,并按改动影响适时增加提交,确保溯源和回退
- Task: `TaskFlowDocs/achieved/2026-11-12-version-commits/`
- Next action: None — completed and archived.

## 在真实 GitHub PR 中验证已合并的文档跟进 CI 复用及失败回退

- ID: TF-20261110-8c4e24
Expand Down
2 changes: 2 additions & 0 deletions hooks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ taskflow/hooks/
├── task-id # the one rule for what is a legal task name; used by task/archive/reopen
├── approval-check # the one rule for whether a Plan's current version is approved
├── completion-gate # the one rule for what counts as an approved, finished Plan
├── version-baseline # verify each task version has a Git rollback point
├── task # explicit intake/promote/unpromote/state/progress/unaided/recover/complete edits
├── archive # full archive transaction (incl. Todo update)
├── version # atomic version transition (changed docs only)
Expand All @@ -42,6 +43,7 @@ taskflow/hooks/
├── run-hook.cmd # cross-platform launcher (polyglot batch/bash)
├── test-host-parity # synthetic host event and capability declaration fixture
├── smoke-test-windows.ps1 # Windows PowerShell/cmd lifecycle regression
├── test-version-baseline # real Git lifecycle regression fixture
└── smoke-test # assert-style smoke tests
```

Expand Down
2 changes: 2 additions & 0 deletions hooks/archive
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ grep -q '> Status: completed' "$docs/$task/plan.md" || { echo "plan.md not compl
# enters the rollback path — the active directory, the Todo and the absent
# achieved path are all untouched.
bash "$HERE/completion-gate" "$docs/$task" || exit 1
version="$(sed -n 's/^> Task version: //p' "$docs/$task/plan.md" | head -1)"
bash "$HERE/version-baseline" check "$root" "$task" "$version" || exit 1

todo="$docs/todo.md"
[ -f "$todo" ] || { echo "todo.md missing; archive not started"; exit 1; }
Expand Down
Loading
Loading