@manhquy/flow-skill 0.1.0 → 0.2.0

package/skills/flow/runner/flow.sh

@@ -136,9 +136,17 @@ stage_name_at() { # $1 = index -> "NN-name"
 current_stage_idx() { # highest CONTIGUOUS-from-00 stage index, or -1 if 00 missing
   # Contiguous (not just highest-existing) so a manually-dropped future stage file
   # cannot make 'next' report a false PLANNING COMPLETE while earlier stages are missing.
+  # A DEBT-SKIPPED stage satisfies contiguity without a file: cmd_skip deliberately
+  # scaffolds only the successor, so treating its absence as a gap would pin the index
+  # at the pre-skip stage forever (05 never scaffolded, planning_complete never true,
+  # '/flow card' deadlocked). Skips stay governed by cmd_skip alone - this only READS
+  # flow/.skipped, exactly like planning_complete does.
   local i=0 s idx=-1
   for s in $STAGES; do
-    if [ -f "$FLOW_DIR/$s.md" ]; then idx=$i; else break; fi
+    if [ -f "$FLOW_DIR/$s.md" ]; then idx=$i
+    elif stage_skipped "$s"; then :
+    else break
+    fi
     i=$((i + 1))
   done
   echo "$idx"
@@ -187,7 +195,11 @@ _python() {
 # harness_call_checked always returns the real harness exit (for callers that care).
 _harness_run() {
   # runs harness; prints stderr (masked lightly); echoes nothing; returns real rc
-  # usage: _harness_run <args...>   sets _HARNESS_LAST_RC
+  # usage: _harness_run [--emit-stdout] <args...>   sets _HARNESS_LAST_RC
+  # --emit-stdout: pass harness stdout THROUGH (value-carrying graph verbs) and
+  # suppress the warn line for the semantic rc 3 (no-next/paused, not a failure).
+  local _emit=0
+  [ "${1:-}" = "--emit-stdout" ] && { _emit=1; shift; }
   _HARNESS_LAST_RC=0
   [ -n "${FLOW_HARNESS_DISABLE:-}" ] && return 0
   [ -f "$HARNESS_PY" ] || return 0
@@ -198,6 +210,8 @@ _harness_run() {
   # capture rc without flipping the caller's set -e state
   out="$(FLOW_PROJECT_ROOT="$ROOT" "$py" "$HARNESS_PY" "$@" 2>"$errf")" || rc=$?
   _HARNESS_LAST_RC=$rc
+  [ "$_emit" = 1 ] && [ -n "$out" ] && printf '%s\n' "$out"
+  if [ "$_emit" = 1 ] && [ "$rc" -eq 3 ]; then rm -f "$errf" 2>/dev/null || true; return "$rc"; fi
   if [ "$rc" -ne 0 ]; then
     local errline summary
     errline="$(tr -d '\r' <"$errf" 2>/dev/null | head -n 3 | tr '\n' ' ')"
@@ -234,6 +248,33 @@ harness_call_checked() {
   _harness_run "$@"
 }
 
+# Wrap a command in a wall-clock bound when `timeout` exists (GNU coreutils / Git Bash);
+# a missing timeout degrades to running unbounded, exactly as before.
+_with_timeout() { # $1 = seconds, rest = command
+  local secs="$1"; shift
+  if command -v timeout >/dev/null 2>&1; then timeout "$secs" "$@"; else "$@"; fi
+}
+
+harness_capture_checked() {
+  # VALUE-carrying variant for graph verbs: emits harness stdout and returns the
+  # real exit code, via _harness_run --emit-stdout so the availability triad,
+  # stderr redaction, and rc plumbing live in ONE place. Fail-closed contract:
+  # 0=value, 3=no-next/paused, 4=harness unavailable (DISABLE / file / python
+  # missing - the soft rc-0 ambiguity _harness_run keeps for durable writes is
+  # exactly what value calls must NOT inherit), 1/2=failure.
+  # No consumers yet; cmd_next delegates through this when FLOW_GRAPH_EXECUTOR lands.
+  [ -n "${FLOW_HARNESS_DISABLE:-}" ] && return 4
+  [ -f "$HARNESS_PY" ] || return 4
+  local py; py="$(_python)"; [ -n "$py" ] || return 4
+  # 20s: generous for a contended BEGIN IMMEDIATE (busy_timeout is 5s) yet bounded.
+  # rc 124 = timed out -> treated as "harness unavailable" by callers, never a hang.
+  local rc=0
+  _with_timeout "${FLOW_HARNESS_TIMEOUT:-20}" env FLOW_PROJECT_ROOT="$ROOT" \
+    "$(_python)" "$HARNESS_PY" "$@" || rc=$?
+  [ "$rc" = "124" ] && { printf 'flow-harness: call timed out (%ss)\n' "${FLOW_HARNESS_TIMEOUT:-20}" >&2; return 4; }
+  return "$rc"
+}
+
 # When STRICT=fail, surface durable failure from card/check call sites (D5).
 _harness_or_fail() {
   harness_call "$@" || {
@@ -258,6 +299,65 @@ harness_emit() { # run a harness subcommand and ECHO its stdout (best-effort; no
   FLOW_PROJECT_ROOT="$ROOT" "$(_python)" "$HARNESS_PY" "$@" 2>/dev/null || true
 }
 
+# ---------- graph-executor recording contract (dark until FLOW_GRAPH_EXECUTOR=1) ----------
+# The auto-run loop is agent-driven prose (auto-run.md), so boundaries are recorded by
+# instrumenting verbs the agent ALREADY calls: workspace add -> card-dispatch,
+# check -> card-build/review evidence, card done -> card-verify-live, workspace remove ->
+# merge proof (executor-computed) + worktree telemetry ingest. Everything here is
+# best-effort: a recording failure must never break the mechanical engine.
+_graph_on() { [ "${FLOW_GRAPH_EXECUTOR:-}" = "1" ] && harness_available; }
+
+# Execution IDENTITY must live beside the DB, and the DB path is the harness's own
+# decision (worktree translation, monorepo sub-projects, --separate-git-dir). Re-deriving
+# it here with a shell heuristic drifted on exactly those shapes and re-split the journal,
+# so ASK the resolver instead of guessing: `graph root` prints dirname(default_db_path()).
+_graph_exec_id() { # [--no-create] -> echo the project's running auto_run execution id
+  # The whole selection is ONE atomic harness call: the DB row IS the pin, and SQLite's
+  # write transaction is the arbitration point. A bash pin file needed a claim dir,
+  # corpse recovery, TOCTOU-free reclaim AND a liveness check to approximate this - and
+  # each of those was a defect (stolen claims forked the journal; an existence-only
+  # check adopted abandoned executions and blackholed every later record).
+  _graph_on || return 1
+  local id
+  if [ "${1:-}" = "--no-create" ]; then
+    id="$(harness_capture_checked graph session --no-create 2>/dev/null | tr -d '\r\n')" || return 1
+  else
+    id="$(harness_capture_checked graph session 2>/dev/null | tr -d '\r\n')" || return 1
+  fi
+  [ -n "$id" ] || return 1
+  printf '%s' "$id"
+}
+
+_graph_planning_id() { # echo the planning execution id (kind=planning, ns='')
+  _graph_on || return 1
+  local id
+  id="$(harness_capture_checked graph session --kind planning 2>/dev/null | tr -d '\r\n')" || return 1
+  [ -n "$id" ] || return 1
+  printf '%s' "$id"
+}
+
+_graph_stage_record() { # $1 = stage just passed -> record the planning boundary (ns='')
+  _graph_on || return 0
+  local stage="$1" eid
+  eid="$(_graph_planning_id)" || return 0
+  local node="stage-${stage%%-*}"          # 03-prd -> stage-03 (topology node id)
+  harness_capture_checked graph record --execution "$eid" --ns "" --node "$node" \
+    --gate-exit 0 --gate-cmd "gate $stage" >/dev/null 2>&1 || true
+  return 0
+}
+
+_graph_record() { # $1=card-id (REQUIRED for card-scoped nodes) $2=node ; rest passed through
+  _graph_on || return 0
+  local card="$1" node="$2"; shift 2
+  # A card-scoped node with no card would land in the ROOT (stage) namespace and derail
+  # the planning walk - workspace add/remove are legitimately card-less for spikes.
+  [ -n "$card" ] || return 0
+  local eid; eid="$(_graph_exec_id)" || return 0
+  harness_capture_checked graph record --execution "$eid" --ns "card:$card" --node "$node" "$@" \
+    >/dev/null 2>&1 || true
+  return 0
+}
+
 cmd_harness() {
   # passthrough to the full durable-layer CLI (visible output + real exit code)
   if [ ! -f "$HARNESS_PY" ]; then echo "harness not installed at $HARNESS_PY"; return 1; fi
@@ -876,6 +976,10 @@ cmd_next() {
   if [ "$idx" -ge "$LAST_STAGE_IDX" ]; then
     FLOW_LOG_STAGE_FROM="$cur"
     if planning_complete; then
+      # Record ONLY when the plan actually advanced. stage-05 is the terminal planning
+      # node, so recording it while an earlier stage is still blocked would make
+      # `graph next` answer "complete" for a project flow.sh itself calls BLOCKED.
+      _graph_stage_record "$cur"
       echo "PASS: stage $cur gate clean. Planning is COMPLETE."
       echo "All planning stages passed (or were debt-skipped). Run '/flow card' to create build cards."
       if prd_declares_fr; then
@@ -889,14 +993,39 @@ cmd_next() {
     return 0
   fi
   local nxt; nxt="$(stage_name_at "$((idx + 1))")"
+  # Walk PAST every debt-skipped successor instead of stopping on one: cmd_skip already
+  # recorded the accepted exposure, so re-creating its file would resurrect a stage the
+  # DEBT line says is knowingly missing - but simply refusing to scaffold would wedge the
+  # project forever when the skipped stage's own successor is also absent (a failed
+  # scaffold in cmd_skip, or an operator deleting the file). Advance to the first stage
+  # that is neither present nor skipped; if that runs off the end, planning is complete.
+  local nidx=$((idx + 1)) skipped_over=""
+  while [ "$nidx" -le "$LAST_STAGE_IDX" ] && stage_skipped "$nxt"; do
+    skipped_over="$skipped_over $nxt"
+    nidx=$((nidx + 1))
+    [ "$nidx" -gt "$LAST_STAGE_IDX" ] && break
+    nxt="$(stage_name_at "$nidx")"
+  done
+  if [ "$nidx" -gt "$LAST_STAGE_IDX" ]; then
+    echo "PASS: stage $cur gate clean. Remaining stages are debt-skipped ($(printf '%s' "${skipped_over# }"))."
+    if planning_complete; then
+      _graph_stage_record "$cur"
+      echo "Planning is COMPLETE. Run '/flow card' to create build cards."
+    else
+      echo "An earlier stage is still BLOCKED (and not debt-skipped) - run '/flow' to see which."
+    fi
+    return 0
+  fi
   if [ -f "$FLOW_DIR/$nxt.md" ]; then
-    echo "PASS: stage $cur gate clean. Stage $((idx + 1)) ($nxt.md) already exists - not overwritten."
+    echo "PASS: stage $cur gate clean. Stage $nidx ($nxt.md) already exists - not overwritten."
+    _graph_stage_record "$cur"
     return 0
   fi
   cp "$TEMPLATE_DIR/$nxt.md" "$FLOW_DIR/$nxt.md"
   FLOW_LOG_STAGE_FROM="$cur"; FLOW_LOG_STAGE_TO="$nxt"
-  echo "PASS: stage $cur gate clean -> unlocked stage $((idx + 1)) (flow/$nxt.md)"
+  echo "PASS: stage $cur gate clean -> unlocked stage $nidx (flow/$nxt.md)"
   gate_durable_hook "$cur"
+  _graph_stage_record "$cur"
   echo "  tip: '/flow recall' surfaces prior debt/retro/friction before you fill this stage."
   return 0
 }
@@ -1045,6 +1174,10 @@ cmd_card_done() { # CLI-owned flip to done, gated by the SAME done-rules as '/fl
   if ! _set_card_status "$file" done; then echo "FAIL: could not write status for $id"; return 1; fi
   if cmd_check "$id"; then            # cmd_check enforces evidence/verify AND records the durable done-trace
     _inflight_clear "$id"
+    # card-verify-live: the done boundary is the EVIDENCE gate passing, not the merge
+    # (merge != shipped) - dependents unblock on card status, matching cmd_ready.
+    # The nested cmd_check already recorded card-review; this advances past it.
+    _graph_record "$id" card-verify-live --gate-exit 0 --card-status done
     return 0
   fi
   _set_card_status "$file" "${orig:-todo}"   # NOT done — never leave a hollow 'done'
@@ -1161,6 +1294,10 @@ cmd_check() {
 
   if [ "$found" -eq 0 ]; then
     echo "PASS: $id is valid (status: $st)."
+    # card-review boundary: the gate verdict IS the evidence the executor records
+    # (green here is what unblocks card-merge in the topology).
+    # Typed flags, never a bash-built JSON literal: $st is free text from the card file.
+    _graph_record "$id" card-review --gate-exit 0 --gate-cmd "check $id" --card-status "$st"
     case "$st" in
       todo) _harness_or_fail story update --id "$id" --status in_progress || return 1 ;;
       done)
@@ -1184,6 +1321,7 @@ cmd_check() {
   fi
   FLOW_LAST_GATE_FAIL="fill:$(grep -c '\[FILL' "$file" 2>/dev/null || echo 0),unchecked:$(grep -cE '^[[:space:]]*- \[ \]' "$file" 2>/dev/null || echo 0)"
   echo "FAIL: $id has gate violations (above)."
+  _graph_record "$id" card-review --gate-exit 1 --gate-cmd "check $id" --card-status "$st"
   return 1
 }
 
@@ -1262,6 +1400,34 @@ cmd_skip() {
   return 0
 }
 
+cmd_gate() {
+  # Read-only mechanical gate scan (no unlock, no template copy, no durable writes):
+  # the ONLY flow.sh verb the graph executor may run from topology cmd position
+  # (`check` mutates story/trace on pass and stays Must-ask). Exit 0 clean / 1 findings.
+  local target="${1:-}"
+  if [ "$target" = "--card" ]; then
+    local card="${2:-}" f
+    if [ -z "$card" ]; then echo "usage: /flow gate --card C-NNN"; return 2; fi
+    f="$(resolve_card_file "$card" 2>/dev/null)"
+    if [ -z "$f" ]; then echo "usage: /flow gate --card C-NNN"; return 2; fi
+    # A nonexistent card is NOT a gate verdict: reporting it as exit 1 would journal a
+    # typo'd id as a genuine red review and burn a two-strikes repair budget.
+    if [ ! -f "$f" ]; then echo "FAIL: card not found for '$card' (looked for $f)"; return 2; fi
+    echo "GATE card ${card}:"
+    if scan_gate "$f"; then echo "  clean"; return 0; fi
+    return 1
+  fi
+  local known=0 s
+  for s in $STAGES; do [ "$s" = "$target" ] && known=1; done
+  if [ "$known" -eq 0 ]; then
+    echo "usage: /flow gate <stage: $STAGES> | /flow gate --card C-NNN"
+    return 2
+  fi
+  echo "GATE stage ${target}:"
+  if scan_gate "$FLOW_DIR/$target.md"; then echo "  clean"; return 0; fi
+  return 1
+}
+
 cmd_retro() {
   [ -f "$RETRO_FILE" ] || { [ -f "$LAW_DIR/RETRO.md" ] && cp "$LAW_DIR/RETRO.md" "$RETRO_FILE"; }
   echo "flow retro - answer these 3, then append ONE honest line to RETRO.md:"
@@ -2010,6 +2176,10 @@ _ws_add() {
     done
   fi
   echo "PASS: created worktree for '$branch' (vendor ${vendor:-?}, port-offset $port) -> $wt"
+  # card-dispatch boundary. NOTE: no FLOW_PROJECT_ROOT export in the enter block — the DB
+  # resolver already maps a linked worktree to the main DB (_db.default_db_path), and
+  # exporting the project root would hijack CARDS_DIR/locks/DEBT for every call in there.
+  _graph_record "$card" card-dispatch --branch "$branch" --worktree "$wt" --vendor "$vendor"
   _ws_print_enter "$branch" "$wt" "$vendor" "$port"
   echo "  (tracked in .flow/workspaces.jsonl; see 'workspace list' / 'workspace doctor')"
   return 0
@@ -2092,6 +2262,20 @@ _ws_remove() {
         '/^worktree /{p=substr($0,10)} /^branch /{b=$2; sub(/^refs\/heads\//,"",b); if(b==want) print p}')"
   [ -n "$wt" ] || wt="$(_ws_get "$rec" worktree_path)"
   if [ -z "$wt" ]; then echo "workspace: no worktree found for branch '$branch'."; return 1; fi
+  # Telemetry ingest must happen BEFORE the tree is gone (the sink lives inside it); the
+  # merge boundary is recorded only AFTER a successful removal, so a refused (dirty-tree)
+  # remove never journals a merge for a card still under active work.
+  local _gcard _gcreated
+  _gcard="$(_ws_get "$rec" card_id)"; _gcreated="$(_ws_get_num "$rec" created_at)"
+  if _graph_on && [ -f "$wt/.flow/events.jsonl" ]; then
+    # Lifecycle-unique key: worktree paths are recycled, so a bare-path cursor would
+    # swallow the next lifecycle's lines. Prefix = destination sink (usage/prune group it).
+    # Path and tag stay in separate arguments so the path is still a path when it crosses
+    # into python — pre-joining them with '#' defeats Git-Bash path translation on Windows.
+    harness_capture_checked rollup --src "$wt/.flow/events.jsonl" \
+      --src-key-path "$LOG_DIR/events.jsonl" \
+      --src-key-tag "$branch#${_gcreated:-0}" >/dev/null 2>&1 || true
+  fi
   if [ "$force" -eq 1 ]; then
     rmout="$(git -C "$ROOT" worktree remove --force "$wt" 2>&1)"; rc=$?
   else
@@ -2102,6 +2286,9 @@ _ws_remove() {
     echo "FAIL: git worktree remove refused (commit/clean the tree, or re-run with --force)."
     return 1
   fi
+  # The executor computes the ancestry itself - this verb has no merge knowledge (it only
+  # removes a tree) - and records card-abandon when the branch was never merged.
+  _graph_record "$_gcard" card-merge --merge --branch "$branch"
   # tombstone ONLY on clean success (git is truth; a failed remove changed nothing)
   local vendor card port
   vendor="$(_ws_get "$rec" vendor)"; card="$(_ws_get "$rec" card_id)"; port="$(_ws_get_num "$rec" port_offset)"
@@ -2175,6 +2362,24 @@ _ws_doctor() {
   if [ -n "$pdup" ]; then echo "  [!] duplicate port_offset across active workspaces (advisory): $(printf '%s ' $pdup)"; warn=1; fi
   local maxw="${FLOW_WORKSPACE_MAX:-4}"
   if [ "$nact" -gt "$maxw" ]; then echo "  [!] $nact active workspaces exceeds FLOW_WORKSPACE_MAX=$maxw (realistic solo ceiling is 3-4; advisory)."; warn=1; fi
+  # Execution-aware (graph executor): a PAUSED execution is waiting on an operator, so
+  # its worktree must not be reconciled away. git + card files stay the authority; the
+  # journal is a derived record, so this only ever WARNS.
+  if _graph_on; then
+    local eid gstat opens
+    # --no-create: doctor is advisory and read-only; it must never mint an execution.
+    eid="$(_graph_exec_id --no-create 2>/dev/null || true)"
+    if [ -n "$eid" ]; then
+      gstat="$(harness_capture_checked graph status --execution "$eid" 2>/dev/null)"
+      opens="$(printf '%s' "$gstat" | tr ',' '\n' | grep -c '"interrupt_id"' || true)"
+      opens="$(printf '%s' "${opens:-0}" | tr -dc '0-9' | head -c 6)"; opens="${opens:-0}"
+      if [ "${opens:-0}" -gt 0 ]; then
+        echo "  [!] graph execution $eid has $opens OPEN interrupt(s) - do not remove the backing"
+        echo "      worktree(s) until resolved: 'flow harness graph status --execution $eid'"
+        warn=1
+      fi
+    fi
+  fi
   rm -rf "$td"
 
   if [ "$drift" -eq 0 ]; then
@@ -3511,6 +3716,7 @@ usage: bash flow.sh <command> [args]
   assess            Brownfield: scaffold + gate a current-state assessment (flow/00-inspect.md) before planning
   card              Create the next build card (after planning complete)
   check C-NNN       Validate a card (FILL/status/sections/done-evidence)
+  gate <stage>|--card C-NNN  Read-only mechanical scan (no unlock, no durable writes)
   mode [teach|work] Show or set who writes the artifacts
   project-type [t]  Show or set project type (web|cli|library|skill); adapts done-evidence
   skip <stage> --reason  Advance past a gate that has a matching open DEBT (non-security only)
@@ -3576,7 +3782,7 @@ _flow_version() {
 
 _log_is_readonly() { # $1 = command -> true|false (does it mutate the flow plan?)
   case "$1" in
-    status|resume|recall|ready|usage|tokens|coherence|consistency|contract|constitution|doctor|design|help|-h|--help|"") echo true ;;
+    status|resume|recall|ready|usage|tokens|coherence|consistency|contract|constitution|doctor|design|gate|help|-h|--help|"") echo true ;;
     *) echo false ;;
   esac
 }
@@ -3684,6 +3890,10 @@ cmd_usage() {
 }
 
 # ---------- dispatch ----------
+# Library mode: tests source this file to exercise real helpers instead of regex-slicing
+# them out (a slice silently breaks the moment a helper gains a dependency, and then the
+# test reports 127 instead of the behavior it claims to check).
+if [ -n "${FLOW_LIB_ONLY:-}" ]; then return 0 2>/dev/null || exit 0; fi
 cmd="${1:-status}"
 shift 2>/dev/null || true
 FLOW_LOG_CMD="$cmd"
@@ -3697,6 +3907,7 @@ case "$cmd" in
   assess)         cmd_assess ;;
   card)           cmd_card "$@" ;;
   check)          cmd_check "${1:-}" ;;
+  gate)           cmd_gate "$@" ;;
   mode)           cmd_mode "${1:-}" ;;
   project-type)   cmd_project_type "${1:-}" ;;
   skip)           cmd_skip "$@" ;;

package/skills-manifest.json

@@ -1,8 +1,8 @@
 {
   "source": "../skills/flow",
   "destRelative": "skills/flow",
-  "fileCount": 76,
-  "syncedAt": "2026-07-19T14:46:19.032Z",
+  "fileCount": 82,
+  "syncedAt": "2026-07-27T03:21:41.774Z",
   "fileList": [
     "SKILL.md",
     "_templates/00-idea.md",
@@ -37,6 +37,10 @@
     "harness/_domain.py",
     "harness/_presence.py",
     "harness/flow_harness.py",
+    "harness/graph_executor.py",
+    "harness/graph_ids.py",
+    "harness/graph_predicates.py",
+    "harness/pins/flow-topology.sha256",
     "harness/pins/harness-cli-v0.1.17.sha256sums",
     "harness/repo_map.py",
     "harness/schema/001-init.sql",
@@ -48,6 +52,7 @@
     "harness/schema/010-usage-event.sql",
     "harness/schema/011-usage-gate-reason.sql",
     "harness/schema/012-usage-ephemeral.sql",
+    "harness/schema/014-graph-executor.sql",
     "law/CLAUDE.md",
     "law/DESIGN.md",
     "law/RETRO.md",
@@ -68,6 +73,7 @@
     "references/debt-and-halts.md",
     "references/design-review-checklist.md",
     "references/flow-catalog.tsv",
+    "references/flow-topology.json",
     "references/forge-idea.md",
     "references/gate-eval.md",
     "references/gate-rules.md",