@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/scripts/doflow/bash/do-parallel-check.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# do-parallel-check.sh — verify one phase's [P] siblings really write disjoint files.
+#                        Form dispatch groups by (phase, owner) and detect union overlaps.
+#
+# `[P]` asserts at plan time that a task's `files:` set does not overlap its phase
+# siblings'. Nothing verified that assertion, so parallel-by-default rested on an
+# unchecked claim: two agents dispatched concurrently onto one file is a lost edit,
+# and the loss is silent. This script turns the claim into a check.
+#
+# Grouping by (phase, owner) lets one agent handle all tasks of the same owner in a phase,
+# reducing dispatch overhead. The script forms groups from `owner:` fields, computes union
+# file sets per group, and reports overlaps across groups (`group_overlaps[]`).
+#
+# Advisory by design: it reports overlaps and grouping decisions; the calling skill decides
+# to serialize or group dispatch. It never edits the plan and never dispatches anything.
+#
+# A task whose `files:` value names no real path (a verification-only task) simply
+# contributes nothing to compare, rather than being treated as conflicting with
+# everything.
+#
+# Usage:
+#   do-parallel-check.sh --phase=<X> [--slug=<slug>] [--json]
+
+set -uo pipefail
+
+phase=""
+slug_override=""
+for arg in "$@"; do
+  case "$arg" in
+    --phase=*) phase="${arg#--phase=}" ;;
+    --slug=*)  slug_override="${arg#--slug=}" ;;
+    --json)    ;;
+    *) ;;
+  esac
+done
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '{"error":"jq-not-found","parallel_safe":null}\n'
+  exit 0
+fi
+
+if [ -z "$phase" ]; then
+  jq -n '{error:"missing-phase", hint:"pass --phase=<X>, e.g. --phase=A"}'
+  exit 2
+fi
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+resolved="$(bash "$script_dir/do-paths.sh" --json ${slug_override:+--slug="$slug_override"} 2>/dev/null)"
+resolved_rc=$?
+# An unsafe slug is refused with the resolver's own error object (IC-009), not read as an empty feature.
+if [ "$resolved_rc" -eq 2 ] && [ "$(printf '%s' "$resolved" | jq -r '.error // empty' 2>/dev/null)" = "invalid-slug" ]; then
+  printf '%s\n' "$resolved"; exit 2
+fi
+repo_root="$(printf '%s' "$resolved" | jq -r '.repo_root // empty')"
+plan_rel="$(printf '%s' "$resolved" | jq -r '.plan // empty')"
+has_plan="$(printf '%s' "$resolved" | jq -r '.has_plan // false')"
+
+if [ "$has_plan" != "true" ] || [ -z "$plan_rel" ]; then
+  jq -n '{error:"no-plan", hint:"this feature has no plan.md to check"}'
+  exit 2
+fi
+plan_abs="$repo_root/$plan_rel"
+
+# Pipeline: awk outputs tab-separated values (one per line), jq reads raw lines as strings,
+# aggregates them into an array, then processes each row.
+awk -v want="$phase" '
+  /^### Phase / {
+    inphase = ($3 == want)
+    next
+  }
+  /^### / { inphase = 0; next }
+  !inphase { next }
+  /^- \[[ x]\] / {
+    line = $0
+    if (match(line, /^- \[[ x]\] [^ ]+/) == 0) next
+    id = substr(line, RSTART + 6, RLENGTH - 6)
+    par = (line ~ /^- \[[ x]\] [^ ]+ \[P\]/) ? "P" : "S"
+    # Extract only the portion after em-dash for owner:/files: parsing
+    dash_pos = index(line, "—")
+    if (dash_pos == 0) {
+      print id "\t" par "\t\t"
+      next
+    }
+    field_section = substr(line, dash_pos + length("—"))
+    owner = ""
+    if (match(field_section, /owner:[^;]*/)) {
+      owner = substr(field_section, RSTART + 7, RLENGTH - 7)
+      gsub(/^[ \t]+|[ \t]+$/, "", owner)
+    }
+    if (match(field_section, /files:[^;]*/)) {
+      files = substr(field_section, RSTART + 6, RLENGTH - 6)
+      n = split(files, parts, ",")
+      emitted = 0
+      for (i = 1; i <= n; i++) {
+        f = parts[i]
+        gsub(/^[ \t]+|[ \t]+$/, "", f)
+        if (f == "" || f ~ /^none/) continue
+        print id "\t" par "\t" owner "\t" f
+        emitted = 1
+      }
+      if (!emitted) print id "\t" par "\t" owner "\t"
+    } else {
+      print id "\t" par "\t" owner "\t"
+    }
+  }
+' "$plan_abs" | jq -R . | jq -s --arg phase "$phase" '
+  # Convert array of tab-separated strings to array of objects
+  map(split("\t")) |
+  map({id: .[0], par: .[1], owner: (.[2] // ""), file: (.[3] // "")}) |
+  . as $rows |
+  
+  # Separate by parallel/sequential
+  ([.[] | select(.par == "P") | .id] | unique)   as $par |
+  ([.[] | select(.par == "S") | .id] | unique)   as $seq |
+  
+  # Existing overlaps: per-task file conflicts among [P] tasks
+  (
+    [.[] | select(.par == "P") | select(.file != "")] |
+    group_by(.file) |
+    map({path: .[0].file, tasks: ([.[] | .id] | unique)}) |
+    map(select(.tasks | length > 1))
+  ) as $overlaps |
+  
+  # Unowned tasks: those with empty owner
+  ([.[] | select(.owner == "") | .id] | unique)   as $unowned_ids |
+  
+  # Form groups preserving first task appearance order
+  (
+    reduce $rows[] as $row (
+      [];
+      if $row.id == "" then .
+      elif $row.owner == "" then
+        # Check if unowned task already added
+        if any(.[]; .id == ($phase + ":" + $row.id)) then
+          map(if .id == ($phase + ":" + $row.id) then
+            .files = (.files + (if $row.file == "" then [] else [$row.file] end) | unique)
+          else . end)
+        else
+          . + [{
+            id: ($phase + ":" + $row.id),
+            owner: null,
+            tasks: [$row.id],
+            files: (if $row.file == "" then [] else [$row.file] end)
+          }]
+        end
+      else
+        ($row.owner) as $own |
+        ($phase + ":" + $own) as $gid |
+        if any(.[]; .id == $gid) then
+          map(if .id == $gid then
+            .tasks = (if (.tasks | index($row.id)) then .tasks else (.tasks + [$row.id]) end) |
+            .files = (.files + (if $row.file == "" then [] else [$row.file] end) | unique)
+          else . end)
+        else
+          . + [{
+            id: $gid,
+            owner: $own,
+            tasks: [$row.id],
+            files: (if $row.file == "" then [] else [$row.file] end)
+          }]
+        end
+      end
+    )
+  ) as $final_groups |
+
+  # Create a mapping from task_id to group_id for lookup
+  ([$final_groups[] | .tasks[] as $t | {key: $t, value: .id}] | from_entries) as $task_to_group |
+
+  # Group overlaps: paths appearing in tasks assigned to more than one group
+  (
+    $rows |
+    [.[] | select(.par != "") | select(.file != "")] |
+    group_by(.file) |
+    map({
+      path: .[0].file,
+      groups: ([.[] | .id as $tid | $task_to_group[$tid]] | unique)
+    }) |
+    map(select((.groups | length) > 1))
+  ) as $final_group_overlaps |
+  
+  # Serialize list = union of group ids from overlaps
+  ([$final_group_overlaps[].groups[]] | unique) as $group_serialize |
+  
+  {
+    phase: $phase,
+    parallel_tasks: $par,
+    sequential_tasks: $seq,
+    overlaps: $overlaps,
+    # `null` when the caller named a phase and nothing parsed, true only when BOTH the task-level
+    # and the group-level collision sets are empty.
+    #
+    # This field was `(($overlaps|length) == 0)`, which was wrong twice. A plan whose tasks are not
+    # under a `### Phase <X>` heading parses to zero tasks, so zero overlaps, so "safe" — the flag
+    # said a collision-free phase where it had read no phase at all. And `$overlaps` counts only
+    # `[P]`-to-`[P]` collisions, so a plan could report `parallel_safe: true` in the same object as
+    # a non-empty `group_overlaps` naming the very file two groups both write. `do-execute-plan`
+    # tells the reader to branch on this field and never on the exit code, so either shape
+    # authorises concurrent writes to one file.
+    parallel_safe: (if (($par | length) == 0 and ($seq | length) == 0) then null
+                    else (($overlaps | length) == 0 and ($final_group_overlaps | length) == 0) end),
+    serialize: ([$overlaps[] | .tasks[]] | unique),
+    groups: $final_groups,
+    group_overlaps: $final_group_overlaps,
+    group_serialize: $group_serialize,
+    unowned_tasks: $unowned_ids
+  }
+'
+exit 0

package/core/shared/scripts/doflow/bash/do-paths.sh

@@ -0,0 +1,347 @@
+#!/usr/bin/env bash
+# do-paths.sh — deterministic path/feature resolver for the doflow chain.
+#
+# Emits a single JSON object describing the ACTIVE feature so doflow skills
+# never compute paths, feature numbers, or existence themselves (the
+# deterministic/generative split — design §4). In a git repo, the active
+# feature is derived from the branch (branch-coupled, FR-6): `feat/<NNN-slug>`
+# → feature dir `agent-docs/doflow/<NNN-slug>/`. On a trunk branch
+# (master/main/develop) the slug is null and the caller must prompt for one.
+# Outside a git repo (e.g. doflow installed at a multi-service container root,
+# above the actual git sub-repos) there is no branch to key off at all, so
+# resolution falls back to scanning `agent-docs/doflow/` directly — see the
+# "feature slug" section below and `candidate_slugs` in the emitted JSON.
+#
+# Self-contained by design: it does NOT source hooks/lib.sh, because this
+# script and lib.sh sit at different relative depths depending on install
+# location (global vs project-scoped). It needs only `git` + `jq`.
+#
+# Fail-open: on any error it still emits best-effort JSON and exits 0, so a
+# skill is never hard-blocked by path resolution. The one non-zero exit is the
+# explicit `--require feature` gate (exit 2 when no active feature).
+#
+# Usage:
+#   do-paths.sh [--json]            # default — full resolver JSON
+#   do-paths.sh --paths-only        # skip the next_number scan (cheap)
+#   do-paths.sh --require feature   # exit 2 + error JSON if no active feature
+#   do-paths.sh --slug=<slug>       # force resolution to this slug, skipping branch/dir detection
+#                                    # (used by a skill after it has already disambiguated via
+#                                    # AskUserQuestion — see "non-git root" note below)
+
+set -uo pipefail   # deliberately NOT -e: we handle errors and still emit JSON
+
+mode="json"
+require=""
+slug_override=""
+prev=""
+for arg in "$@"; do
+  case "$arg" in
+    --json)         mode="json" ;;
+    --paths-only)   mode="paths-only" ;;
+    --require)      require="pending" ;;          # value follows in next arg
+    --require=*)    require="${arg#--require=}" ;;
+    --slug=*)       slug_override="${arg#--slug=}" ;;
+    feature)        [ "$prev" = "--require" ] && require="feature" ;;
+    *) ;;
+  esac
+  prev="$arg"
+done
+[ "$require" = "pending" ] && require="feature"
+
+# jq is mandatory to emit JSON; fail-open with a diagnostic object if absent.
+if ! command -v jq >/dev/null 2>&1; then
+  printf '{"error":"jq-not-found","feature_slug":null}\n'
+  exit 0
+fi
+
+# ── repo root & branch (degrade gracefully outside a git repo) ────────────────
+is_git_repo=false
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -n "$repo_root" ]; then
+  is_git_repo=true
+else
+  repo_root="$(pwd)"
+fi
+branch=""
+[ "$is_git_repo" = true ] && branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+
+specs_rel="agent-docs/doflow"
+specs_dir="$repo_root/$specs_rel"
+
+# ── numeric-prefixed feature dirs under agent-docs/doflow/ (shared by the non-git candidate-slug
+# fallback below and the next_number scan further down — one scan, not two; applies the same
+# numeric-prefix filter next_number always used, so a stray non-numeric dir — notes/, .archive/,
+# a manual-cleanup leftover — can never masquerade as a feature candidate) ────────────────────
+numbered_dirs=()
+if { [ "$is_git_repo" = false ] || [ "$mode" != "paths-only" ]; } && [ -d "$specs_dir" ]; then
+  for d in "$specs_dir"/*/; do
+    [ -d "$d" ] || continue
+    n="$(basename "$d")"
+    case "${n%%-*}" in ''|*[!0-9]*) continue ;; esac
+    numbered_dirs+=("$n")
+  done
+fi
+
+# ── feature slug: branch-derived in a git repo; directory-scan otherwise ──────
+# A non-git root (doflow installed above the actual git repos — e.g. a multi-service
+# container workspace) has no branch to key off at all, so branch parsing doesn't apply here —
+# fall back to scanning agent-docs/doflow/ directly (numbered_dirs above). Exactly one candidate
+# dir is unambiguous and gets auto-selected (no prompt needed — nothing to decide). Zero
+# candidates is genuinely "no active feature." Two or more is a real decision this deterministic
+# script cannot make on its own; it surfaces every candidate via `candidate_slugs` instead of
+# guessing, so the calling skill (do-execute-plan / do-flow, which has AskUserQuestion access)
+# can ask the user, then re-invoke with `--slug=<chosen>` to force resolution.
+feature_slug=""
+candidate_slugs_json="[]"
+# Initialized here, not only inside the git arm below: a non-git root never runs the branch
+# `case`, and the emit block reads this unconditionally under `set -u`. Leaving it unset made
+# the resolver die with "branch_class: unbound variable" at exactly the container-root layout
+# the directory-scan fallback exists to support.
+branch_class=""
+if [ "$is_git_repo" = true ]; then
+  case "$branch" in
+    "")                          feature_slug=""; branch_class="trunk" ;;
+    master|main|develop|HEAD)     feature_slug=""; branch_class="trunk" ;;
+    release/*)                    feature_slug=""; branch_class="release" ;;
+    hotfix/*)                     feature_slug=""; branch_class="hotfix" ;;
+    feat/*|feature/*)             feature_slug="${branch#*/}"; branch_class="feature" ;;
+    fix/*|bugfix/*)               feature_slug="${branch#*/}"; branch_class="fix" ;;
+    */*)                          feature_slug="${branch#*/}"; branch_class="other" ;;
+    *)                            feature_slug="$branch"; branch_class="other" ;;
+  esac
+  # Flatten any separator the strip above left behind. Two reasons this is not cosmetic:
+  # `feature_dir` is `agent-docs/doflow/<slug>`, and a slug with a `/` nests it a level deeper than
+  # every other feature — deep enough that the non-git directory scan above can never find it,
+  # since that scan globs one level and then drops names without a numeric prefix. And
+  # `assertSafeTaskId` in src/runtime/evidence-ledger.js rejects path separators outright, so
+  # `doflow evidence` and `doflow claim` throw for the whole session.
+  #
+  # The arm above used to read `*/)`, which matches only a name ending in `/` — something git
+  # refuses to create — so it never once fired, and every prefix outside the six named here fell
+  # to `*)` and kept it. `feat/`, `feature/`, `fix/` and `bugfix/` were unaffected because they
+  # have their own arms; `task/`, `chore/`, `refactor/` and the rest were not.
+  feature_slug="$(printf '%s' "$feature_slug" | tr '/' '-')"
+else
+  case "${#numbered_dirs[@]}" in
+    0) : ;;
+    1) feature_slug="${numbered_dirs[0]}" ;;
+    *) candidate_slugs_json="$(printf '%s\n' "${numbered_dirs[@]}" | jq -R . | jq -s .)" ;;
+  esac
+fi
+
+# An explicit --slug always wins (post-disambiguation re-resolution, or a deliberate override).
+if [ -n "$slug_override" ]; then
+  feature_slug="$slug_override"
+  candidate_slugs_json="[]"
+fi
+
+# The slug becomes a directory name under agent-docs/doflow/ and a key in per-task state, so it must
+# not be able to name a path or a flag (IC-009): letters, digits, dot, underscore and dash, a letter
+# or digit first, and no "..". Refused before any path is built, whether it came from --slug or was
+# derived from the branch. Exit 2 like the other refusals; the message is also in `hint`, which is
+# the field every caller of the other error objects already reads.
+if [ -n "$feature_slug" ]; then
+  slug_ok=true
+  # The ranges are ASCII whatever the caller's locale: under a UTF-8 collation [A-Za-z] can admit
+  # letters such as "é", which the rule exists to refuse.
+  (export LC_ALL=C; [[ "$feature_slug" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]] && [[ "$feature_slug" != *..* ]]) || slug_ok=false
+  if [ "$slug_ok" = false ]; then
+    rule='use letters, digits, dot, underscore or dash, start with a letter or digit, and no ".."'
+    # A slug the caller did not type is traced to where it came from, so a branch name is not blamed
+    # on a flag nobody passed.
+    if [ -z "$slug_override" ] && [ "$is_git_repo" = true ] && [ -n "$branch" ]; then
+      subject="branch '$branch' gives slug '$feature_slug', which is not a valid feature slug"
+    else
+      subject="slug \"$feature_slug\" is not a valid feature slug"
+    fi
+    jq -n --arg subject "$subject" --arg rule "$rule" \
+      '{error:"invalid-slug", message:($subject + ": " + $rule), hint:$rule}'
+    exit 2
+  fi
+fi
+
+feature_dir=""; requirement=""; design=""; specs=""; data_model=""; plan=""; state=""; audit=""
+decisions=""; decisions_register=""; has_decisions=false
+has_requirement=false; has_design=false; has_plan=false; has_specs=false; has_data_model=false
+layout="legacy"
+intention_next_round=""; design_next_round=""; plan_next_round=""
+if [ -n "$feature_slug" ]; then
+  feature_dir="$specs_rel/$feature_slug"
+  abs="$repo_root/$feature_dir"
+  state="$feature_dir/state.md"; audit="$feature_dir/audit.md"
+  decisions="$feature_dir/decisions.md"; decisions_register="$feature_dir/decisions/register.json"
+  [ -f "$abs/decisions/register.json" ] && has_decisions=true
+  # ── layout: computed ONCE from a single file's presence, then used to pick
+  # every path field below — never detected per-field (design.md R4). This is
+  # what makes a self-contradictory mix of old/new paths for the same feature
+  # dir unreachable by construction.
+  [ -f "$abs/intention/requirement.md" ] && layout="structured"
+  if [ "$layout" = "structured" ]; then
+    requirement="$feature_dir/intention/requirement.md"
+    design="$feature_dir/design/design.md"
+    specs="$feature_dir/design/specs.md"
+    data_model="$feature_dir/design/data-model.md"
+    plan="$feature_dir/plan.md"
+    [ -f "$abs/intention/requirement.md" ]  && has_requirement=true
+    [ -f "$abs/design/design.md" ]          && has_design=true
+    [ -f "$abs/design/specs.md" ]           && has_specs=true
+    [ -f "$abs/design/data-model.md" ]      && has_data_model=true
+    [ -f "$abs/plan.md" ]                   && has_plan=true
+  else
+    requirement="$feature_dir/requirement.md"; design="$feature_dir/design.md"
+    plan="$feature_dir/plan.md"
+    [ -f "$abs/requirement.md" ] && has_requirement=true
+    [ -f "$abs/design.md" ]      && has_design=true
+    [ -f "$abs/plan.md" ]        && has_plan=true
+  fi
+
+  # ── per-stage question-log round scan (structured layout only has files to find,
+  # but the scan itself is layout-agnostic — an empty/absent subdir just floors at 1).
+  # Skipped in --paths-only mode like the next_number scan below; the three variables
+  # stay "" (emitted as null, never a numeric 1) so "not computed in this cheap mode"
+  # can never be mistaken for "computed, no rounds yet" ──
+  if [ "$mode" != "paths-only" ]; then
+    max=0
+    if [ -d "$abs/intention" ]; then
+      for f in "$abs/intention"/brainstorm-*-question.md; do
+        [ -f "$f" ] || continue
+        num="$(basename "$f")"; num="${num#brainstorm-}"; num="${num%-question.md}"
+        case "$num" in ''|*[!0-9]*) continue ;; esac
+        num=$((10#$num)); [ "$num" -gt "$max" ] && max="$num"
+      done
+    fi
+    intention_next_round=$((max + 1))
+
+    max=0
+    if [ -d "$abs/design" ]; then
+      for f in "$abs/design"/design-*-question.md; do
+        [ -f "$f" ] || continue
+        num="$(basename "$f")"; num="${num#design-}"; num="${num%-question.md}"
+        case "$num" in ''|*[!0-9]*) continue ;; esac
+        num=$((10#$num)); [ "$num" -gt "$max" ] && max="$num"
+      done
+    fi
+    design_next_round=$((max + 1))
+
+    max=0
+    if [ -d "$abs" ]; then
+      for f in "$abs"/plan-*-question.md; do
+        [ -f "$f" ] || continue
+        num="$(basename "$f")"; num="${num#plan-}"; num="${num%-question.md}"
+        case "$num" in ''|*[!0-9]*) continue ;; esac
+        num=$((10#$num)); [ "$num" -gt "$max" ] && max="$num"
+      done
+    fi
+    plan_next_round=$((max + 1))
+  fi
+fi
+
+# ── next number: max(existing spec dirs, numbered branches) + 1 ───────────────
+# Base-10 forced (10#) so leading zeros never trigger octal parsing.
+next_number="001"
+if [ "$mode" != "paths-only" ]; then
+  max=0
+  if [ "${#numbered_dirs[@]}" -gt 0 ]; then
+    for n in "${numbered_dirs[@]}"; do
+      nn=$((10#${n%%-*})); [ "$nn" -gt "$max" ] && max="$nn"
+    done
+  fi
+  while IFS= read -r b; do
+    seg="${b##*/}"; num="${seg%%-*}"
+    case "$num" in ''|*[!0-9]*) continue ;; esac
+    num=$((10#$num)); [ "$num" -gt "$max" ] && max="$num"
+  done < <(git -C "$repo_root" branch --format='%(refname:short)' 2>/dev/null || true)
+  next_number="$(printf '%03d' "$((max + 1))")"
+fi
+
+# ── constitution paths (two-tier — design §6) ─────────────────────────────────
+constitution_local="agent-docs/constitution.md"   # tier-2, per-repo (may not exist)
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+constitution_base=""
+for c in \
+  "$script_dir/../../../guidance/references/CONSTITUTION_BASE.md" \
+  "$HOME/.doflow/guidance/references/CONSTITUTION_BASE.md"; do
+  if [ -f "$c" ]; then
+    constitution_base="$(cd "$(dirname "$c")" && pwd)/CONSTITUTION_BASE.md"
+    break
+  fi
+done
+# Existence of tier-2 is repo-scoped, not feature-scoped, so it is computed here rather than in the
+# has_requirement/has_design/has_plan block above — a constitution is present or absent regardless
+# of whether any feature is active. It also stays outside the --paths-only skip, like the two paths
+# above, because callers using that cheap mode still need it.
+has_constitution_local=false
+[ -f "$repo_root/$constitution_local" ] && has_constitution_local=true
+
+# ── --require feature gate (the one non-zero exit) ────────────────────────────
+if [ "$require" = "feature" ] && [ -z "$feature_slug" ]; then
+  if [ "$candidate_slugs_json" != "[]" ]; then
+    jq -n --arg branch "$branch" --argjson candidate_slugs "$candidate_slugs_json" \
+      '{error:"ambiguous-feature",
+        branch:(if $branch=="" then null else $branch end),
+        candidate_slugs:$candidate_slugs,
+        hint:"multiple agent-docs/doflow/ feature dirs exist and no git branch disambiguates them — ask which one via AskUserQuestion, then re-run with --slug=<chosen>"}'
+  else
+    jq -n --arg branch "$branch" \
+      '{error:"no-active-feature",
+        branch:(if $branch=="" then null else $branch end),
+        hint:"checkout a feat/<NNN-slug> branch or run /do-brainstorm to start one"}'
+  fi
+  exit 2
+fi
+
+# ── emit resolver JSON ────────────────────────────────────────────────────────
+jq -n \
+  --arg repo_root "$repo_root" \
+  --argjson is_git_repo "$is_git_repo" \
+  --arg branch "$branch" \
+  --arg feature_slug "$feature_slug" \
+  --arg feature_dir "$feature_dir" \
+  --argjson candidate_slugs "$candidate_slugs_json" \
+  --arg requirement "$requirement" --arg design "$design" --arg specs "$specs" --arg data_model "$data_model" --arg plan "$plan" \
+  --arg state "$state" --arg audit "$audit" \
+  --arg decisions "$decisions" --arg decisions_register "$decisions_register" --argjson has_decisions "$has_decisions" \
+  --argjson has_requirement "$has_requirement" --argjson has_design "$has_design" --argjson has_plan "$has_plan" \
+  --argjson has_specs "$has_specs" --argjson has_data_model "$has_data_model" \
+  --arg layout "$layout" \
+  --arg intention_next_round "$intention_next_round" \
+  --arg design_next_round "$design_next_round" \
+  --arg plan_next_round "$plan_next_round" \
+  --arg next_number "$next_number" \
+  --arg constitution_base "$constitution_base" \
+  --arg constitution_local "$constitution_local" \
+  --argjson has_constitution_local "$has_constitution_local" \
+  --arg branch_class "$branch_class" \
+  '{
+    repo_root:          $repo_root,
+    is_git_repo:        $is_git_repo,
+    branch:             (if $branch=="" then null else $branch end),
+    feature_slug:       (if $feature_slug=="" then null else $feature_slug end),
+    feature_dir:        (if $feature_dir=="" then null else $feature_dir end),
+    candidate_slugs:    $candidate_slugs,
+    layout:             $layout,
+    requirement:        (if $requirement=="" then null else $requirement end),
+    design:             (if $design=="" then null else $design end),
+    specs:              (if $specs=="" then null else $specs end),
+    data_model:         (if $data_model=="" then null else $data_model end),
+    plan:               (if $plan=="" then null else $plan end),
+    state:              (if $state=="" then null else $state end),
+    audit:              (if $audit=="" then null else $audit end),
+    decisions:          (if $decisions=="" then null else $decisions end),
+    decisions_register: (if $decisions_register=="" then null else $decisions_register end),
+    has_decisions:      $has_decisions,
+    has_requirement:    $has_requirement,
+    has_design:         $has_design,
+    has_specs:          $has_specs,
+    has_data_model:     $has_data_model,
+    has_plan:           $has_plan,
+    intention_next_round: (if $intention_next_round=="" then null else ($intention_next_round|tonumber) end),
+    design_next_round:  (if $design_next_round=="" then null else ($design_next_round|tonumber) end),
+    plan_next_round:    (if $plan_next_round=="" then null else ($plan_next_round|tonumber) end),
+    next_number:        $next_number,
+    constitution_base:  (if $constitution_base=="" then null else $constitution_base end),
+    constitution_local: $constitution_local,
+    has_constitution_local: $has_constitution_local,
+    branch_class:       (if $branch_class=="" then null else $branch_class end)
+  }'
+exit 0

package/core/shared/scripts/doflow/bash/do-prereqs.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# do-prereqs.sh — doflow implement-phase prerequisite gate (prompt-level PRIMARY).
+#
+# Called as step 1 of /do-execute-plan. With --require-plan it exits 2 (and prints an
+# error JSON) when the active feature lacks requirement.md, design.md, or plan.md — the
+# "no implementing before you've planned" rule. Self-contained; fail-open for everything
+# EXCEPT the explicit gate failure (the one intentional non-zero exit).
+#
+# Usage: do-prereqs.sh --require-plan [--slug=<slug>]
+#   exit 0 = ok, exit 2 = missing requirement/design/plan (or ambiguous/no active feature)
+#   --slug=<slug> forwards to do-paths.sh — pass this after a caller has already disambiguated
+#   an "ambiguous-feature" result (non-git root, 2+ candidates) via AskUserQuestion.
+
+set -uo pipefail
+
+require_plan=false
+slug_override=""
+for a in "$@"; do
+  case "$a" in
+    --require-plan) require_plan=true ;;
+    --slug=*)       slug_override="${a#--slug=}" ;;
+  esac
+done
+
+command -v jq >/dev/null 2>&1 || { echo '{"ok":true,"note":"jq-absent-skip-gate"}'; exit 0; }
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+RESOLVER="$script_dir/do-paths.sh"
+[ -f "$RESOLVER" ] || RESOLVER="${DOFLOW_CONFIG_DIR:+$DOFLOW_CONFIG_DIR/scripts/doflow/bash/do-paths.sh}"
+[ -f "$RESOLVER" ] || { echo '{"ok":true,"note":"resolver-absent-skip-gate"}'; exit 0; }
+
+RESOLVER_ARGS=(--json)
+[ -n "$slug_override" ] && RESOLVER_ARGS+=("--slug=$slug_override")
+rc=0; json=$("$RESOLVER" "${RESOLVER_ARGS[@]}" 2>/dev/null) || rc=$?
+# A slug that could name a path is the caller's mistake, not an unrunnable resolver: the gate refuses
+# it with the resolver's own error rather than skipping itself (IC-009).
+if [ "$rc" -eq 2 ] && [ "$(printf '%s' "$json" | jq -r '.error // empty' 2>/dev/null)" = "invalid-slug" ]; then
+  printf '%s\n' "$json"; exit 2
+fi
+[ "$rc" -eq 0 ] || { echo '{"ok":true,"note":"resolver-error-skip-gate"}'; exit 0; }
+slug=$(echo "$json" | jq -r '.feature_slug // empty')
+candidate_slugs=$(echo "$json" | jq -c '.candidate_slugs // []')
+has_requirement=$(echo "$json" | jq -r '.has_requirement')
+has_design=$(echo "$json" | jq -r '.has_design')
+has_plan=$(echo "$json" | jq -r '.has_plan')
+
+if [ "$require_plan" = true ]; then
+  if [ -z "$slug" ]; then
+    if [ "$candidate_slugs" != "[]" ]; then
+      echo "$json" | jq '{ok:false, error:"ambiguous-feature", candidate_slugs:.candidate_slugs,
+                          hint:"multiple agent-docs/doflow/ feature dirs exist and no git branch disambiguates them — ask which one via AskUserQuestion, then re-run do-prereqs.sh --require-plan --slug=<chosen>"}'
+    else
+      echo "$json" | jq '{ok:false, error:"no-active-feature", hint:"run /do-brainstorm to start a feature"}'
+    fi
+    exit 2
+  fi
+  if [ "$has_requirement" != "true" ] || [ "$has_design" != "true" ] || [ "$has_plan" != "true" ]; then
+    echo "$json" | jq '{ok:false, error:"missing-prereqs", has_requirement:.has_requirement,
+                        has_design:.has_design, has_plan:.has_plan,
+                        hint:"run /do-design and /do-plan before /do-execute-plan"}'
+    exit 2
+  fi
+fi
+
+echo "$json" | jq '{ok:true, feature_slug:.feature_slug, has_requirement:.has_requirement, has_design:.has_design, has_plan:.has_plan}'
+exit 0