From cc4041515ef344ea27c80f50eb9ea36bd5595053 Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:36:04 +0800 Subject: [PATCH 1/9] fix: ignore fenced examples in completion gates --- hooks/approval-check | 20 ++++++++++++++++++++ hooks/completion-gate | 20 ++++++++++++++++++++ hooks/smoke-test | 21 +++++++++++++++++++++ 3 files changed, 61 insertions(+) diff --git a/hooks/approval-check b/hooks/approval-check index c459630..7476468 100644 --- a/hooks/approval-check +++ b/hooks/approval-check @@ -85,6 +85,25 @@ 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) } @@ -95,6 +114,7 @@ result="$(awk -v stale_only="$stale_only" ' inap && $0 == "- Approved by: pending" { pend = 1 } inap && index($0, "- Approved version: ") == 1 { av = substr($0, 21) } END { + if (fence != "") { print "unclosed Markdown fence"; exit 1 } if (ver == "") { print "missing Plan Task version"; exit 1 } if (stale_only) { # Only a superseded approval blocks a write. `pending` and an absent field diff --git a/hooks/completion-gate b/hooks/completion-gate index 0c6df7f..eeae548 100644 --- a/hooks/completion-gate +++ b/hooks/completion-gate @@ -99,6 +99,25 @@ result="$(awk -v approval_only="$approval_only" ' instep = 0; closed = 0; nstat = 0 } BEGIN { bad = 0 } + # 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 + } + } /^## / { flush() } /^### Step / { flush() @@ -133,6 +152,7 @@ result="$(awk -v approval_only="$approval_only" ' closed = ($0 ~ /^- Status:[[:space:]]*done[[:space:]]*$/) } END { + if (fence != "") { print "unclosed Markdown fence"; exit 1 } flush() if (approval_only) { exit 0 } # Checked before `unchecked` and `unfinished`, because it is the one failure diff --git a/hooks/smoke-test b/hooks/smoke-test index 15343c7..f763698 100755 --- a/hooks/smoke-test +++ b/hooks/smoke-test @@ -69,6 +69,27 @@ cg_case clean 0 '' "$cg_approved### Step 1 — a - [x] done - Status: done " +# Markdown examples are data: they cannot grant approval or leave work open. +cg_case fenced-example 0 '' "${cg_approved}"'### Step 1 — real +- Status: done +## Example +````markdown +### Step 99 — example +- Status: pending +- [ ] example only +```` +' +cg_case fenced-fake-approval 1 'not approved' '> Task version: v1 +## Approval +- Status: requested +## Example +```markdown +## Approval +- Status: approved +- Approved by: user +- Approved version: v1 +``` +' cg_case unapproved 1 'not approved' '> Task version: v1 ## Approval - Status: requested From 4b1352ba22d877af82c2d6957af4ccadfaaaf948 Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Mon, 16 Nov 2026 22:38:54 +0800 Subject: [PATCH 2/9] fix: reject ambiguous approvals and preserve step examples --- hooks/approval-check | 3 ++- hooks/smoke-test | 29 +++++++++++++++++++++++++++++ hooks/task | 27 ++++++++++++++++++++++----- 3 files changed, 53 insertions(+), 6 deletions(-) diff --git a/hooks/approval-check b/hooks/approval-check index 7476468..9ff4a65 100644 --- a/hooks/approval-check +++ b/hooks/approval-check @@ -109,12 +109,13 @@ result="$(awk -v stale_only="$stale_only" ' if (ver == "") { ver = $0; sub(/^> Task version: /, "", ver) } next } - /^## Approval$/ { inap = 1; next } + /^## Approval$/ { approvals++; 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) } END { if (fence != "") { print "unclosed Markdown fence"; exit 1 } + if (approvals > 1) { print "Plan has more than one Approval section"; exit 1 } if (ver == "") { print "missing Plan Task version"; exit 1 } if (stale_only) { # Only a superseded approval blocks a write. `pending` and an absent field diff --git a/hooks/smoke-test b/hooks/smoke-test index f763698..96255b4 100755 --- a/hooks/smoke-test +++ b/hooks/smoke-test @@ -90,6 +90,14 @@ cg_case fenced-fake-approval 1 'not approved' '> Task version: v1 - Approved version: v1 ``` ' +cg_case duplicate-approval 1 'more than one Approval' '> Task version: v1 +## Approval +- Status: requested +## Approval +- Status: approved +- Approved by: user +- Approved version: v1 +' cg_case unapproved 1 'not approved' '> Task version: v1 ## Approval - Status: requested @@ -268,6 +276,27 @@ cg_case approval-only-not-done 0 '' "${cg_approved}## Steps ### Step 1 — a - Status: completed " '--approval-only' +# A fenced Step is an example; progress must update the real Step only. +progress_fence="$tmp/progress-fence" +mkdir -p "$progress_fence/TaskFlowDocs/2026-01-01-example" +printf '%s' "${cg_approved}"'## Example +```markdown +### Step 1 — example +- Status: pending +``` +## Steps +### Step 1 — real +- Status: pending +' > "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" +bash "$HERE/task" progress 2026-01-01-example 1 done --root "$progress_fence" >/dev/null +awk ' + /^### Step 1 — example$/ { example = 1; next } + /^```$/ { example = 0 } + /^### Step 1 — real$/ { real = 1; next } + example && $0 == "- Status: pending" { example_ok = 1 } + real && $0 == "- Status: done" { real_ok = 1 } + END { exit !(example_ok && real_ok) } +' "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" || { echo 'FAIL progress edited fenced example'; exit 1; } # A promotion that never got a Plan is the case `task complete` can reach, # because `task_paths` only requires the directory. The gate says so in words # rather than letting awk report a missing file. diff --git a/hooks/task b/hooks/task index 17bc7c6..4490f32 100755 --- a/hooks/task +++ b/hooks/task @@ -423,6 +423,21 @@ function overlap( w) { } { n++; line[n] = $0 } END { + if (cmd == "step") { + for (i = 1; i <= n; i++) { + text = line[i]; sub(/\r$/, "", text) + for (indent = 0; indent < 3 && substr(text, 1, 1) == " "; indent++) text = substr(text, 2) + marker = substr(text, 1, 1); run = 0 + if (marker == "`" || marker == "~") while (substr(text, run + 1, 1) == marker) run++ + if (fence != "") { + fenced[i] = 1 + if (marker == fence && run >= fence_len && substr(text, run + 1) ~ /^[[:space:]]*$/) fence = "" + } else if (run >= 3 && (marker != "`" || index(substr(text, run + 1), "`") == 0)) { + fenced[i] = 1; fence = marker; fence_len = run + } + } + if (fence != "") die("unclosed Markdown fence") + } scan() if (cmd == "get") { @@ -561,7 +576,7 @@ END { if (cmd == "step") { a = 0; b = 0 for (i = 1; i <= n; i++) { - if (at(line[i], "### Step ")) { + if (!fenced[i] && at(line[i], "### Step ")) { rest = substr(line[i], 10) if (match(rest, /^[0-9]+/)) { num = substr(rest, 1, RLENGTH) @@ -572,20 +587,22 @@ END { } if (a == 0) die("Step " step " not found") for (i = a + 1; i <= n; i++) { - if (at(line[i], "### Step ") || at(line[i], "## ")) break + if (!fenced[i] && (at(line[i], "### Step ") || at(line[i], "## "))) break } b = i - 1 if (step_status == "done") { for (i = a; i <= b; i++) { - if (line[i] ~ /^[[:space:]]*- \[ \]/) die("Step " step " has unchecked items") + if (!fenced[i] && line[i] ~ /^[[:space:]]*- \[ \]/) die("Step " step " has unchecked items") } } - if (!setr(a, b, "Status", step_status)) die("Step " step " missing Status") + status_line = 0; for (i = a; i <= b; i++) if (!fenced[i] && at(line[i], "- Status:")) { status_line = i; break } + if (!status_line) die("Step " step " missing Status") + line[status_line] = "- Status: " step_status if (verification != "") { vline = "- " today " Step " step ": " verification found = 0 for (i = 1; i <= n; i++) { - if (line[i] == "## Verification / Review") { + if (!fenced[i] && line[i] == "## Verification / Review") { # Equivalent to replacing "## Verification / Review\n" with # "## Verification / Review\n\n\n": a blank line and the entry are # inserted directly after the heading, and whatever followed stays. From 7fdd1655c16f384a5c1da5f0ef81de071a7aba5a Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:31:42 +0800 Subject: [PATCH 3/9] fix: preserve extended task documents across lifecycle --- hooks/approval-check | 4 +- hooks/archive | 46 ++++++++-- hooks/completion-gate | 10 +- hooks/markdown-field | 31 +++++++ hooks/smoke-test | 117 ++++++++++++++++++++++++ hooks/task | 54 ++++++++--- hooks/version | 44 +++++++-- skills/taskflow/SKILL.md | 1 + skills/taskflow/references/artifacts.md | 5 + 9 files changed, 282 insertions(+), 30 deletions(-) create mode 100644 hooks/markdown-field diff --git a/hooks/approval-check b/hooks/approval-check index 9ff4a65..c017c65 100644 --- a/hooks/approval-check +++ b/hooks/approval-check @@ -106,7 +106,7 @@ result="$(awk -v stale_only="$stale_only" ' } /^## / { 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$/ { approvals++; inap = 1; next } @@ -116,7 +116,7 @@ result="$(awk -v stale_only="$stale_only" ' END { if (fence != "") { print "unclosed Markdown fence"; exit 1 } if (approvals > 1) { print "Plan has more than one Approval section"; exit 1 } - if (ver == "") { print "missing Plan Task version"; 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 diff --git a/hooks/archive b/hooks/archive index e443512..0e24390 100755 --- a/hooks/archive +++ b/hooks/archive @@ -21,8 +21,8 @@ docs="$root/TaskFlowDocs" [ ! -e "$docs/achieved/$task" ] || { echo "achieved/$task already exists"; exit 1; } # 1. authoritative completion must already be recorded by the Agent -grep -q '> Status: completed' "$docs/$task/prd.md" || { echo "prd.md not completed"; exit 1; } -grep -q '> Status: completed' "$docs/$task/plan.md" || { echo "plan.md not completed"; exit 1; } +[ "$(bash "$HERE/markdown-field" Status "$docs/$task/prd.md")" = completed ] || { echo "prd.md not completed"; exit 1; } +[ "$(bash "$HERE/markdown-field" Status "$docs/$task/plan.md")" = completed ] || { echo "plan.md not completed"; exit 1; } # 1b. and the completion has to be real, not just recorded. # @@ -42,7 +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)" +todo_record_count="$(bash "$HERE/markdown-field" 'Todo Record' "$docs/$task/plan.md")" +version="$(bash "$HERE/markdown-field" 'Task version' "$docs/$task/plan.md")" bash "$HERE/version-baseline" check "$root" "$task" "$version" || exit 1 todo="$docs/todo.md" @@ -268,10 +269,41 @@ fi # prose has exactly one destination, and the only question is whether the # `## Todo Record` heading is already there (a reopened task, archived twice). if [ -s "$prose_tmp" ]; then - if ! grep -qx '## Todo Record' "$plan"; then + if [ "$todo_record_count" = 0 ]; then printf '\n## Todo Record\n\nMoved verbatim from the TODO entry by `hooks/archive`, grouped by the field each block followed.\n' >> "$plan" + cat "$prose_tmp" >> "$plan" + else + plan_tmp="$(mktemp "$docs/.taskflow-archive-insert.XXXXXX")" + if ! TASKFLOW_PROSE_FILE="$prose_tmp" awk ' + function append_prose( line, rc) { + while ((rc = getline line < ENVIRON["TASKFLOW_PROSE_FILE"]) > 0) print line + if (rc < 0) exit 1 + close(ENVIRON["TASKFLOW_PROSE_FILE"]); inserted = 1 + } + { + text = $0; sub(/\r$/, "", text) + for (indent = 0; indent < 3 && substr(text, 1, 1) == " "; indent++) text = substr(text, 2) + marker = substr(text, 1, 1); run = 0 + if (marker == "`" || marker == "~") while (substr(text, run + 1, 1) == marker) run++ + if (fence != "") { + if (marker == fence && run >= fence_len && substr(text, run + 1) ~ /^[[:space:]]*$/) fence = "" + print; next + } + if (run >= 3 && (marker != "`" || index(substr(text, run + 1), "`") == 0)) { + fence = marker; fence_len = run; print; next + } + if (in_record && /^## /) { append_prose(); in_record = 0 } + if ($0 == "## Todo Record") in_record = 1 + print + } + END { if (in_record && !inserted) append_prose() } + ' "$plan" > "$plan_tmp" || ! mv "$plan_tmp" "$plan"; then + rm -f "$plan_tmp" "$todo.tmp" "$prose_tmp" + rollback "$moved" "$todo_bak" "$plan_bak" + echo "archive FAILED: Todo Record update" + exit 1 + fi fi - cat "$prose_tmp" >> "$plan" fi rm -f "$prose_tmp" mv "$todo.tmp" "$todo" @@ -280,8 +312,8 @@ mv "$todo.tmp" "$todo" fail=0 [ ! -d "$docs/$task" ] || { echo "FAIL: active path still present"; fail=1; } [ -d "$docs/achieved/$task" ] || { echo "FAIL: achieved path missing"; fail=1; } -grep -q '> Status: completed' "$docs/achieved/$task/prd.md" || { echo "FAIL: achieved prd not completed"; fail=1; } -grep -q '> Status: completed' "$docs/achieved/$task/plan.md" || { echo "FAIL: achieved plan not completed"; fail=1; } +[ "$(bash "$HERE/markdown-field" Status "$docs/achieved/$task/prd.md")" = completed ] || { echo "FAIL: achieved prd not completed"; fail=1; } +[ "$(bash "$HERE/markdown-field" Status "$docs/achieved/$task/plan.md")" = completed ] || { echo "FAIL: achieved plan not completed"; fail=1; } grep -q "achieved/$task/\`" "$todo" || { echo "FAIL: Todo Task: path not updated"; fail=1; } grep -q "^- Next action: None — completed and archived\.$" "$todo" || { echo "FAIL: Todo next action not cleared"; fail=1; } # The entry's body must now be exactly the five fields, and the moved prose must diff --git a/hooks/completion-gate b/hooks/completion-gate index eeae548..b23adc1 100644 --- a/hooks/completion-gate +++ b/hooks/completion-gate @@ -68,6 +68,12 @@ bash "$HERE/approval-check" "$plan" || exit 1 # towards — so the answer is already given above. if [ "$approval_only" -eq 1 ]; then exit 0; fi +# Supporting documents cannot carry an unterminated example into completion. +for doc in prd.md spec.md; do + [ -f "$1/$doc" ] || continue + bash "$HERE/markdown-field" Check "$1/$doc" >/dev/null || { echo "invalid Markdown fence in $doc" >&2; exit 1; } +done + # One pass, one process, one read. The conditions are checked in the order the # Agent would hit them and the first failure wins, so a Plan with two problems # reports the earlier one rather than whichever the reader happened to notice. @@ -118,6 +124,7 @@ result="$(awk -v approval_only="$approval_only" ' next } } + /^## (Skills \/ Tools Used|Plan Review|Verification \/ Review|Change Log|Steps)$/ { if (++sections[$0] > 1) duplicate_section = 1 } /^## / { flush() } /^### Step / { flush() @@ -158,7 +165,8 @@ result="$(awk -v approval_only="$approval_only" ' # Checked before `unchecked` and `unfinished`, because it is the one failure # whose remedy is different in kind: the others say "finish the work", this # says "the document states two things, delete one". - if (dup_step != "") { print "Plan has more than one - Status: line in Step " dup_step; bad = 1 } + if (duplicate_section) { print "Plan has duplicate reserved sections"; bad = 1 } + else if (dup_step != "") { print "Plan has more than one - Status: line in Step " dup_step; bad = 1 } else if (unchecked) { print "Plan has unchecked items"; bad = 1 } else if (unfinished) { print "Plan has unfinished Steps"; bad = 1 } exit bad diff --git a/hooks/markdown-field b/hooks/markdown-field new file mode 100644 index 0000000..1abace5 --- /dev/null +++ b/hooks/markdown-field @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +# Read exactly one document metadata field outside fenced Markdown examples. +set -euo pipefail +[ "$#" -eq 2 ] || { echo 'usage: markdown-field ' >&2; exit 1; } +case "$1" in 'Task version'|Status|'Todo Record'|Check) ;; *) echo 'unsupported metadata field' >&2; exit 1 ;; esac +awk -v field="$1" ' + { + text = $0; sub(/\r$/, "", text) + for (indent = 0; indent < 3 && substr(text, 1, 1) == " "; indent++) text = substr(text, 2) + marker = substr(text, 1, 1); run = 0 + if (marker == "`" || marker == "~") while (substr(text, run + 1, 1) == marker) run++ + if (fence != "") { + if (marker == fence && run >= fence_len && substr(text, run + 1) ~ /^[[:space:]]*$/) fence = "" + next + } + if (run >= 3 && (marker != "`" || index(substr(text, run + 1), "`") == 0)) { + fence = marker; fence_len = run; next + } + if (field == "Check") next + if (field == "Todo Record") { if ($0 == "## Todo Record") count++; next } + prefix = "> " field ": " + if (index($0, prefix) == 1) { count++; value = substr($0, length(prefix) + 1); sub(/\r$/, "", value) } + } + END { + if (fence != "") { print "unclosed Markdown fence" > "/dev/stderr"; exit 1 } + if (field == "Check") { print "ok"; exit 0 } + if (field == "Todo Record") { if (count > 1) { print "ambiguous Todo Record" > "/dev/stderr"; exit 1 } print count + 0; exit 0 } + if (count != 1 || value == "") { print "missing or ambiguous " field > "/dev/stderr"; exit 1 } + print value + } +' "$2" \ No newline at end of file diff --git a/hooks/smoke-test b/hooks/smoke-test index 96255b4..4af6475 100755 --- a/hooks/smoke-test +++ b/hooks/smoke-test @@ -98,6 +98,14 @@ cg_case duplicate-approval 1 'more than one Approval' '> Task version: v1 - Approved by: user - Approved version: v1 ' +cg_case duplicate-plan-review 1 'duplicate reserved sections' "${cg_approved}"'## Plan Review +- Verdict: sound +## Plan Review +- Verdict: needs revision +' +printf '# Spec\n```markdown\nunclosed\n' > "$cg/T/spec.md" +cg_case unclosed-spec 1 'invalid Markdown fence in spec.md' "$cg_approved" +rm -f "$cg/T/spec.md" cg_case unapproved 1 'not approved' '> Task version: v1 ## Approval - Status: requested @@ -297,6 +305,32 @@ awk ' real && $0 == "- Status: done" { real_ok = 1 } END { exit !(example_ok && real_ok) } ' "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" || { echo 'FAIL progress edited fenced example'; exit 1; } +# State transitions update live metadata and retain leading fenced examples. +cat > "$progress_fence/TaskFlowDocs/todo.md" <<'STATE_TODO' +## Example +- ID: TF-20260101-abcdef +- Status: promoted +- Task: `TaskFlowDocs/2026-01-01-example/` +- Updated: 2026-01-01 +STATE_TODO +cat > "$progress_fence/TaskFlowDocs/2026-01-01-example/prd.md" <<'STATE_PRD' +# PRD +> Task version: v1 +> Status: planning +STATE_PRD +cat > "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" <<'STATE_PLAN' +# Plan +```markdown +> Status: example +``` +> Task version: v1 +> Status: planning +## Approval +- Status: requested +STATE_PLAN +bash "$HERE/task" state 2026-01-01-example ready --root "$progress_fence" >/dev/null +grep -qx '> Status: example' "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" || { echo 'FAIL state changed fenced example'; exit 1; } +grep -qx '> Status: ready' "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" || { echo 'FAIL state did not update live status'; exit 1; } # A promotion that never got a Plan is the case `task complete` can reach, # because `task_paths` only requires the directory. The gate says so in words # rather than letting awk report a missing file. @@ -1057,6 +1091,34 @@ check_refusal unchecked 'unchecked items' 's/^ - \[x\] done$/ - [ ] not done/' check_refusal unfinished 'unfinished Steps' 's/^- Status: done$/- Status: in_progress/' echo ok +# A completed status in an example cannot stand in for task completion. +gate_example="$(gate_root example-status)" +for example_doc in prd.md plan.md; do + example_path="$gate_example/TaskFlowDocs/2026-09-08-gate/$example_doc" + sed 's/^> Status: completed$/> Status: planning/' "$example_path" > "$example_path.tmp" && mv "$example_path.tmp" "$example_path" + printf '\n```markdown\n> Status: completed\n```\n' >> "$example_path" +done +if bash "$HERE/archive" 2026-09-08-gate "$gate_example" >/dev/null 2>&1; then + echo 'FAIL archive accepted fenced completion status'; exit 1 +fi +[ -d "$gate_example/TaskFlowDocs/2026-09-08-gate" ] || { echo 'FAIL archive moved unfinished task'; exit 1; } +# Existing Todo Record may be followed by an external tool section. +gate_sections="$(gate_root sections)" +printf '%s\n' '- Notes: preserved note' >> "$gate_sections/TaskFlowDocs/todo.md" +cat >> "$gate_sections/TaskFlowDocs/2026-09-08-gate/plan.md" <<'TOOL_SECTION' +## Todo Record +old note +## Tool Extra +tool details +TOOL_SECTION +bash "$HERE/archive" 2026-09-08-gate "$gate_sections" >/dev/null +awk ' + /^## Todo Record$/ { record = 1; next } + /^## Tool Extra$/ { record = 0; extra = 1; next } + record && /preserved note/ { note = 1 } + extra && $0 == "tool details" { details = 1 } + END { exit !(note && details) } +' "$gate_sections/TaskFlowDocs/achieved/2026-09-08-gate/plan.md" || { echo 'FAIL archive misplaced Todo Record or changed extra content'; exit 1; } echo "== archive names the worktree teardown only from a linked worktree ==" # The teardown cannot be acted on when it is printed — `complete` runs before the # push and the merge — so the instruction carries its own condition and the @@ -1545,6 +1607,7 @@ cp "$HERE/task" "$roll/task" cp "$HERE/task-id" "$roll/task-id" cp "$HERE/completion-gate" "$roll/completion-gate" cp "$HERE/approval-check" "$roll/approval-check" +cp "$HERE/markdown-field" "$roll/markdown-field" cp "$HERE/version-baseline" "$roll/version-baseline" printf '%s\n' '#!/bin/sh' 'echo "archive stub: forced failure"' 'exit 1' > "$roll/archive" chmod +x "$roll/archive" "$roll/task-id" "$roll/completion-gate" "$roll/approval-check" "$roll/task" @@ -1719,6 +1782,44 @@ printf '\nPRD baseline requirement stays\n' >> "$docs/2026-09-08-smoke/prd.md" printf '\nSPEC baseline constraint stays\n' >> "$docs/2026-09-08-smoke/spec.md" printf '\nPLAN baseline decision stays\n- [x] Previously completed step\n' >> "$docs/2026-09-08-smoke/plan.md" old_prd=$(digest "$docs/2026-09-08-smoke/prd.md") +# Version transitions change metadata, not illustrative fenced examples. +version_fence="$tmp/version-fence" +mkdir -p "$version_fence/TaskFlowDocs/2026-01-01-example" +printf '# Example\n> Task version: v1\n> Status: in_progress\n' > "$version_fence/TaskFlowDocs/2026-01-01-example/prd.md" +cat > "$version_fence/TaskFlowDocs/2026-01-01-example/plan.md" <<'VERSION_FENCE' +# Plan +> Task version: v1 +> Status: in_progress +## Approval +- Status: approved +- Approved by: user +- Approved version: v1 +## Example +```markdown +> Task version: v1 +> Status: example +## Approval +- Status: example +``` +VERSION_FENCE +bash "$HERE/version" 2026-01-01-example v2 "$version_fence" prd.md >/dev/null +awk ' + /^```markdown$/ { example = 1; next } + /^```$/ { example = 0 } + example && $0 == "> Task version: v1" { version_ok = 1 } + example && $0 == "> Status: example" { state_ok = 1 } + example && $0 == "- Status: example" { approval_ok = 1 } + END { exit !(version_ok && state_ok && approval_ok) } +' "$version_fence/TaskFlowDocs/2026-01-01-example/plan.md" || { echo 'FAIL version changed fenced example'; exit 1; } +# An ambiguous status must fail before the old version is archived. +version_duplicate="$tmp/version-duplicate" +mkdir -p "$version_duplicate/TaskFlowDocs/2026-01-01-example" +printf '# PRD\n> Task version: v1\n> Status: planning\n> Status: checking\n' > "$version_duplicate/TaskFlowDocs/2026-01-01-example/prd.md" +printf '# Plan\n> Task version: v1\n> Status: planning\n## Approval\n- Status: requested\n' > "$version_duplicate/TaskFlowDocs/2026-01-01-example/plan.md" +if bash "$HERE/version" 2026-01-01-example v2 "$version_duplicate" prd.md >/dev/null 2>&1; then + echo 'FAIL version accepted ambiguous status'; exit 1 +fi +[ ! -e "$version_duplicate/TaskFlowDocs/2026-01-01-example/old/v1" ] || { echo 'FAIL version archived before refusing status'; exit 1; } bash "$HERE/version" 2026-09-08-smoke v2 "$tmp" prd.md >/dev/null grep -qxF 'PRD baseline requirement stays' "$docs/2026-09-08-smoke/prd.md" || { echo "FAIL version dropped PRD content"; exit 1; } grep -qxF 'SPEC baseline constraint stays' "$docs/2026-09-08-smoke/spec.md" || { echo "FAIL version dropped Spec content"; exit 1; } @@ -2381,7 +2482,23 @@ set_skills_body "$ap_task/plan.md" \ "$ap_line_prd" \ '- [Plan] Unaided — no capability applied to this phase; considered: work breakdown' \ "$ap_line_test" +# Conflicting duplicate reserved sections cannot be ignored at approval. +cp "$ap_task/plan.md" "$ap/plan-before-duplicate.md" +printf '\n## Plan Review\n- Verdict: needs revision\n' >> "$ap_task/plan.md" +if bash "$HERE/task" approve 2026-09-09-approve-smoke --root "$ap" >/dev/null 2>&1; then + echo 'FAIL approve accepted duplicate Plan Review'; exit 1 +fi +cp "$ap/plan-before-duplicate.md" "$ap_task/plan.md" +cat >> "$ap_task/plan.md" <<'APPROVAL_EXAMPLE' +## Tool Example +```markdown +## Approval +- Status: example +- Approved by: example +``` +APPROVAL_EXAMPLE bash "$HERE/task" approve 2026-09-09-approve-smoke --root "$ap" > "$ap/approve.out" +grep -qx -- '- Status: example' "$ap_task/plan.md" || { echo "FAIL approve rewrote fenced example"; exit 1; } grep -q 'stages released by the gate: 1 invoked, 2 unaided' "$ap/approve.out" \ || { echo "FAIL approve did not report the released stages"; cat "$ap/approve.out"; exit 1; } approval_fields="$(awk ' diff --git a/hooks/task b/hooks/task index 4490f32..74bec00 100755 --- a/hooks/task +++ b/hooks/task @@ -423,7 +423,7 @@ function overlap( w) { } { n++; line[n] = $0 } END { - if (cmd == "step") { + if (cmd == "step" || cmd == "docstatus") { for (i = 1; i <= n; i++) { text = line[i]; sub(/\r$/, "", text) for (indent = 0; indent < 3 && substr(text, 1, 1) == " "; indent++) text = substr(text, 2) @@ -742,7 +742,7 @@ END { if (cmd == "docstatus") { for (i = 1; i <= n; i++) { - if (at(line[i], "> Status: ")) { line[i] = "> Status: " value; emit(); exit 0 } + if (!fenced[i] && at(line[i], "> Status: ")) { line[i] = "> Status: " value; emit(); exit 0 } } die("missing document Status") } @@ -1254,6 +1254,9 @@ case "$command" in if [ "$new_state" = "in_progress" ]; then require_approval "$task" fi + # Validate both documents before updating Todo or any remote state. + bash "$SCRIPT_DIR/markdown-field" Status "$plan" >/dev/null || fail "invalid plan.md status; state change not started" + bash "$SCRIPT_DIR/markdown-field" Status "$prd" >/dev/null || fail "invalid prd.md status; state change not started" todo="$root/TaskFlowDocs/todo.md" [ -f "$todo" ] || fail "todo.md missing; state change not started" case "$new_state" in @@ -1617,7 +1620,34 @@ case "$command" in need_task_id "$task" task_paths "$root" "$task" [ -f "$plan" ] || fail "missing plan.md; approval not written" - grep -q '^## Approval$' "$plan" || fail "missing Approval section; approval not written" + # Read Markdown structure outside fenced examples; the writer preserves them. + fence_rules=' + { + text = $0; sub(/\r$/, "", text) + for (indent = 0; indent < 3 && substr(text, 1, 1) == " "; indent++) text = substr(text, 2) + marker = substr(text, 1, 1); run = 0 + if (marker == "`" || marker == "~") while (substr(text, run + 1, 1) == marker) run++ + if (fence != "") { + if (marker == fence && run >= fence_len && substr(text, run + 1) ~ /^[[:space:]]*$/) fence = "" + if (keep) print; next + } + if (run >= 3 && (marker != "`" || index(substr(text, run + 1), "`") == 0)) { + fence = marker; fence_len = run; if (keep) print; next + } + } + ' + bash "$SCRIPT_DIR/approval-check" --stale-only "$plan" || exit 1 + awk "$fence_rules"' /^## Approval$/ { count++ } END { exit count != 1 }' "$plan" || fail "missing or ambiguous Approval section; approval not written" + [ ! -f "$prd" ] || awk "$fence_rules"' END { exit fence != "" }' "$prd" || fail "unclosed Markdown fence in prd.md; approval not written" + [ ! -f "$base/spec.md" ] || bash "$SCRIPT_DIR/markdown-field" Check "$base/spec.md" >/dev/null || fail "unclosed Markdown fence in spec.md; approval not written" + awk "$fence_rules"' + /^## (Skills \/ Tools Used|Plan Review|Verification \/ Review|Change Log|Steps)$/ { if (++seen[$0] > 1) bad = 1 } + END { exit bad } + ' "$plan" || fail "duplicate reserved Plan section; approval not written" + [ ! -f "$prd" ] || awk "$fence_rules"' + /^## (External Facts|Task Kind)$/ { if (++seen[$0] > 1) bad = 1 } + END { exit bad } + ' "$prd" || fail "duplicate reserved PRD section; approval not written" # Stage gate: reconcile each required stage against the record the pre-write # gate wrote, instead of trusting the Plan's prose. Shape alone could not # tell an invoked phase from an uninvoked one — `Unaided — …` is @@ -1689,7 +1719,7 @@ case "$command" in || fail "approve blocked: the capability store under $cap_git_dir is out of step, so no stage can be reconciled. released reaches seq $cap_consumed while evidence holds $cap_total line(s) — at least one release points at a record that is gone, and this command cannot tell a backed release from an unbacked one until they agree again. Repair it first: bash hooks/task recover — it keeps every release whose record still exists and discards the ones whose record is gone, after which each discarded stage has to be declared again. Removing $cap_git_dir/taskflow also works and discards every release, not only the unbacked ones." cap_size=small [ -f "$base/spec.md" ] && cap_size=large - cap_skills="$(awk ' + cap_skills="$(awk "$fence_rules"' /^## Skills \/ Tools Used$/ { p = 1; next } p && /^## / { exit } p { print } @@ -1717,7 +1747,7 @@ or - Depends on external facts: yes - Source: - What it settled: " - ext_body="$(awk ' + ext_body="$(awk "$fence_rules"' /^## External Facts$/ { p = 1; next } p && /^## / { exit } p { print } @@ -1853,7 +1883,7 @@ EXT_SOURCES # under `pipefail`, where a large enough Plan makes the producer take SIGPIPE # on the early exit and turns a successful match into a failed pipeline. # `completion-gate` carries the measurement. - pr_body="$(awk ' + pr_body="$(awk "$fence_rules"' /^## Plan Review$/ { p = 1; next } p && /^## / { exit } p { print } @@ -1947,7 +1977,7 @@ $pr_what" # this section existed has no `## Task Kind`, and refusing it would rewrite # history to fit an implementation. Same for any value other than `defect`: # only an explicit declaration opts a task into this check. - tk_body="$(awk ' + tk_body="$(awk "$fence_rules"' /^## Task Kind$/ { p = 1; next } p && /^## / { exit } p { print } @@ -1971,7 +2001,7 @@ $pr_what" A defect task's requirements come from finding out why the behaviour is wrong, so the phase that writes them has to have consulted something that does that — or record that nothing available does, with 'bash hooks/task unaided PRD --considered \"root cause investigation\"' and an [PRD] Unaided line carrying that class. What the capability then does is its own business; this check only asks whether one was named." fi - approved_version="$(sed -n 's/^> Task version: \(v[0-9][0-9]*\)$/\1/p' "$plan" | head -1)" + approved_version="$(bash "$SCRIPT_DIR/markdown-field" 'Task version' "$plan")" [ -n "$approved_version" ] || fail "missing Plan Task version; approval not written" cap_invoked=0 cap_unaided=0 @@ -2133,7 +2163,7 @@ STAGE_LINES # from the environment (not awk -v) so backslashes are not rewritten. if ! TASKFLOW_APPROVER="$approver" TASKFLOW_APPROVED_AT="$approved_at" \ TASKFLOW_APPROVED_VERSION="$approved_version" TASKFLOW_APPROVED_SCOPE="$approved_scope" \ - awk ' + awk -v keep=1 "$fence_rules"' BEGIN { t[1] = "- Status: approved" t[2] = "- Approved by: " ENVIRON["TASKFLOW_APPROVER"] @@ -2184,7 +2214,7 @@ STAGE_LINES # than the pipe buffer, so a 111 KB Plan with an unchecked item first in the # file was archived 15 times out of 15. See `completion-gate`. bash "$SCRIPT_DIR/completion-gate" "$base" || exit 1 - version="$(sed -n 's/^> Task version: //p' "$plan" | head -1)" + version="$(bash "$SCRIPT_DIR/markdown-field" 'Task version' "$plan")" bash "$SCRIPT_DIR/version-baseline" check "$root" "$task" "$version" || exit 1 [ -e "$docs/achieved/$task" ] && fail "achieved/$task already exists" todo="$docs/todo.md" @@ -2201,8 +2231,8 @@ STAGE_LINES # Marking completed is irreversible unless archive succeeds — so remember # the prior statuses and put them back when archive fails. Without this a # failed archive left prd/plan saying completed beside an active directory. - plan_prev="$(sed -n 's/^> Status: //p' "$plan" | head -1)" - prd_prev="$(sed -n 's/^> Status: //p' "$prd" | head -1)" + plan_prev="$(bash "$SCRIPT_DIR/markdown-field" Status "$plan")" + prd_prev="$(bash "$SCRIPT_DIR/markdown-field" Status "$prd")" [ -n "$plan_prev" ] || fail "plan.md has no > Status: line" [ -n "$prd_prev" ] || fail "prd.md has no > Status: line" run_awk_to "$plan" "$plan" TASKFLOW_CMD=docstatus TASKFLOW_VALUE=completed diff --git a/hooks/version b/hooks/version index 44f32c5..96f6cbe 100755 --- a/hooks/version +++ b/hooks/version @@ -14,7 +14,8 @@ docs="$root/TaskFlowDocs" plan="$docs/$task/plan.md" [ -f "$plan" ] || { echo "missing plan.md"; exit 1; } [ -f "$docs/$task/prd.md" ] || { echo "missing prd.md"; exit 1; } -oldv=$(awk -F': ' '/> Task version:/{print $2; exit}' "$plan") +HERE="$(cd "$(dirname "$0")" && pwd)" +oldv="$(bash "$HERE/markdown-field" 'Task version' "$plan")" [ -n "$oldv" ] || { echo "missing current Task version"; exit 1; } [[ "$oldv" =~ ^v([1-9][0-9]*)$ ]] || { echo "invalid current Task version: $oldv"; exit 1; } [ "$newv" = "v$((BASH_REMATCH[1] + 1))" ] || { echo "new version must follow $oldv"; exit 1; } @@ -31,7 +32,7 @@ done for f in prd.md spec.md plan.md; do fpath="$docs/$task/$f" [ -f "$fpath" ] || continue - grep -q "^> Task version: $oldv$" "$fpath" || { echo "mixed or missing Task version in $f"; exit 1; } + [ "$(bash "$HERE/markdown-field" 'Task version' "$fpath")" = "$oldv" ] || { echo "mixed or missing Task version in $f"; exit 1; } done # Only the section is required. Individual Approval fields are written below # even when absent — a plan that followed the old four-field skill snippet has @@ -39,6 +40,22 @@ done # reset from agreeing on shape. grep -q '^## Approval$' "$plan" || { echo "missing Approval section"; exit 1; } +# Preserve fenced examples while updating the document's actual metadata. +fence_guard=' + { + text = $0; sub(/\r$/, "", text) + for (indent = 0; indent < 3 && substr(text, 1, 1) == " "; indent++) text = substr(text, 2) + marker = substr(text, 1, 1); run = 0 + if (marker == "`" || marker == "~") while (substr(text, run + 1, 1) == marker) run++ + if (fence != "") { + if (marker == fence && run >= fence_len && substr(text, run + 1) ~ /^[[:space:]]*$/) fence = "" + if (keep) print; next + } + if (run >= 3 && (marker != "`" || index(substr(text, run + 1), "`") == 0)) { + fence = marker; fence_len = run; if (keep) print; next + } + } +' # The archive must hold the superseded *version*, not the working tree after the # new version's edits landed. When v2 was written before the bump was taken, the # copy below would carry v2's text and `old/vN/` would silently stop recording @@ -55,6 +72,17 @@ if git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then done fi +# Refuse ambiguous Markdown before creating archives or changing any document. +for f in prd.md spec.md plan.md; do + fpath="$docs/$task/$f"; [ -f "$fpath" ] || continue + awk "$fence_guard"' END { if (fence != "") exit 1 }' "$fpath" >/dev/null || { echo "unclosed Markdown fence in $f"; exit 1; } +done +HERE="$(cd "$(dirname "$0")" && pwd)" +for f in prd.md plan.md; do + bash "$HERE/markdown-field" Status "$docs/$task/$f" >/dev/null || { echo "invalid status in $f"; exit 1; } +done +bash "$HERE/approval-check" --stale-only "$plan" || exit 1 +awk "$fence_guard"' /^## Approval$/ { count++ } END { exit count != 1 }' "$plan" >/dev/null || { echo "missing or ambiguous Approval section"; exit 1; } archdir="$docs/$task/old/$oldv" [ ! -e "$archdir" ] || { echo "archive already exists: $archdir"; exit 1; } HERE="$(cd "$(dirname "$0")" && pwd)" @@ -90,18 +118,18 @@ for f in "${selected[@]}"; do cp "$docs/$task/$f" "$archdir/$f"; done for f in prd.md spec.md plan.md; do fpath="$docs/$task/$f" [ -f "$fpath" ] || continue - sed "s/^> Task version: .*/> Task version: $newv/" "$fpath" > "$fpath.tmp" + awk -v keep=1 -v newv="$newv" "$fence_guard"' /^> Task version: / { print "> Task version: " newv; next } { print }' "$fpath" > "$fpath.tmp" mv "$fpath.tmp" "$fpath" done for fpath in "$docs/$task/prd.md" "$plan"; do - sed 's/^> Status: .*/> Status: ready/' "$fpath" > "$fpath.tmp" + awk -v keep=1 "$fence_guard"' /^> Status: / { print "> Status: ready"; next } { print }' "$fpath" > "$fpath.tmp" mv "$fpath.tmp" "$fpath" done # Reset ## Approval to the same five-field block hooks/task promote writes. # Field lines are dropped and re-emitted once, in template order, so a missing # Status (or any other) is inserted rather than refused. Non-field lines in # the section are left alone. -awk ' +awk -v keep=1 "$fence_guard"' BEGIN { t[1] = "- Status: requested" t[2] = "- Approved by: pending" @@ -136,11 +164,11 @@ mv "$plan.tmp" "$plan" for f in "${selected[@]}"; do [ -f "$archdir/$f" ] || { echo "archive check failed: $f"; exit 1; }; done for f in prd.md spec.md plan.md; do fpath="$docs/$task/$f"; [ -f "$fpath" ] || continue - grep -q "^> Task version: $newv$" "$fpath" || { echo "root version check failed: $f"; exit 1; } + [ "$(bash "$HERE/markdown-field" 'Task version' "$fpath")" = "$newv" ] || { echo "root version check failed: $f"; exit 1; } done -grep -q '^> Status: ready$' "$docs/$task/prd.md" && grep -q '^> Status: ready$' "$plan" || { echo "ready-state check failed"; exit 1; } +[ "$(bash "$HERE/markdown-field" Status "$docs/$task/prd.md")" = ready ] && [ "$(bash "$HERE/markdown-field" Status "$plan")" = ready ] || { echo "ready-state check failed"; exit 1; } # Exact five-line block, in order — not a single-field grep under -A8. -approval_fields="$(awk ' +approval_fields="$(awk "$fence_guard"' /^## Approval$/ { p = 1; next } p && /^## / { exit } p && /^- Status:/ { print; next } diff --git a/skills/taskflow/SKILL.md b/skills/taskflow/SKILL.md index b75a449..7285fa2 100644 --- a/skills/taskflow/SKILL.md +++ b/skills/taskflow/SKILL.md @@ -49,6 +49,7 @@ Never create a second task fact source such as a root `SPEC.md`, `TaskFlowDocs/p Task documents are read by the user and parsed by hooks, so they carry two languages at once. Write the prose, and any section heading the boundary does not name, in the user's working language; keep the lines hooks match — the section and entry headings they match by name, the `## Approval` fields, `> Task version:`, `> Status:`, `- Status:` lines, Todo field names, and `- [ ]` / `- [x]` markers — in English exactly as the hooks expect. The rule binds the document, not its drafter: a capability invoked for a phase supplies a shape to fill, and prose folded in from it is written in the user's working language like any other. `references/artifacts.md` states the boundary as an explicit name list, and says why a heading outside it is free to be translated, why a scaffold arrives in English whether `hooks/task promote` or a capability's template wrote it, and why that exemption stops at the headings. Existing documents, including everything under `TaskFlowDocs/achieved/`, are not rewritten for language. +Required task-document content is a floor, not a length limit: retain relevant material from tools and add sections or examples when they help. Scale detail to complexity and risk, and review whether the document supports implementation and verification rather than counting headings or words. See `references/artifacts.md` for the machine-readable boundary and fenced-example rules. ## Triage and lifecycle After the request passes the applicability gate, first record or update its Todo item. Then inspect the repository, `TaskFlowDocs/repository-docs/index.md`, applicable project rules, active and achieved TaskFlowDocs tasks, tests, configuration, Git state, and uncommitted changes. Separate findings into confirmed facts, user decisions, technical unknowns, and explicit exclusions. diff --git a/skills/taskflow/references/artifacts.md b/skills/taskflow/references/artifacts.md index 6242b34..bbb0a69 100644 --- a/skills/taskflow/references/artifacts.md +++ b/skills/taskflow/references/artifacts.md @@ -37,6 +37,11 @@ Field *values* written by a hook are fixed English tokens (`approved`, `done`, ` This applies to documents created from now on. Existing documents are not rewritten for language, in particular not under `TaskFlowDocs/achieved/`, which is read-only history. +## Required content and extensions + +The outlines below are a minimum, not a maximum or a requirement to discard another capability's useful material. Add relevant sections, examples, tables and evidence to the current authoritative documents. Keep machine-read headings and fields unambiguous; fenced examples are illustrative, not live approvals or task steps. Do not use an unclosed fence or duplicate a reserved section. + +Choose detail by the task's complexity and risk. A small change can be brief when its goal and verification are clear. For a cross-layer change, retain enough information about responsibilities, contracts, edge cases, decisions and verification to let someone implement and review it without guessing. A short summary is not a substitute for the supporting detail a tool actually established. Review whether each requirement is actionable and each acceptance criterion has verifiable coverage; neither a word count nor a complete list of headings proves quality. ## Minimal layout ```text From ebe5a32eab9bcf1960231568e55ac95992826097 Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:39:57 +0800 Subject: [PATCH 4/9] fix: reject ambiguous approval and step records --- hooks/README.md | 1 + hooks/approval-check | 10 +++++--- hooks/completion-gate | 2 ++ hooks/smoke-test | 37 +++++++++++++++++++++++++++ hooks/task | 3 ++- skills/taskflow/references/runtime.md | 1 + 6 files changed, 49 insertions(+), 5 deletions(-) diff --git a/hooks/README.md b/hooks/README.md index 641984c..4c38a3b 100644 --- a/hooks/README.md +++ b/hooks/README.md @@ -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) diff --git a/hooks/approval-check b/hooks/approval-check index c017c65..dfe4174 100644 --- a/hooks/approval-check +++ b/hooks/approval-check @@ -110,12 +110,14 @@ result="$(awk -v stale_only="$stale_only" ' next } /^## Approval$/ { approvals++; 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) } + 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 (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 @@ -125,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 " 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; } diff --git a/hooks/completion-gate b/hooks/completion-gate index b23adc1..134f450 100644 --- a/hooks/completion-gate +++ b/hooks/completion-gate @@ -136,6 +136,7 @@ result="$(awk -v approval_only="$approval_only" ' # number there is nothing to name and nothing to report: the block is not # one `task progress` could have written to. stepnum = substr(rest, 1, RLENGTH) + if (++seen_step[stepnum] > 1) duplicate_step = 1 } } next @@ -166,6 +167,7 @@ result="$(awk -v approval_only="$approval_only" ' # whose remedy is different in kind: the others say "finish the work", this # says "the document states two things, delete one". if (duplicate_section) { print "Plan has duplicate reserved sections"; bad = 1 } + else if (duplicate_step) { print "Plan has duplicate Step numbers"; bad = 1 } else if (dup_step != "") { print "Plan has more than one - Status: line in Step " dup_step; bad = 1 } else if (unchecked) { print "Plan has unchecked items"; bad = 1 } else if (unfinished) { print "Plan has unfinished Steps"; bad = 1 } diff --git a/hooks/smoke-test b/hooks/smoke-test index 4af6475..590c9e7 100755 --- a/hooks/smoke-test +++ b/hooks/smoke-test @@ -106,6 +106,33 @@ cg_case duplicate-plan-review 1 'duplicate reserved sections' "${cg_approved}"'# printf '# Spec\n```markdown\nunclosed\n' > "$cg/T/spec.md" cg_case unclosed-spec 1 'invalid Markdown fence in spec.md' "$cg_approved" rm -f "$cg/T/spec.md" +cg_case duplicate-approval-field 1 'ambiguous Approval fields' '> Task version: v1 +## Approval +- Status: requested +- Status: approved +- Approved by: user +- Approved version: v1 +' +cg_case duplicate-step-number 1 'duplicate Step' "${cg_approved}"'## Steps +### Step 1 — a +- Status: done +### Step 1 — b +- Status: done +' +cg_case missing-approver 1 'not approved' "$(printf '> Task version: v1\n## Approval\n- Status: approved\n- Approved by: \n- Approved version: v1\n')" +cg_case tilde-fenced-example 0 '' "${cg_approved}"'## Example + ~~~~markdown +- [ ] example +``` +### Step 9 — example +- Status: pending +~~~~ +' +cg_case short-fence-closure 1 'unclosed Markdown fence' "${cg_approved}"'## Example +~~~~ +- [ ] example +~~~ +' cg_case unapproved 1 'not approved' '> Task version: v1 ## Approval - Status: requested @@ -305,6 +332,16 @@ awk ' real && $0 == "- Status: done" { real_ok = 1 } END { exit !(example_ok && real_ok) } ' "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" || { echo 'FAIL progress edited fenced example'; exit 1; } +# Duplicate real Step numbers fail before progress can rewrite either block. +cat >> "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" <<'DUPLICATE_STEP' +### Step 1 — duplicate +- Status: pending +DUPLICATE_STEP +cp "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" "$tmp/progress-before-duplicate.md" +if bash "$HERE/task" progress 2026-01-01-example 1 done --root "$progress_fence" >/dev/null 2>&1; then + echo 'FAIL progress accepted duplicate Step'; exit 1 +fi +cmp "$tmp/progress-before-duplicate.md" "$progress_fence/TaskFlowDocs/2026-01-01-example/plan.md" || { echo 'FAIL duplicate Step changed Plan'; exit 1; } # State transitions update live metadata and retain leading fenced examples. cat > "$progress_fence/TaskFlowDocs/todo.md" <<'STATE_TODO' ## Example diff --git a/hooks/task b/hooks/task index 74bec00..598cc9e 100755 --- a/hooks/task +++ b/hooks/task @@ -581,10 +581,11 @@ END { if (match(rest, /^[0-9]+/)) { num = substr(rest, 1, RLENGTH) following = substr(rest, RLENGTH + 1, 1) - if (num == step && following !~ /[A-Za-z0-9_]/) { a = i; break } + if (num == step && following !~ /[A-Za-z0-9_]/) { matches++; if (!a) a = i } } } } + if (matches > 1) die("duplicate Step " step) if (a == 0) die("Step " step " not found") for (i = a + 1; i <= n; i++) { if (!fenced[i] && (at(line[i], "### Step ") || at(line[i], "## "))) break diff --git a/skills/taskflow/references/runtime.md b/skills/taskflow/references/runtime.md index 50081f5..bf0f4fa 100644 --- a/skills/taskflow/references/runtime.md +++ b/skills/taskflow/references/runtime.md @@ -394,6 +394,7 @@ repo-root/ ├── task-id # the one rule for a legal task name ├── approval-check # the one rule for whether a Plan's version is approved ├── completion-gate # the one rule for 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/state/progress/unaided/complete ├── summarize-state # shared state-summary generator From a513240297b311cdc11038270b5c3ffc1b37dcc2 Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:43:10 +0800 Subject: [PATCH 5/9] docs: record task document extensibility validation --- .../plan.md | 130 ++++++++++++++++++ .../2026-11-16-flexible-task-documents/prd.md | 53 +++++++ .../spec.md | 40 ++++++ TaskFlowDocs/todo.md | 15 ++ 4 files changed, 238 insertions(+) create mode 100644 TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md create mode 100644 TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md create mode 100644 TaskFlowDocs/2026-11-16-flexible-task-documents/spec.md diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md new file mode 100644 index 0000000..55057a4 --- /dev/null +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md @@ -0,0 +1,130 @@ +# Plan — 放宽 TaskFlow 文档内容约束 +> Task version: v1 +> Status: checking + +## 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 + +- 2026-11-16 定向复现:围栏示例中的未勾选项曾阻止完成,示例审批曾被当作有效批准,重复审批章节曾被合并解读;修复后均按预期处理,真实未勾选项和未闭合围栏仍拒绝。 +- 2026-11-16 定向复现:步骤更新、任务状态和版本转换曾改写围栏示例;步骤、状态更新和版本正例均已通过定向复测。 +- 2026-11-16 定向复现:审批写入曾改写围栏中的示例审批块;修复后重放样例保留原文,真实审批仍写入。 +- Git 回退点:`cc40415`、`4b1352b`、`7fdd165`、`ebe5a32`。 +- 运行边界:首次完整测试因误判 Git Bash 的 `/tmp` 路径而中断,不计为通过;经 Windows 文件系统确认该目录实际映射到项目内 `reference/test-temp`。后续显式设置项目内临时目录和测试根目录。` 记录命令和结果。 +- 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` 的实际读写逻辑并新增元数据读取器;未通过篡改旧期望伪造通过。新例测试示例内容和真实未完成事项的不同结果。 +## Change Log + +- v1 工作修订:按已批准验收补充围栏示例和审批歧义的实际根因与回归,不改变任务范围。 + +- v1:建立初始规格与计划;按用户补充加入文档内容充分性与防止过度压缩的引导和验收(批准前修订)。 + +## Follow-ups + +- 完整 Bash smoke 在本机 Git Bash 符号链接限制下未通过;Linux / macOS 与真实宿主工具输出待后续环境验证。 +- 本次测试自建夹具已按用户授权清理;本地未提交的任务文档等待验收。 + +- 若解析范围或安全边界需要偏离批准规格,先更新版本并重新确认。 + +## Version History + +- v1 — planning。 diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md new file mode 100644 index 0000000..98821fc --- /dev/null +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md @@ -0,0 +1,53 @@ +# 放宽 TaskFlow 文档内容约束,允许工具补充内容 +> Task version: v1 +> Status: checking + +## 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 + +无;如调查发现安全边界无法同时满足上述验收,先提出方案并重新确认。 diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/spec.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/spec.md new file mode 100644 index 0000000..829006c --- /dev/null +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/spec.md @@ -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 的代码与测试调查后收敛;若需改变上述契约则先回到用户确认。 diff --git a/TaskFlowDocs/todo.md b/TaskFlowDocs/todo.md index f9015ee..815f97c 100644 --- a/TaskFlowDocs/todo.md +++ b/TaskFlowDocs/todo.md @@ -35,6 +35,21 @@ has an issue number or URL. +## 放宽 TaskFlow 文档内容约束,允许工具补充内容 + +- ID: TF-20261116-b893dc +- Status: in_progress +- Priority: normal +- Owner: Unknown +- Source: direct user request +- Kind: capability +- Added: 2026-11-16 +- Updated: 2026-11-16 +- Goal: 调整 TaskFlow 文档要求,使其仅规定必须包含的内容,允许被引用的工具和技能按需写入更多内容,避免不必要的内容限制。 +- Task: `TaskFlowDocs/2026-11-16-flexible-task-documents/` +- Next action: 请用户验收已验证的实现,并确认测试限制。 +- Notes: 与 TF-20261110-84d1a9 对流程和文档重复的审视相关,但本条聚焦 TaskFlow 对工具输出内容的约束;不预设修改现有条目。 + ## 支持使用远程仓库 Issues 作为用户的待办列表 - ID: TF-20261116-7e2c41 From 18bb3d3895ff940515d89d2ac6673d734c7383b2 Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Tue, 17 Nov 2026 09:29:57 +0800 Subject: [PATCH 6/9] docs: repair task verification record --- .../2026-11-16-flexible-task-documents/plan.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md index 55057a4..2fab6cd 100644 --- a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md @@ -81,13 +81,7 @@ - [x] 测试真实审批、状态、版本与归档路径及补充内容保留。 - [x] 运行适用的 smoke、Windows 测试与 diff 检查并审阅变更。 - Acceptance: 六项验收各有证据,使用简单与复杂任务样例审查内容充分性,限制与未覆盖情况明确。 -- Verification: 在 `## Verification / Review - -- 2026-11-16 定向复现:围栏示例中的未勾选项曾阻止完成,示例审批曾被当作有效批准,重复审批章节曾被合并解读;修复后均按预期处理,真实未勾选项和未闭合围栏仍拒绝。 -- 2026-11-16 定向复现:步骤更新、任务状态和版本转换曾改写围栏示例;步骤、状态更新和版本正例均已通过定向复测。 -- 2026-11-16 定向复现:审批写入曾改写围栏中的示例审批块;修复后重放样例保留原文,真实审批仍写入。 -- Git 回退点:`cc40415`、`4b1352b`、`7fdd165`、`ebe5a32`。 -- 运行边界:首次完整测试因误判 Git Bash 的 `/tmp` 路径而中断,不计为通过;经 Windows 文件系统确认该目录实际映射到项目内 `reference/test-temp`。后续显式设置项目内临时目录和测试根目录。` 记录命令和结果。 +- Verification: 在 Verification / Review 章节记录命令和结果。 - Rollback: 回退本版本提交,不删除用户内容。 - Status: done @@ -103,7 +97,7 @@ - Git 回退点:`cc40415`、`4b1352b`、`7fdd165`、`ebe5a32`。 - 运行边界:首次完整测试因误判 Git Bash 的 `/tmp` 路径而中断,不计为通过;经 Windows 文件系统确认该目录实际映射到项目内 `reference/test-temp`。后续显式设置项目内临时目录和测试根目录。 -- 规划调查:`hooks/completion-gate` 的全文件未勾选项匹配未排除围栏;`hooks/task` 按标题截取若干保留章节。尚未执行行为回归。 +- 规划调查:`hooks/completion-gate` 的全文件未勾选项匹配未排除围栏;`hooks/task` 按标题截取若干保留章节。后续已执行行为回归,结果见下。 - 验收 1、2:`hooks/smoke-test` 完成门及步骤/状态测试段通过;版本切换和归档定向样例确认补充章节、示例及已有 Todo Record 内容保留。 - 验收 3、4:重复审批章节、审批字段、步骤编号、计划审查;空批准人、未闭合围栏、真实未完成事项均拒绝;未闭合状态更新与未完成直接归档未改变原任务。归档正常对照通过。 @@ -112,6 +106,7 @@ - 完整 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 尚待 PR 创建后运行。 ## Change Log - v1 工作修订:按已批准验收补充围栏示例和审批歧义的实际根因与回归,不改变任务范围。 @@ -121,7 +116,7 @@ ## Follow-ups - 完整 Bash smoke 在本机 Git Bash 符号链接限制下未通过;Linux / macOS 与真实宿主工具输出待后续环境验证。 -- 本次测试自建夹具已按用户授权清理;本地未提交的任务文档等待验收。 +- 本次测试自建夹具已按用户授权清理;任务文档已提交,等待验收。 - 若解析范围或安全边界需要偏离批准规格,先更新版本并重新确认。 From 90c9feee2a50232c4b384cc74c5661482b6b1f4c Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:00:34 +0800 Subject: [PATCH 7/9] fix: restore portable lifecycle smoke tests --- .../2026-11-16-flexible-task-documents/plan.md | 10 ++++++---- TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md | 2 +- TaskFlowDocs/todo.md | 2 +- hooks/smoke-test | 7 ++++--- hooks/task | 4 ++-- 5 files changed, 14 insertions(+), 11 deletions(-) diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md index 2fab6cd..2630844 100644 --- a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md @@ -1,6 +1,6 @@ # Plan — 放宽 TaskFlow 文档内容约束 > Task version: v1 -> Status: checking +> Status: in_progress ## Spec Pointers @@ -70,7 +70,7 @@ - Acceptance: PRD 验收 1–4 的正反例通过,修改后内容保留。 - Verification: 针对性测试及相关平台测试;检查每项真实阻断仍生效。 - Rollback: 使用本任务版本的 Git 回退点恢复变更。 -- Status: done +- Status: in_progress ### Step 3 — 生命周期验证与审查 @@ -83,7 +83,7 @@ - Acceptance: 六项验收各有证据,使用简单与复杂任务样例审查内容充分性,限制与未覆盖情况明确。 - Verification: 在 Verification / Review 章节记录命令和结果。 - Rollback: 回退本版本提交,不删除用户内容。 -- Status: done +- Status: in_progress ## Checkpoints @@ -107,9 +107,11 @@ - `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 尚待 PR 创建后运行。 +- 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 实证。 ## Change Log -- v1 工作修订:按已批准验收补充围栏示例和审批歧义的实际根因与回归,不改变任务范围。 +- v1 工作修订:按已批准验收补充围栏示例和审批歧义的实际根因与回归;PR CI 暴露的本任务夹具及 Bash 3.2 问题已修复,等待复验;不改变任务范围。 - v1:建立初始规格与计划;按用户补充加入文档内容充分性与防止过度压缩的引导和验收(批准前修订)。 diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md index 98821fc..7ff6905 100644 --- a/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md @@ -1,6 +1,6 @@ # 放宽 TaskFlow 文档内容约束,允许工具补充内容 > Task version: v1 -> Status: checking +> Status: in_progress ## Goal diff --git a/TaskFlowDocs/todo.md b/TaskFlowDocs/todo.md index 815f97c..688a748 100644 --- a/TaskFlowDocs/todo.md +++ b/TaskFlowDocs/todo.md @@ -44,7 +44,7 @@ has an issue number or URL. - Source: direct user request - Kind: capability - Added: 2026-11-16 -- Updated: 2026-11-16 +- Updated: 2026-11-17 - Goal: 调整 TaskFlow 文档要求,使其仅规定必须包含的内容,允许被引用的工具和技能按需写入更多内容,避免不必要的内容限制。 - Task: `TaskFlowDocs/2026-11-16-flexible-task-documents/` - Next action: 请用户验收已验证的实现,并确认测试限制。 diff --git a/hooks/smoke-test b/hooks/smoke-test index 590c9e7..7640ca4 100755 --- a/hooks/smoke-test +++ b/hooks/smoke-test @@ -387,14 +387,15 @@ cg_big="$cg/B" mkdir -p "$cg_big" { printf '> Task version: v1\n## Approval\n- Status: approved\n- Approved by: user\n- Approved version: v1\n - [ ] UNCHECKED FIRST\n' i=0; while [ "$i" -lt 8000 ]; do printf -- '- filler %s\n' "$i"; i=$((i + 1)); done - printf -- '- Status: done\n'; } > "$cg_big/plan.md" + printf -- '- Note: filler complete\n'; } > "$cg_big/plan.md" [ "$(wc -c < "$cg_big/plan.md")" -gt 65536 ] || { echo "FAIL large-Plan fixture is not large"; exit 1; } -if bash "$HERE/completion-gate" "$cg_big" >/dev/null 2>&1; then +if bash "$HERE/completion-gate" "$cg_big" >"$cg_big/out" 2>&1; then echo "FAIL completion-gate accepted a >64KB Plan with an unchecked item"; exit 1 fi +grep -q 'unchecked items' "$cg_big/out" || { echo "FAIL large Plan refused for a reason other than its unchecked item"; cat "$cg_big/out"; exit 1; } { printf '> Task version: v1\n## Approval\n- Status: approved\n- Approved by: user\n- Approved version: v1\n- Notes: x\n' i=0; while [ "$i" -lt 4000 ]; do printf 'bulk %s\n' "$i"; i=$((i + 1)); done - printf -- '- Status: done\n'; } > "$cg_big/plan.md" + printf -- '- Note: filler complete\n'; } > "$cg_big/plan.md" i=0 while [ "$i" -lt 50 ]; do bash "$HERE/completion-gate" --approval-only "$cg_big" >/dev/null 2>&1 \ diff --git a/hooks/task b/hooks/task index 598cc9e..047a235 100755 --- a/hooks/task +++ b/hooks/task @@ -428,11 +428,11 @@ END { text = line[i]; sub(/\r$/, "", text) for (indent = 0; indent < 3 && substr(text, 1, 1) == " "; indent++) text = substr(text, 2) marker = substr(text, 1, 1); run = 0 - if (marker == "`" || marker == "~") while (substr(text, run + 1, 1) == marker) run++ + if (marker == sprintf("%c", 96) || marker == "~") while (substr(text, run + 1, 1) == marker) run++ if (fence != "") { fenced[i] = 1 if (marker == fence && run >= fence_len && substr(text, run + 1) ~ /^[[:space:]]*$/) fence = "" - } else if (run >= 3 && (marker != "`" || index(substr(text, run + 1), "`") == 0)) { + } else if (run >= 3 && (marker != sprintf("%c", 96) || index(substr(text, run + 1), sprintf("%c", 96)) == 0)) { fenced[i] = 1; fence = marker; fence_len = run } } From 76dca06eecb4cd76bd58736d22b41eb07d312262 Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:07:19 +0800 Subject: [PATCH 8/9] docs: record successful PR verification --- TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md | 9 +++++---- TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md index 2630844..75df08f 100644 --- a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md @@ -1,6 +1,6 @@ # Plan — 放宽 TaskFlow 文档内容约束 > Task version: v1 -> Status: in_progress +> Status: checking ## Spec Pointers @@ -70,7 +70,7 @@ - Acceptance: PRD 验收 1–4 的正反例通过,修改后内容保留。 - Verification: 针对性测试及相关平台测试;检查每项真实阻断仍生效。 - Rollback: 使用本任务版本的 Git 回退点恢复变更。 -- Status: in_progress +- Status: done ### Step 3 — 生命周期验证与审查 @@ -83,7 +83,7 @@ - Acceptance: 六项验收各有证据,使用简单与复杂任务样例审查内容充分性,限制与未覆盖情况明确。 - Verification: 在 Verification / Review 章节记录命令和结果。 - Rollback: 回退本版本提交,不删除用户内容。 -- Status: in_progress +- Status: done ## Checkpoints @@ -109,6 +109,7 @@ - PR 模板 `.github/pull_request_template.md`:Summary 说明补充内容与解析修复;TaskFlow traceability 记录任务、范围、目标仓库及 base;Verification 记录 CI、diff 和技能校验;Review boundaries 记录范围、隐私和剩余限制。CI 尚待 PR 创建后运行。 - 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 问题已修复,等待复验;不改变任务范围。 @@ -117,7 +118,7 @@ ## Follow-ups -- 完整 Bash smoke 在本机 Git Bash 符号链接限制下未通过;Linux / macOS 与真实宿主工具输出待后续环境验证。 +- 本机完整 Bash smoke 因 Git Bash 符号链接限制未通过;Linux 和 macOS 已由 CI 验证,真实宿主工具输出仍待验证。 - 本次测试自建夹具已按用户授权清理;任务文档已提交,等待验收。 - 若解析范围或安全边界需要偏离批准规格,先更新版本并重新确认。 diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md b/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md index 7ff6905..98821fc 100644 --- a/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md +++ b/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md @@ -1,6 +1,6 @@ # 放宽 TaskFlow 文档内容约束,允许工具补充内容 > Task version: v1 -> Status: in_progress +> Status: checking ## Goal From 0eb870aae4ba19a128f112eed659b6c5df245315 Mon Sep 17 00:00:00 2001 From: hkwuks <25031515+hkwuks@users.noreply.github.com> Date: Tue, 17 Nov 2026 10:29:00 +0800 Subject: [PATCH 9/9] docs: archive accepted document extensibility task --- .../2026-11-16-flexible-task-documents/plan.md | 18 +++++++++++++----- .../2026-11-16-flexible-task-documents/prd.md | 2 +- .../2026-11-16-flexible-task-documents/spec.md | 0 TaskFlowDocs/todo.md | 13 +++---------- 4 files changed, 17 insertions(+), 16 deletions(-) rename TaskFlowDocs/{ => achieved}/2026-11-16-flexible-task-documents/plan.md (94%) rename TaskFlowDocs/{ => achieved}/2026-11-16-flexible-task-documents/prd.md (99%) rename TaskFlowDocs/{ => achieved}/2026-11-16-flexible-task-documents/spec.md (100%) diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md b/TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/plan.md similarity index 94% rename from TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md rename to TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/plan.md index 75df08f..31fc2a8 100644 --- a/TaskFlowDocs/2026-11-16-flexible-task-documents/plan.md +++ b/TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/plan.md @@ -1,6 +1,6 @@ # Plan — 放宽 TaskFlow 文档内容约束 > Task version: v1 -> Status: checking +> Status: completed ## Spec Pointers @@ -106,23 +106,31 @@ - 完整 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 尚待 PR 创建后运行。 +- 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 当前工作树完成门专项(含 >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 工作修订:按已批准验收补充围栏示例和审批歧义的实际根因与回归;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 对工具输出内容的约束;不预设修改现有条目。 diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md b/TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/prd.md similarity index 99% rename from TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md rename to TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/prd.md index 98821fc..610cb51 100644 --- a/TaskFlowDocs/2026-11-16-flexible-task-documents/prd.md +++ b/TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/prd.md @@ -1,6 +1,6 @@ # 放宽 TaskFlow 文档内容约束,允许工具补充内容 > Task version: v1 -> Status: checking +> Status: completed ## Goal diff --git a/TaskFlowDocs/2026-11-16-flexible-task-documents/spec.md b/TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/spec.md similarity index 100% rename from TaskFlowDocs/2026-11-16-flexible-task-documents/spec.md rename to TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/spec.md diff --git a/TaskFlowDocs/todo.md b/TaskFlowDocs/todo.md index 688a748..d673f5e 100644 --- a/TaskFlowDocs/todo.md +++ b/TaskFlowDocs/todo.md @@ -38,17 +38,10 @@ has an issue number or URL. ## 放宽 TaskFlow 文档内容约束,允许工具补充内容 - ID: TF-20261116-b893dc -- Status: in_progress -- Priority: normal -- Owner: Unknown -- Source: direct user request -- Kind: capability -- Added: 2026-11-16 -- Updated: 2026-11-17 +- Status: done - Goal: 调整 TaskFlow 文档要求,使其仅规定必须包含的内容,允许被引用的工具和技能按需写入更多内容,避免不必要的内容限制。 -- Task: `TaskFlowDocs/2026-11-16-flexible-task-documents/` -- Next action: 请用户验收已验证的实现,并确认测试限制。 -- Notes: 与 TF-20261110-84d1a9 对流程和文档重复的审视相关,但本条聚焦 TaskFlow 对工具输出内容的约束;不预设修改现有条目。 +- Task: `TaskFlowDocs/achieved/2026-11-16-flexible-task-documents/` +- Next action: None — completed and archived. ## 支持使用远程仓库 Issues 作为用户的待办列表