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

package/core/shared/guidance/rules/RULE_04_QUESTIONS.md

@@ -0,0 +1,46 @@
+# Question & Clarification Rules
+
+## When to Ask
+- Ask ONLY for genuine user-owned decisions unresolved by the request, the code, or sensible defaults
+- Enough to act → act; don't ask to confirm the obvious (see RULE_02 Scope Discipline)
+- One question that unblocks beats three that re-litigate settled choices
+
+<important if="asking the user a clarifying question or choosing between approaches">
+## How to Ask (MANDATORY format)
+Structured multiple-choice — never a free-form question buried in prose.
+- **A native question tool exists in this session** (Claude Code's `AskUserQuestion`, or any
+  harness tool that presents options and returns the user's choice): use it. Which harness this
+  is is not the test — what THIS session offers is; Codex and Gemini sessions increasingly
+  carry one.
+- **No native question tool** (truly non-interactive runs): write a `{stage}-questions.md` file
+  with `[Answer]:` tags — the fallback, never the preference.
+
+Each question:
+- 2–4 **meaningful, mutually-exclusive** options covering the real scenarios
+- NEVER invent filler; an "Other"/free-text escape is always the last choice
+- One topic per question; specific and unambiguous; lead with your recommended default
+</important>
+
+<important if="writing a question file because this session has no native question tool">
+## Question-File Format
+```markdown
+## Question 1 — [the question]
+A) [option]  B) [option]  X) Other (free text after the tag)
+
+[Answer]:
+```
+Naming: `{stage}-questions.md` (e.g. `spec-questions.md`) in the directory the stage writes
+its output to — not a fixed path outside the repo's layout.
+
+Lifecycle: write the file → tell the user and wait for "done" → read answers →
+**Validate Before Proceeding** (below) → act. A missing `[Answer]:`, or one that is not a listed
+letter, means ask again — never guess, and never reinterpret free text as a letter choice.
+</important>
+
+<important if="reading the user's answers before you act on them">
+## Validate Before Proceeding
+- Scan answers for contradictions (scope vs risk, quick fix vs multi-subsystem) and ambiguity
+- Conflict found → name it and ask one targeted follow-up in `{stage}-clarification-questions.md`,
+  same format, citing the conflicting answer; never proceed on an unresolved contradiction, and
+  never assume an answer to an ambiguous response
+</important>

package/core/shared/scripts/doflow/assets/mermaid-theme.json

@@ -0,0 +1,46 @@
+{
+  "theme": "base",
+  "themeVariables": {
+    "background": "#f5f5f5",
+    "primaryColor": "#ececec",
+    "primaryTextColor": "#2d3142",
+    "primaryBorderColor": "#2d3142",
+    "secondaryColor": "#f5f5f5",
+    "secondaryTextColor": "#4f5d75",
+    "secondaryBorderColor": "#4f5d75",
+    "tertiaryColor": "#f5f5f5",
+    "tertiaryTextColor": "#7a8399",
+    "tertiaryBorderColor": "#bfc0c0",
+    "mainBkg": "#ececec",
+    "nodeBorder": "#2d3142",
+    "nodeTextColor": "#2d3142",
+    "clusterBkg": "#f5f5f5",
+    "clusterBorder": "#bfc0c0",
+    "lineColor": "#4f5d75",
+    "textColor": "#2d3142",
+    "titleColor": "#2d3142",
+    "edgeLabelBackground": "#f5f5f5",
+    "actorBkg": "#ececec",
+    "actorBorder": "#2d3142",
+    "actorTextColor": "#2d3142",
+    "actorLineColor": "#bfc0c0",
+    "signalColor": "#4f5d75",
+    "signalTextColor": "#2d3142",
+    "labelBoxBkgColor": "#ececec",
+    "labelBoxBorderColor": "#eb6c36",
+    "labelTextColor": "#2d3142",
+    "loopTextColor": "#4f5d75",
+    "noteBkgColor": "#f5f5f5",
+    "noteBorderColor": "#eb6c36",
+    "noteTextColor": "#2d3142",
+    "activationBkgColor": "#ececec",
+    "activationBorderColor": "#4f5d75",
+    "sequenceNumberColor": "#f5f5f5",
+    "attributeBackgroundColorOdd": "#f5f5f5",
+    "attributeBackgroundColorEven": "#ececec",
+    "labelColor": "#2d3142",
+    "altBackground": "#ececec",
+    "fontFamily": "Geist, Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif",
+    "fontSize": "14px"
+  }
+}

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# do-exec-paths.sh — resolve the execution workspace and one task's artifact paths.
+#
+# The single source of truth for where a task's brief, report, and review packages
+# live, so do-task-brief.sh, do-review-package.sh and the dispatching skill cannot
+# drift to different directories. Artifacts sit inside the feature's own directory
+# (design §5.3) rather than a second workspace concept: the resolver already derives
+# that directory, and a third bookkeeping location would only invite confusion with
+# the install ledger.
+#
+# Delegates feature resolution to do-paths.sh — it never re-derives a branch, a slug,
+# or a feature number itself. Reads no plan content and touches no git state.
+#
+# Fail-open like the rest of this layer: on any resolution problem it still emits
+# JSON and exits 0, except the explicit no-feature and bad-input gates (exit 2).
+#
+# Usage:
+#   do-exec-paths.sh --task=<id> [--slug=<slug>] [--json]
+#   do-exec-paths.sh --group=<phase>:<owner> --tasks=<id,id,...> [--slug=<slug>] [--json]
+#
+# Emits for task mode: {feature_dir, workspace, brief, brief_record, report, task_id}
+# Emits for group mode: {feature_dir, workspace, group_id, group_brief, brief_record, reports[]}
+# `brief_record` is the *-brief.json beside the brief (the tier, tools and report-format record).
+
+set -uo pipefail
+
+task_id=""
+group_id=""
+tasks_csv=""
+slug_override=""
+mode=""
+for arg in "$@"; do
+  case "$arg" in
+    --task=*)
+      task_id="${arg#--task=}"
+      mode="task"
+      ;;
+    --group=*)
+      group_id="${arg#--group=}"
+      mode="group"
+      ;;
+    --tasks=*)
+      tasks_csv="${arg#--tasks=}"
+      ;;
+    --slug=*) slug_override="${arg#--slug=}" ;;
+    --json)   ;;
+    *) ;;
+  esac
+done
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '{"error":"jq-not-found","workspace":null}\n'
+  exit 0
+fi
+
+# Validate mode and required arguments
+if [ "$mode" = "group" ]; then
+  if [ -z "$group_id" ] || [ -z "$tasks_csv" ]; then
+    jq -n '{error:"missing-group-args", hint:"pass --group=<phase>:<owner> and --tasks=<id,id,...>"}'
+    exit 2
+  fi
+elif [ "$mode" = "task" ]; then
+  if [ -z "$task_id" ]; then
+    jq -n '{error:"missing-task", hint:"pass --task=<id>, e.g. --task=A.1"}'
+    exit 2
+  fi
+else
+  jq -n '{error:"missing-mode", hint:"pass either --task=<id> or --group=<phase>:<owner> and --tasks=<id,id,...>"}'
+  exit 2
+fi
+
+# A task id or group owner becomes part of a filename, so anything that could escape
+# the workspace or collide across directories is rejected rather than sanitized.
+# This applies to both modes: group_id contains phase:owner, and each task_id does too.
+validate_id() {
+  local id="$1"
+  case "$id" in
+    */*|*\\*|..*|*..|"") return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+if [ "$mode" = "task" ]; then
+  if ! validate_id "$task_id"; then
+    jq -n --arg id "$task_id" '{error:"invalid-task", task_id:$id, hint:"a task id is phase-dotted, e.g. A.1 — no path separators"}'
+    exit 2
+  fi
+fi
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+resolver="$script_dir/do-paths.sh"
+if [ ! -f "$resolver" ]; then
+  jq -n '{error:"resolver-not-found", hint:"do-paths.sh must sit beside this script"}'
+  exit 0
+fi
+
+resolved="$(bash "$resolver" --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')"
+feature_dir="$(printf '%s' "$resolved" | jq -r '.feature_dir // empty')"
+
+if [ -z "$feature_dir" ]; then
+  jq -n '{error:"no-active-feature", hint:"checkout a feat/<NNN-slug> branch, or pass --slug=<slug>"}'
+  exit 2
+fi
+
+workspace_rel="$feature_dir/exec"
+mkdir -p "$repo_root/$workspace_rel" 2>/dev/null
+
+if [ "$mode" = "task" ]; then
+  # Task mode: unchanged from original behavior
+  jq -n \
+    --arg feature_dir "$feature_dir" \
+    --arg workspace "$workspace_rel" \
+    --arg brief "$workspace_rel/task-$task_id-brief.md" \
+    --arg brief_record "$workspace_rel/task-$task_id-brief.json" \
+    --arg report "$workspace_rel/task-$task_id-report.md" \
+    --arg task_id "$task_id" \
+    '{feature_dir:$feature_dir, workspace:$workspace, brief:$brief, brief_record:$brief_record, report:$report, task_id:$task_id}'
+  exit 0
+fi
+
+# Group mode: process group_id and tasks_csv
+if ! validate_id "$group_id"; then
+  jq -n --arg id "$group_id" '{error:"invalid-group", group_id:$id, hint:"a group id must be phase-dotted with a safe owner name"}'
+  exit 2
+fi
+
+# Validate each task ID in the CSV
+IFS=',' read -ra task_ids <<< "$tasks_csv"
+for tid in "${task_ids[@]}"; do
+  # Trim whitespace
+  tid="${tid// /}"
+  if ! validate_id "$tid"; then
+    jq -n --arg id "$tid" '{error:"invalid-task", task_id:$id, hint:"a task id is phase-dotted, e.g. A.1 — no path separators"}'
+    exit 2
+  fi
+done
+
+# Build clean task ids
+clean_task_ids=()
+for tid in "${task_ids[@]}"; do
+  tid="${tid// /}"
+  [ -n "$tid" ] && clean_task_ids+=("$tid")
+done
+
+jq -n \
+  --arg feature_dir "$feature_dir" \
+  --arg workspace "$workspace_rel" \
+  --arg group_id "$group_id" \
+  --arg group_brief "$workspace_rel/group-${group_id//:/-}-brief.md" \
+  --arg brief_record "$workspace_rel/group-${group_id//:/-}-brief.json" \
+  '{
+    feature_dir: $feature_dir,
+    workspace: $workspace,
+    group_id: $group_id,
+    group_brief: $group_brief,
+    brief_record: $brief_record,
+    reports: [$ARGS.positional[] | $workspace + "/task-" + . + "-report.md"]
+  }' \
+  --args "${clean_task_ids[@]}"
+
+exit 0