autonomous-sdlc-harness 0.2.0 → 0.4.0

package/templates/scripts/flows/task_plan_writing.graph.json

@@ -0,0 +1,192 @@
+{
+  "formatVersion": 1,
+  "flow": "task_plan_writing",
+  "description": "The routing of ${CLAUDE_PLUGIN_ROOT}/instructions/task_plan_writing_instructions_core.md as data: the task-plan loop, the UI-test-plan loop and convergence, with the values the walker resolves (counters, path templates, heartbeats, findings folders, skip gates, cap summaries). The dispatch blocks each agent receives are not here; they stay in that core. Copied verbatim into the adopter's scripts directory, never rendered.",
+  "start": "plan_writer",
+  "entries": ["plan_writer", "business_parity_review", "ui_writer", "ui_review", "convergence"],
+  "counters": {
+    "iteration": { "cap": 5 }
+  },
+  "paths": {
+    "story_index": "{state_dir}/story_plans/{branch}_story_plan.md",
+    "ui_test_index": "{state_dir}/ui_test_plans/{branch}_ui_test_plan.md"
+  },
+  "reports": ["business_parity_review", "architecture_review", "plan_review", "ui_test"],
+  "nodes": {
+    "plan_writer": {
+      "kind": "dispatch",
+      "agent": "task-plan-writer",
+      "heartbeat": "[plan-write · iter {iteration}] → task-plan-writer",
+      "prompts": ["initial", "revision"],
+      "outcomes": {
+        "returned": { "to": "business_parity_review" },
+        "questions": { "binding": "<ask>", "resume": "plan_writer" },
+        "error": { "binding": "<escalate>", "reason": "error" },
+        "blocker": { "binding": "<escalate>", "reason": "blocker" }
+      }
+    },
+    "business_parity_review": {
+      "kind": "dispatch",
+      "agent": "business-parity-reviewer",
+      "heartbeat": "[plan-write · parity · iter {iteration}] → business-parity-reviewer",
+      "findingsFolder": "{state_dir}/business_parity_reviews/{branch}/",
+      "skip": [
+        {
+          "construct": "passedByExclusion",
+          "runModeId": "parity",
+          "to": "architecture_review",
+          "report": { "business_parity_review": "passed-by-exclusion" }
+        },
+        {
+          "construct": "skipped",
+          "phase": "parity",
+          "to": "architecture_review",
+          "report": { "business_parity_review": "skipped" }
+        }
+      ],
+      "outcomes": {
+        "PASS": {
+          "to": "architecture_review",
+          "report": { "business_parity_review": "passed" }
+        },
+        "FAIL": {
+          "to": "plan_writer",
+          "increment": "iteration",
+          "prompt": "revision",
+          "onCap": {
+            "binding": "<escalate>",
+            "reason": "cap",
+            "summary": "the plan loop reached its {cap}-revision cap; the business-parity gate was open when it fired",
+            "roundCounts": ["business_parity_review", "architecture_review", "plan_review"],
+            "evidence": "story_index"
+          }
+        },
+        "error": { "binding": "<escalate>", "reason": "error" },
+        "blocker": { "binding": "<escalate>", "reason": "blocker" }
+      }
+    },
+    "architecture_review": {
+      "kind": "dispatch",
+      "agent": "architecture-reviewer",
+      "heartbeat": "[plan-write · arch · iter {iteration}] → architecture-reviewer",
+      "findingsFolder": "{state_dir}/architecture_reviews/{branch}/",
+      "skip": [
+        {
+          "construct": "passedByExclusion",
+          "runModeId": "architecture",
+          "to": "plan_review",
+          "report": { "architecture_review": "passed-by-exclusion" }
+        }
+      ],
+      "outcomes": {
+        "PASS": {
+          "to": "plan_review",
+          "report": { "architecture_review": "passed" }
+        },
+        "FAIL": {
+          "to": "plan_writer",
+          "increment": "iteration",
+          "prompt": "revision",
+          "onCap": {
+            "binding": "<escalate>",
+            "reason": "cap",
+            "summary": "the plan loop reached its {cap}-revision cap; the architecture gate was open when it fired",
+            "roundCounts": ["business_parity_review", "architecture_review", "plan_review"],
+            "evidence": "story_index"
+          }
+        },
+        "error": { "binding": "<escalate>", "reason": "error" },
+        "blocker": { "binding": "<escalate>", "reason": "blocker" }
+      }
+    },
+    "plan_review": {
+      "kind": "dispatch",
+      "agent": "task-plan-reviewer",
+      "heartbeat": "[plan-write · iter {iteration}] → task-plan-reviewer",
+      "findingsFolder": "{state_dir}/task_plan_reviews/{branch}/",
+      "outcomes": {
+        "PASS": {
+          "to": "ui_writer",
+          "reset": "iteration",
+          "ledger": "P1",
+          "report": { "plan_review": "passed" }
+        },
+        "FAIL": {
+          "to": "plan_writer",
+          "increment": "iteration",
+          "prompt": "revision",
+          "onCap": {
+            "binding": "<escalate>",
+            "reason": "cap",
+            "summary": "the plan loop reached its {cap}-revision cap; the plan-review gate was open when it fired",
+            "roundCounts": ["business_parity_review", "architecture_review", "plan_review"],
+            "evidence": "story_index"
+          }
+        },
+        "error": { "binding": "<escalate>", "reason": "error" },
+        "blocker": { "binding": "<escalate>", "reason": "blocker" }
+      }
+    },
+    "ui_writer": {
+      "kind": "dispatch",
+      "agent": "ui-tests-plan-writer",
+      "heartbeat": "[ui-test-write · iter {iteration}] → ui-tests-plan-writer",
+      "prompts": ["initial", "revision"],
+      "skip": [
+        {
+          "construct": "skipped",
+          "phase": "qa",
+          "to": "convergence",
+          "report": { "ui_test": "qa-phase-off" }
+        },
+        {
+          "construct": "passedByExclusion",
+          "runModeId": "qa",
+          "to": "convergence",
+          "report": { "ui_test": "run-mode-skipped" }
+        }
+      ],
+      "outcomes": {
+        "returned": { "to": "ui_review" },
+        "no_ui": {
+          "to": "convergence",
+          "ledger": "P2",
+          "report": { "ui_test": "no_ui" }
+        },
+        "questions": { "binding": "<ask>", "resume": "ui_writer" },
+        "error": { "binding": "<escalate>", "reason": "error" },
+        "blocker": { "binding": "<escalate>", "reason": "blocker" }
+      }
+    },
+    "ui_review": {
+      "kind": "dispatch",
+      "agent": "ui-tests-plan-reviewer",
+      "heartbeat": "[ui-test-write · iter {iteration}] → ui-tests-plan-reviewer",
+      "findingsFolder": "{state_dir}/ui_test_plan_reviews/{branch}/",
+      "outcomes": {
+        "PASS": {
+          "to": "convergence",
+          "ledger": "P2",
+          "report": { "ui_test": "passed" }
+        },
+        "FAIL": {
+          "to": "ui_writer",
+          "increment": "iteration",
+          "prompt": "revision",
+          "onCap": {
+            "binding": "<escalate>",
+            "reason": "cap",
+            "summary": "{cap} UI-test-plan-review iterations did not converge",
+            "evidence": "ui_test_index"
+          }
+        },
+        "error": { "binding": "<escalate>", "reason": "error" },
+        "blocker": { "binding": "<escalate>", "reason": "blocker" }
+      }
+    },
+    "convergence": {
+      "kind": "terminal",
+      "binding": "<terminal_handoff>"
+    }
+  }
+}

package/templates/scripts/lib/flow-walker-gates.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# flow-walker-gates.sh — the mechanical answers the flow walker needs at a
+# gate, each defined once: the next free `review_<n>` index in a findings
+# folder, that folder's round count, the run mode's skipped ids, whether a
+# `phases.*` flag is on, and the escalation evidence a story index or UI-test
+# index carries.
+#
+# IT ANSWERS AND NEVER DECIDES. Which node comes next, whether a counter hit
+# its cap and what the walker prints are the walker's. Nothing here writes
+# anything — not even the walker's state file — and the findings-folder
+# functions list names only and open no file.
+#
+# SOURCED, NEVER EXECUTED, AND IT SOURCES NOTHING. It sets no shell option, so
+# the sourcing script's shell is left exactly as found. `fw_phase_on` calls
+# `hr_phase_enabled`, so the caller sources `lib/harness-run-lib.sh` first.
+#
+# BASH 3.2 AND JQ 1.5 ARE THE FLOORS, as in `lib/harness-run-lib.sh`: no
+# associative array, no array-reading builtin, no `${x,,}` / `${x^^}`, no `local -n`.
+# Nothing here calls `jq` directly.
+#
+# NAMING AND STATUSES. Every function is prefixed `fw_` and touches no variable
+# outside a `local`. Statuses follow `lib/harness-run-lib.sh`: 0 yes / answered,
+# 1 no / not set, 2 unresolvable — and a caller that treats 2 as 1 acts on a
+# record it could not read.
+#
+# REPRO — reproduce any answer by hand, against a throwaway fixture:
+#
+#   root=$(mktemp -d); git -C "$root" init -q
+#   printf '{"defaultBranch":"main","stateDir":"sdlc-harness/","phases":{"qa":true}}' > "$root/harness.config.json"
+#   . <repo>/<scripts_dir>/lib/harness-run-lib.sh
+#   . <repo>/<scripts_dir>/lib/flow-walker-gates.sh
+#
+#   review index      mkdir "$root/f"; : > "$root/f/review_0.md"; : > "$root/f/review_3.md"
+#                     fw_next_review_index "$root/f"   -> 4   (a gap is never back-filled)
+#                     fw_round_count "$root/f"         -> 2
+#                     fw_next_review_index "$root/nope"; fw_round_count "$root/nope"  -> 0, 0
+#   run mode          fw_run_mode_skipped "$root" sdlc-harness/ feat_x none      -> none
+#                     fw_run_mode_skipped "$root" sdlc-harness/ feat_x ''; echo $?  -> 1, prints nothing
+#                     mkdir -p "$root/sdlc-harness/flow_progress"
+#                     printf '## Run mode\n- skipped: parity, qa\n' > "$root/sdlc-harness/flow_progress/feat_x_progress.md"
+#                     fw_run_mode_skipped "$root" sdlc-harness/ feat_x none      -> parity, qa   (the ledger wins)
+#                     fw_id_in_list qa 'parity, qa'; echo $?   -> 0
+#                     fw_id_in_list qa none; echo $?           -> 1
+#   phase flag        fw_phase_on "$root" qa; echo $?     -> 0
+#                     fw_phase_on "$root" docs; echo $?   -> 1
+#                     fw_phase_on "$root" bogus; echo $?  -> 2
+#   index evidence    printf '## Rejected findings\n- **3** (rejected round 1; rebutted round 2 — call stands) — r\n- **5** (rejected round 2) — r\n## Scope register\n' > "$root/i.md"
+#                     fw_index_evidence "$root/i.md"
+#                     -> evidence: <root>/i.md ## Rejected findings
+#                        evidence.open: - **5** (rejected round 2) — r
+#                        evidence: <root>/i.md ## Scope register
+#                     fw_index_evidence "$root/absent.md"  -> prints nothing
+
+# Print one past the highest <n> among entries named exactly `review_<n>.md`,
+# or 0 when the folder is absent or holds none. `ls`, not a glob, so a caller
+# running with pathname expansion off gets the same answer.
+fw_next_review_index() {
+  local folder="${1-}" name n max=-1
+  [ -d "$folder" ] || { printf '0\n'; return 0; }
+  ls -1 -- "$folder" 2>/dev/null | {
+    while IFS= read -r name; do
+      case "$name" in
+        review_*.md) ;;
+        *) continue ;;
+      esac
+      n="${name#review_}"
+      n="${n%.md}"
+      case "$n" in
+        ''|*[!0-9]*) continue ;;
+      esac
+      n=$((10#$n))
+      [ "$n" -gt "$max" ] && max="$n"
+    done
+    printf '%s\n' "$((max + 1))"
+  }
+  return 0
+}
+
+# Print how many entries start with `review_` — the core's
+# `ls <findings_folder> | grep -c '^review_'`, not the highest index.
+fw_round_count() {
+  local folder="${1-}" name count=0
+  [ -d "$folder" ] || { printf '0\n'; return 0; }
+  ls -1 -- "$folder" 2>/dev/null | {
+    while IFS= read -r name; do
+      case "$name" in
+        review_*) count=$((count + 1)) ;;
+      esac
+    done
+    printf '%s\n' "$count"
+  }
+  return 0
+}
+
+# Print the run mode's skipped ids (comma-separated, or `none`). A ledger at
+# `<state_dir>/flow_progress/<branch>_progress.md` is the record and its
+# `## Run mode` block's `- skipped: ` line wins over <flag_value>
+# (`run_mode_instructions.md` → `## The durable record`, **Tie-break**).
+# Returns 2 when the ledger exists but carries no such line; returns 1 when
+# there is no ledger and <flag_value> is empty — there is no default.
+fw_run_mode_skipped() {
+  local root="${1-}" state_dir="${2-}" branch="${3-}" flag="${4-}" ledger value
+  state_dir="${state_dir%/}"
+  ledger="$root/$state_dir/flow_progress/${branch}_progress.md"
+  if [ -f "$ledger" ]; then
+    value=$(awk '
+      /^## / { in_rm = ($0 ~ /^## Run mode[ \t\r]*$/); next }
+      in_rm && /^- skipped: / { v = substr($0, 12); sub(/[ \t\r]+$/, "", v); print v; exit }
+    ' "$ledger" 2>/dev/null)
+    [ -n "$value" ] || return 2
+    printf '%s\n' "$value"
+    return 0
+  fi
+  [ -n "$flag" ] || return 1
+  printf '%s\n' "$flag"
+  return 0
+}
+
+# Exit 0 when <id> is a member of <csv>, 1 otherwise. `none` is the empty set;
+# whitespace around each member is ignored.
+fw_id_in_list() {
+  local id="${1-}" rest="${2-}" item
+  [ -n "$id" ] || return 1
+  while [ -n "$rest" ]; do
+    item="${rest%%,*}"
+    case "$rest" in
+      *,*) rest="${rest#*,}" ;;
+      *) rest='' ;;
+    esac
+    item="${item#"${item%%[![:space:]]*}"}"
+    item="${item%"${item##*[![:space:]]}"}"
+    [ "$item" = none ] && continue
+    [ "$item" = "$id" ] && return 0
+  done
+  return 1
+}
+
+# Pass `hr_phase_enabled`'s 0 / 1 / 2 through unchanged.
+fw_phase_on() {
+  hr_phase_enabled "${1-}" "${2-}"
+}
+
+# Print the escalation evidence an index carries, or nothing when the file is
+# absent. `call stands` marks a rebutted entry (`task-plan-writer.md` →
+# `## Revision mode`); every other `- ` entry under `## Rejected findings` is
+# open. Which `## Scope register` rows are in dispute is judgement and stays
+# with the orchestrator — only the heading's presence is reported.
+fw_index_evidence() {
+  local index="${1-}"
+  [ -f "$index" ] || return 0
+  FW_INDEX="$index" awk '
+    /^## / {
+      h = $0; sub(/[ \t\r]+$/, "", h); in_rj = 0
+      if (h == "## Rejected findings") {
+        if (!rj) print "evidence: " ENVIRON["FW_INDEX"] " ## Rejected findings"
+        rj = 1; in_rj = 1
+      } else if (h == "## Scope register") {
+        sr = 1
+      }
+      next
+    }
+    in_rj && /^- / { if (index($0, "call stands") == 0) print "evidence.open: " $0 }
+    END { if (sr) print "evidence: " ENVIRON["FW_INDEX"] " ## Scope register" }
+  ' "$index"
+}