Skip to content
Merged
136 changes: 136 additions & 0 deletions TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/plan.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
# Plan — 放宽 TaskFlow 文档内容约束
> Task version: v1
> Status: completed

## Spec Pointers

- `spec.md`

## Reference Pointers

- Repository document: `CONTRIBUTING.md` — 使用独立任务分支,代码与任务文档保持一致。
- Repository document: `CODE_STYLE.md` — 任务文档和 shell 使用既有约定,不引入额外依赖。
- Repository document: `README.md` — 验证现有生命周期说明和平台测试命令。
- Repository document: `LICENSE` — 项目使用 AGPL-3.0,不改变许可。

## Related Tasks

- 关联 `TF-20261110-84d1a9`:该任务审视总体流程与 Token;本任务独立处理文档扩展与解析兼容。

## Skills / Tools Used

- [PRD] Declared `agent-skills:spec-driven-development` — 用六个规格维度拆解目标和验收,依据仓库任务文档格式归档。
- [Spec] Declared `agent-skills:spec-driven-development` — 使用边界、接口、测试与成功标准组织设计。
- [Plan] Declared `agent-skills:planning-and-task-breakdown` — 将调查、修复与验收拆成可验证步骤。
- [Test] Unaided — 初始测试策略以仓库脚本制定;considered: testing strategy
- 实际读取并使用 `agent-skills:test-driven-development`:先复现审批、归档和步骤问题,再添加回归与修复;宿主没有记录技能调用事件。

## Preconditions

- [x] 用户批准 v1 范围与实施计划。

## Plan Review

- Verdict: sound
- Coverage: 验收 1–3 由步骤 1–2 调查与修复并以生命周期测试验证;验收 4–6 由步骤 2–3 的反例、回归、文档对照和复杂度样例审查覆盖。
- Verifiability: 各步骤的检查分别验证根因、正反例及完整生命周期,不能把示例检查当作真实审批验证。
- Layer ownership: 在负责读取或写入的解析层修复误判;不通过改测试期望或伪造流程标记绕过检查。

## Approval

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

## Steps

### Step 1 — 调查扩展内容和解析边界

- Goal: 追踪 PRD、Spec、Plan 的相关读取与写入,重现误判,并调查模板、工具输出路由和审查引导是否造成内容过度压缩。
- Dependencies: 用户批准。
- Files: `hooks/task`, `hooks/completion-gate`, `hooks/approval-check`, `hooks/version`, `hooks/archive`, 现有测试和技能说明。
- Implementation checklist:
- [x] 列出调用者及相关解析规则,重现误判。
- [x] 将发现和具体修复边界记录在计划中。
- Acceptance: 明确何处允许附加内容,何处存在可复现的错误及其责任层。
- Verification: 针对现有生命周期路径执行最小反例并记录输出。
- Rollback: 不修改产品行为;保留调查证据。
- Status: done

### Step 2 — 修复解析与内容保留

- Goal: 允许约定范围的工具补充内容,同时保留必需字段和真实未完成事项检查;按复杂度引导保留实施和验收所需细节。
- Dependencies: Step 1。
- Files: 由 Step 1 确定的责任 hooks、相关现有测试和 TaskFlow 技能文档。
- Implementation checklist:
- [x] 先编写覆盖真实误判及安全反例的失败测试。
- [x] 在责任层做最小修复,并更新说明。
- Acceptance: PRD 验收 1–4 的正反例通过,修改后内容保留。
- Verification: 针对性测试及相关平台测试;检查每项真实阻断仍生效。
- Rollback: 使用本任务版本的 Git 回退点恢复变更。
- Status: done

### Step 3 — 生命周期验证与审查

- Goal: 核对文档、实现和用户验收的一致性。
- Dependencies: Step 2。
- Files: 任务计划和验证记录;必要时补充测试。
- Implementation checklist:
- [x] 测试真实审批、状态、版本与归档路径及补充内容保留。
- [x] 运行适用的 smoke、Windows 测试与 diff 检查并审阅变更。
- Acceptance: 六项验收各有证据,使用简单与复杂任务样例审查内容充分性,限制与未覆盖情况明确。
- Verification: 在 Verification / Review 章节记录命令和结果。
- Rollback: 回退本版本提交,不删除用户内容。
- Status: done

## Checkpoints

- v1 基线为任务创建时的 `origin/main` 提交;代码变更在本版本完成前建立 Git 提交。

## Verification / Review

- 2026-11-16 定向复现:围栏示例中的未勾选项曾阻止完成,示例审批曾被当作有效批准,重复审批章节曾被合并解读;修复后均按预期处理,真实未勾选项和未闭合围栏仍拒绝。
- 2026-11-16 定向复现:步骤更新、任务状态和版本转换曾改写围栏示例;步骤、状态更新和版本正例均已通过定向复测。
- 2026-11-16 定向复现:审批写入曾改写围栏中的示例审批块;修复后重放样例保留原文,真实审批仍写入。
- Git 回退点:`cc40415`、`4b1352b`、`7fdd165`、`ebe5a32`。
- 运行边界:首次完整测试因误判 Git Bash 的 `/tmp` 路径而中断,不计为通过;经 Windows 文件系统确认该目录实际映射到项目内 `reference/test-temp`。后续显式设置项目内临时目录和测试根目录。

- 规划调查:`hooks/completion-gate` 的全文件未勾选项匹配未排除围栏;`hooks/task` 按标题截取若干保留章节。后续已执行行为回归,结果见下。

- 验收 1、2:`hooks/smoke-test` 完成门及步骤/状态测试段通过;版本切换和归档定向样例确认补充章节、示例及已有 Todo Record 内容保留。
- 验收 3、4:重复审批章节、审批字段、步骤编号、计划审查;空批准人、未闭合围栏、真实未完成事项均拒绝;未闭合状态更新与未完成直接归档未改变原任务。归档正常对照通过。
- 验收 5、6:`skills/taskflow/SKILL.md` 与 `references/artifacts.md` 说明必需内容为下限、按复杂度保留细节并按可实施性审查;对照简单 README 任务和复杂远程 Issue 任务,避免以字数判断质量。`quick_validate.py skills/taskflow` 使用 torch 环境与 `PYTHONUTF8=1` 通过。
- Windows 全量 `hooks/smoke-test-windows.ps1`:隔离根 `reference/test-temp/windows-run-03`,通过含打开 stdin 的自检;该运行早于最后一轮重复字段/归档位置补充。最新代码的完成门、步骤、状态和归档 smoke 专项通过;审批专项在最终空白批准人微调前通过,最终门禁专项覆盖该微调。
- 完整 Bash smoke 在本机精简 PATH 环境中因 Git Bash 的模拟链接缺少运行库而失败;已确认本机无权限建立原生符号链接,因此该项未通过,不计为产品失败或全套通过。
- `bash -n` 检查修改过的 hooks 通过;`git diff --check` 通过。未在 Linux / macOS 实机运行;未执行真实外部工具生成文档的宿主端到端验证,工具输出能力不能由格式测试证明。
- 层归属:修改 `approval-check`、`completion-gate`、`task`、`version`、`archive` 的实际读写逻辑并新增元数据读取器;未通过篡改旧期望伪造通过。新例测试示例内容和真实未完成事项的不同结果。
- PR 模板 `.github/pull_request_template.md`:Summary 说明补充内容与解析修复;TaskFlow traceability 记录任务、范围、目标仓库及 base;Verification 记录 CI、diff 和技能校验;Review boundaries 记录范围、隐私和剩余限制。CI 已运行,结果见下。
- 2026-11-17 PR #144 首次 CI:Ubuntu 大文档门禁测试因旧夹具包含重复审批状态而失败;将非结构性尾行改为普通说明,并新增明确的 `unchecked items` 拒绝原因断言,保留原大文件与管道边界覆盖。macOS Bash 3.2 无法解析 Task AWK heredoc 中不成对的反引号,改为等价字符编码;Windows CI 通过。上述是本任务实现及测试的工作修订,不改变批准范围。
- 2026-11-17 当前工作树完成门专项(含 >64KB 未勾选反例及 50 次大批准块)通过;修改后的 macOS Bash 3.2 行为已由下方 CI 复验。
- 2026-11-17 CI:代码提交 `90c9fee` 的 Hooks 工作流 https://github.com/hkwuks/TaskFlow/actions/runs/43999790222 通过 Ubuntu、macOS 和 Windows smoke、evals、Todo 合并审计及 CI 复用检查;release 为按条件跳过。macOS Bash 3.2 与大文档门禁均得到 CI 复验。
## Change Log

- v1 工作修订:按已批准验收补充围栏示例和审批歧义的实际根因与回归;PR CI 暴露的本任务夹具及 Bash 3.2 问题已修复并复验;不改变任务范围。

- v1:建立初始规格与计划;按用户补充加入文档内容充分性与防止过度压缩的引导和验收(批准前修订)。

## Follow-ups

- 本机完整 Bash smoke 因 Git Bash 符号链接限制未通过;Linux 和 macOS 已由 CI 验证,真实宿主工具输出仍待验证。
- 本次测试自建夹具已按用户授权清理;用户于 2026-11-17 验收任务。

- 若解析范围或安全边界需要偏离批准规格,先更新版本并重新确认。

## Version History

- v1 — planning。

## Todo Record

Moved verbatim from the TODO entry by `hooks/archive`, grouped by the field each block followed.

### `- Notes:`

- 与 TF-20261110-84d1a9 对流程和文档重复的审视相关,但本条聚焦 TaskFlow 对工具输出内容的约束;不预设修改现有条目。
53 changes: 53 additions & 0 deletions TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/prd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# 放宽 TaskFlow 文档内容约束,允许工具补充内容
> Task version: v1
> Status: completed

## Goal

TaskFlow 规定任务文档必需的事实与机器可解析边界,允许技能和工具补充有用内容。

## Task Kind

- Kind: capability

## Background / Confirmed Facts

现有 `skills/taskflow/references/artifacts.md` 允许未被匹配的标题,但 `hooks/completion-gate` 会扫描整个计划的未勾选项,代码块里的示例也会影响完成检查。`hooks/task` 和其他读写器还使用标题及字段定位结构,需要逐一核实。

## Requirements

- 规定必要内容与机器可解析边界,允许补充章节、正文和示例,不要求另一工具采用 TaskFlow 的完整模板。
- 必需的审批、步骤、验收和版本检查继续有效;补充内容不能伪造或覆盖这些事实。
- 审查各核心文档的读写、版本和归档路径,定位并修复由补充内容引发的实际误判或数据丢失。
- 文档说明支持的扩展形式和存在歧义时的处理,避免要求工具输出一律丢弃。
- 按任务复杂度和实际风险确定所需细节;避免模型把有价值的工具输出压缩为空泛摘要,并引导审查内容能否支持实施与验收。

## Acceptance Criteria

1. PRD、Spec 和 Plan 可以包含工具补充的非保留章节和正文,主要生命周期操作不丢失这些内容。
2. Plan 中受支持的代码围栏内示例不会被当成真实标题、步骤、审批字段或未勾选任务;围栏外真实未完成项目仍阻止完成。
3. 重复保留结构、未闭合围栏和其他无法可靠解析的情况明确处理,不静默通过审批或完成检查。
4. 必需字段、审批、真实任务步骤和版本归档原有安全检查保持有效,相关回归测试覆盖正反例。
5. 技能说明、示例和实际实现一致,核查外部技能的输出如何合并进权威任务文档。
6. 引导和审查基于任务复杂度及可实施性判断内容是否充分;复杂任务保留必要契约、边界、例子与验证依据,简单任务不设人为篇幅下限,检查不得把标题数量或字数当作质量证明。

## External Facts

- Depends on external facts: no
- Why not: 行为依据本仓库的 `hooks/completion-gate`、`hooks/task` 和 `skills/taskflow/references/artifacts.md`;外部技能只作为本地使用情境。

## In Scope

任务文档的内容约束、核心生命周期中解析与保留扩展内容、相关测试及说明。

## Out of Scope

Todo 后端重设计、额外外部服务、对已有历史文档的批量重写。

## Risks / Deferred Items

解析 Markdown 的变更不能把真实未完成任务藏进不会检查的区域;需检查围栏、缩进和保留标题的边界。具体支持集合在实现前通过代码调查确定。

## Open Questions

无;如调查发现安全边界无法同时满足上述验收,先提出方案并重新确认。
40 changes: 40 additions & 0 deletions TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Spec — 放宽 TaskFlow 文档内容约束
> Task version: v1

## Objective and Success Criteria

在保留 TaskFlow 必需事实及生命周期安全检查的前提下,让工具产生的有用章节、说明和示例进入现有权威文档。成功条件以 PRD 六项验收为准。

## Architecture Boundaries and Responsibilities

- `skills/taskflow/` 负责规定最低内容、可扩展内容和保留结构,不替外部技能定义完整模板。
- `hooks/task`、`hooks/completion-gate`、`hooks/approval-check`、`hooks/version`、`hooks/archive` 等各自拥有解析或修改任务文档的边界;先追踪实际调用与写入再选择共享或局部修复。
- 外部技能输出经审阅归入既有 PRD、Spec、Plan 或 reference,不形成冲突的任务事实源;保留对具体任务有用的契约、边界、示例和验证依据,不为匹配骨架而机械压缩。

## Project Structure / Affected Files

检查上述 hooks 及其调用者、`hooks/smoke-test`、Windows 启动器测试、`skills/taskflow/SKILL.md` 和 `skills/taskflow/references/artifacts.md`;根据调查确定实际改动,保持中英文说明一致。

## Interfaces, Data Flow, and Contracts

输入是含必需 TaskFlow 元数据及附加 Markdown 的任务文档。生命周期读取器仅将有效结构视为工作状态;写入器更新目标字段时保留其他内容。受支持围栏中的文本是示例,不产生字段、步骤或待办。无法判定的格式不得静默放行。

## Invariants and Compatibility

保留现有审批、版本、真实待办和步骤检查,不更改历史数据或主动转换用户内容。不引入未经授权的兼容层或依赖。

## Validation and Error Semantics

比较含与不含附加内容的等价文档;测试额外章节、围栏内伪结构、围栏外真实待办、未闭合围栏与重复保留结构,以及修改和归档后的内容完整性。明确拒绝无法安全判定的输入。用简单任务与复杂任务样例审查是否保留实施和验收所需的内容;不得用行数或标题数代替内容判断。

## Code and Test Constraints

遵循 `CODE_STYLE.md`,shell 使用仓库既有工具;先用失败测试证明具体误判,再修改责任层。运行针对性测试、适用的 Windows 测试和 `git diff --check`,必要时运行完整 smoke。

## Design Decisions and Alternatives

优先复用现有解析与测试机制;不以放松所有检查或仅新增流程标记代替功能修复。围栏语法和跨读取器共享方式以实际调用链和测试为依据,避免未核实地引入新框架。

## Open Questions

具体实现边界将在 Step 1 的代码与测试调查后收敛;若需改变上述契约则先回到用户确认。
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. -->

## 放宽 TaskFlow 文档内容约束,允许工具补充内容

- ID: TF-20261116-b893dc
- Status: done
- Goal: 调整 TaskFlow 文档要求,使其仅规定必须包含的内容,允许被引用的工具和技能按需写入更多内容,避免不必要的内容限制。
- Task: `TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/`
- Next action: None — completed and archived.

## 支持使用远程仓库 Issues 作为用户的待办列表

- ID: TF-20261116-7e2c41
Expand Down
1 change: 1 addition & 0 deletions hooks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,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
├── markdown-field # read task metadata outside fenced examples
├── 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)
Expand Down
37 changes: 30 additions & 7 deletions hooks/approval-check
Original file line number Diff line number Diff line change
Expand Up @@ -85,17 +85,40 @@ plan="$1"
# becomes a failed pipeline. Measured there on a 39 KB approval block, 16 times
# out of 200. Reading the file once has no such failure mode at any size.
result="$(awk -v stale_only="$stale_only" '
# Fenced Markdown is illustrative text, never task structure.
{
fence_line = $0
sub(/\r$/, "", fence_line)
for (indent = 0; indent < 3 && substr(fence_line, 1, 1) == " "; indent++) fence_line = substr(fence_line, 2)
marker = substr(fence_line, 1, 1)
run = 0
if (marker == "`" || marker == "~") {
while (substr(fence_line, run + 1, 1) == marker) run++
}
if (fence != "") {
if (marker == fence && run >= fence_len && substr(fence_line, run + 1) ~ /^[[:space:]]*$/) fence = ""
next
}
if (run >= 3 && (marker != "`" || index(substr(fence_line, run + 1), "`") == 0)) {
fence = marker; fence_len = run
next
}
}
/^## / { inap = 0 }
/^> Task version: v[0-9][0-9]*$/ {
if (ver == "") { ver = $0; sub(/^> Task version: /, "", ver) }
versions++; if (ver == "") { ver = $0; sub(/^> Task version: /, "", ver) }
next
}
/^## Approval$/ { inap = 1; next }
inap && $0 == "- Status: approved" { st = 1 }
inap && $0 == "- Approved by: pending" { pend = 1 }
inap && index($0, "- Approved version: ") == 1 { av = substr($0, 21) }
/^## Approval$/ { approvals++; inap = 1; next }
inap && /^### Step / { inap = 0; next }
inap && /^- Status:/ { status_fields++; if ($0 == "- Status: approved") st = 1 }
inap && /^- Approved by:/ { by_fields++; by = substr($0, 16); gsub(/^[[:space:]]+|[[:space:]]+$/, "", by); if (by == "pending") pend = 1 }
inap && index($0, "- Approved version: ") == 1 { version_fields++; av = substr($0, 21) }
END {
if (ver == "") { print "missing Plan Task version"; exit 1 }
if (fence != "") { print "unclosed Markdown fence"; exit 1 }
if (approvals > 1) { print "Plan has more than one Approval section"; exit 1 }
if (status_fields > 1 || by_fields > 1 || version_fields > 1) { print "Plan has ambiguous Approval fields"; exit 1 }
if (versions != 1) { print "missing or ambiguous Plan Task version"; exit 1 }
if (stale_only) {
# Only a superseded approval blocks a write. `pending` and an absent field
# are both "nothing approved yet", which is every task before its first
Expand All @@ -104,7 +127,7 @@ result="$(awk -v stale_only="$stale_only" '
print "this document was approved at " av " but the Plan now says " ver "; the approval does not cover it. Approve the document as it now stands: bash hooks/task approve <task-id>"
exit 1
}
if (!st || av != ver || pend) { print "current Task version is not approved"; exit 1 }
if (!st || by == "" || av != ver || pend) { print "current Task version is not approved"; exit 1 }
exit 0
}
' "$plan")" || { printf '%s\n' "$result" >&2; exit 1; }
Expand Down
Loading
Loading