@jeiemgi/cckit 0.1.6

package/scripts/lib/effort-ops-test.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# effort-ops-test.sh — covers the effort lifecycle ops (#48). Hermetic: stubs gh (no network/auth)
+# and uses a throwaway git repo with a bare remote. Run:  bash scripts/lib/effort-ops-test.sh
+set -u
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+LIB="$ROOT/scripts/lib"
+fail=0
+t()  { if [ "$2" = "$3" ]; then echo "ok: $1"; else echo "FAIL: $1 -> got '[$2]' want '[$3]'"; fail=1; fi; }
+tc() { if grep -qE "$2" "$1"; then echo "ok: $3"; else echo "FAIL: $3 (no /$2/ in gh log)"; fail=1; fi; }
+command -v jq  >/dev/null 2>&1 || { echo "effort-ops-test: jq required"  >&2; exit 1; }
+command -v git >/dev/null 2>&1 || { echo "effort-ops-test: git required" >&2; exit 1; }
+
+tmp="$(mktemp -d)"; trap 'rm -rf "$tmp"' EXIT
+export GH_LOG="$tmp/gh.log"; export GH_N="$tmp/n"; : > "$GH_LOG"
+
+# Stub gh: log every call, return canned output keyed on the subcommand.
+stub="$tmp/bin"; mkdir -p "$stub"
+cat > "$stub/gh" <<'SH'
+#!/usr/bin/env bash
+echo "$*" >> "$GH_LOG"
+case "$1 $2" in
+  "issue create")  n=$(( $(cat "$GH_N" 2>/dev/null || echo 0) + 1 )); echo "$n" > "$GH_N"
+                   echo "https://github.com/o/r/issues/$n" ;;
+  "issue edit"|"issue close"|"pr merge") exit 0 ;;
+  "issue view")    echo "[Effort] 99 · demo effort" ;;          # --json title -q .title
+  "pr create")     echo "https://github.com/o/r/pull/7" ;;
+  "api "*|"api")
+    case "$*" in
+      *"--method POST"*"/sub_issues"*) exit 0 ;;                # link a sub
+      *"/sub_issues"*".[].number"*)    printf '101\n102\n' ;;   # list subs (for close)
+      *".id"*)                         echo "55501" ;;          # issue db id
+      *) exit 0 ;;
+    esac ;;
+  *) exit 0 ;;
+esac
+SH
+chmod +x "$stub/gh"
+export PATH="$stub:$PATH"
+export KIT_REPO="o/r" EFFORT_REPO="o/r" KIT_BASE_BRANCH="main"
+# shellcheck source=/dev/null
+source "$LIB/effort.sh" 2>/dev/null
+# shellcheck source=/dev/null
+source "$LIB/effort-ops.sh"
+
+# ── effort_new ────────────────────────────────────────────────────────────────────────────────
+: > "$GH_LOG"
+parent="$(effort_new "[Core] demo effort" "first sub" "second sub" 2>/dev/null)"
+t  "effort_new returns the parent number"          "$parent" "1"
+t  "effort_new creates parent + 2 subs (3 issues)" "$(grep -c 'issue create' "$GH_LOG")" "3"
+t  "effort_new links 2 native sub-issues"          "$(grep -c 'method POST .*sub_issues' "$GH_LOG")" "2"
+tc "$GH_LOG" 'issue create .*--title \[Effort\] · \[Core\] demo effort' "effort_new titles the parent"
+# a jargon/long name is rejected before any issue is created
+: > "$GH_LOG"
+effort_new "refactor the whole scripts/kit wiring layer" >/dev/null 2>&1 && rc=0 || rc=1
+t  "effort_new rejects a bad title"                "$rc" "1"
+t  "effort_new creates nothing on a bad title"     "$(grep -c 'issue create' "$GH_LOG")" "0"
+
+# ── effort_start / effort_pr / effort_close (real git + bare remote) ───────────────────────────
+( cd "$tmp" && git init -q --bare remote.git )
+( cd "$tmp" && git clone -q remote.git work \
+  && cd work && git -c user.email=t@t -c user.name=t commit -q --allow-empty -m init \
+  && git push -q origin HEAD:main )
+cd "$tmp/work"
+
+start_out="$(effort_start 99 demo 2>/dev/null)"
+t  "effort_start echoes wt|branch|num" "${start_out##*|}" "99"
+t  "effort_start created the branch"   "$(git show-ref --verify --quiet refs/heads/effort/99-demo && echo yes)" "yes"
+
+# move onto the effort branch (its worktree) for pr/close
+cd "$tmp/work/.claude/worktrees/effort-99"
+: > "$GH_LOG"
+effort_pr 99 >/dev/null 2>&1
+tc "$GH_LOG" 'pr create .*--base main --head effort/99-demo' "effort_pr opens effort/99 → main"
+
+: > "$GH_LOG"
+effort_close 99 >/dev/null 2>&1
+tc "$GH_LOG" 'pr merge effort/99-demo .*--squash' "effort_close squash-merges the PR"
+tc "$GH_LOG" 'issue close 101'  "effort_close closes sub #101"
+tc "$GH_LOG" 'issue close 99 '  "effort_close closes the parent"
+
+[ "$fail" -eq 0 ] && echo "ALL OK (effort-ops)" || echo "effort-ops: FAILURES"
+exit "$fail"

package/scripts/lib/effort-ops.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+# effort-ops.sh — the effort lifecycle as shell ops, so `cckit effort new|start|pr|close` works from
+# any shell or agent (not only via the effort-* skills). Thin: composes the git-mechanics helpers in
+# effort.sh (linking, snapshots, title lint) plus gh + git. bash 3.2 compatible. Requires: gh, jq, git.
+#
+#   effort_new "<name>" [<sub title> …]   parent issue (template) + native sub-issues, all linked
+#   effort_start <N> [<slug>]             effort/<N> branch + worktree from the base branch
+#   effort_pr [<N>]                       open the ONE PR effort/<N> → base branch
+#   effort_close <N>                      snapshot sub-diffs, squash-merge the PR, close parent + subs
+#
+# Repo + base branch come from kit.config.json (EFFORT_REPO / KIT_BASE_BRANCH), loaded by effort.sh.
+
+_eff_repo()  { printf '%s' "${EFFORT_REPO:-${KIT_REPO:-}}"; }
+_eff_base()  { printf '%s' "${KIT_BASE_BRANCH:-main}"; }
+_eff_slug()  { # <text> → a short branch-safe slug (mirrors wt_start)
+  printf '%s' "$1" | sed -E 's/^\[[^]]+\][[:space:]]*//' | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g' | cut -c1-40
+}
+_eff_need()  { command -v "$1" >/dev/null 2>&1 || { echo "effort: $1 is required" >&2; return 1; }; }
+
+# The parent-issue body template (rules/effort-model.md): the four sections double as the work record.
+_eff_parent_body() {
+  cat <<'EOF'
+## Goal
+<!-- problem statement: what outcome, in one or two lines -->
+
+## Scope
+<!-- the sub-issue plan; mark each parallel | sequential / dependsOn -->
+
+## For agents
+<!-- exact file paths / entry points a future agent needs -->
+
+## Verification
+<!-- how we know it's done: commands, checks, acceptance -->
+EOF
+}
+
+# effort_new "<name>" [<sub title> …] — create the parent (template) + native sub-issues, linked.
+effort_new() {
+  _eff_need gh || return 1; _eff_need jq || return 1
+  local repo name; repo="$(_eff_repo)"; name="${1:-}"; shift || true
+  [ -n "$repo" ] || { echo "effort_new: no repo (KIT_REPO/EFFORT_REPO unset — run in a kit project)" >&2; return 1; }
+  [ -n "$name" ] || { echo 'effort_new: usage: effort_new "<name>" [<sub title> …]' >&2; return 1; }
+  # Validate the name against the title rule BEFORE creating anything (synthetic prefix for the lint).
+  effort_title_lint "[Effort] 0 · $name" || { echo "effort_new: fix the name and retry" >&2; return 1; }
+
+  local url num
+  url="$(gh issue create --repo "$repo" --title "[Effort] · $name" --body "$(_eff_parent_body)")" \
+    || { echo "effort_new: failed to create the parent issue" >&2; return 1; }
+  num="${url##*/}"
+  gh issue edit "$num" --repo "$repo" --title "[Effort] $num · $name" >/dev/null 2>&1
+  echo "  ✓ effort #$num · $name" >&2
+
+  local i=0 sub child
+  for sub in "$@"; do
+    i=$((i + 1))
+    child="$(gh issue create --repo "$repo" --title "[Effort $num] $i · $sub" --body "Parent #$num." )" || continue
+    effort_link_sub "$num" "${child##*/}" || true
+  done
+  printf '%s\n' "$num"
+}
+
+# effort_start <N> [<slug>] — create the effort/<N> integration branch + its worktree from the base.
+effort_start() {
+  _eff_need git || return 1
+  local num="${1:-}" slug_override="${2:-}" repo base root title slug branch wt
+  [ -n "$num" ] || { echo "effort_start: <effort issue #> required" >&2; return 1; }
+  repo="$(_eff_repo)"; base="$(_eff_base)"
+  root="$(git worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2; exit}')"
+  [ -n "$root" ] || { echo "effort_start: not in a git repo" >&2; return 1; }
+
+  if [ -n "$slug_override" ]; then slug="$slug_override"
+  else
+    title="$(gh issue view "$num" --repo "$repo" --json title -q .title 2>/dev/null)"
+    slug="$(_eff_slug "${title:-effort}")"; [ -n "$slug" ] || slug="effort"
+  fi
+  branch="effort/$num-$slug"; wt="$root/.claude/worktrees/effort-$num"
+
+  git -C "$root" fetch origin "$base" --quiet 2>/dev/null || true
+  if git -C "$root" show-ref --verify --quiet "refs/heads/$branch"; then
+    echo "effort_start: branch $branch already exists" >&2
+  else
+    local from="origin/$base"; git -C "$root" rev-parse --verify --quiet "$from" >/dev/null 2>&1 || from="$base"
+    git -C "$root" worktree add -b "$branch" "$wt" "$from" >/dev/null 2>&1 \
+      || { echo "effort_start: failed to create worktree for $branch" >&2; return 1; }
+  fi
+  echo "  ✓ effort #$num → $branch  (worktree: $wt)" >&2
+  printf '%s|%s|%s\n' "$wt" "$branch" "$num"
+}
+
+# effort_pr [<N>] — open the single PR effort/<N> → base. N defaults to the current effort branch.
+effort_pr() {
+  _eff_need gh || return 1
+  local num="${1:-}" repo base branch title name
+  repo="$(_eff_repo)"; base="$(_eff_base)"
+  branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+  [ -n "$num" ] || num="$(effort_branch_num "$branch")"
+  [ -n "$num" ] || { echo "effort_pr: not on an effort/<N>-… branch and no <N> given" >&2; return 1; }
+  case "$branch" in effort/"$num"-*) : ;; *) echo "effort_pr: current branch ($branch) is not effort/$num-…" >&2; return 1 ;; esac
+
+  git push -u origin "$branch" >/dev/null 2>&1 || true
+  title="$(gh issue view "$num" --repo "$repo" --json title -q .title 2>/dev/null)"
+  name="$(printf '%s' "$title" | sed -E 's/^\[Effort\] [0-9]+ · ?//')"
+  gh pr create --repo "$repo" --base "$base" --head "$branch" \
+    --title "[Effort] $num · ${name:-effort}" \
+    --body "$(printf 'Closes the #%s effort.\n\n## For agents\nSee #%s for the goal, scope, and entry points.\n' "$num" "$num")"
+}
+
+# effort_close <N> — snapshot per-sub diffs (before squash), squash-merge the PR, close parent + subs.
+# Destructive: it merges and closes. Snapshots first so the per-sub work record survives the squash.
+effort_close() {
+  _eff_need gh || return 1; _eff_need jq || return 1
+  local num="${1:-}" repo base branch
+  [ -n "$num" ] || { echo "effort_close: <effort issue #> required" >&2; return 1; }
+  repo="$(_eff_repo)"; base="$(_eff_base)"
+  branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+  case "$branch" in effort/"$num"-*) : ;; *) echo "effort_close: run from the effort/$num-… branch" >&2; return 1 ;; esac
+
+  # (a) snapshot the per-sub-issue diffs while the unsquashed history still exists.
+  effort_snapshot_subs "$num" "origin/$base" || true
+  # (b) squash-merge the effort PR.
+  gh pr merge "$branch" --repo "$repo" --squash --delete-branch >/dev/null 2>&1 \
+    || { echo "effort_close: could not squash-merge the PR for $branch (open? mergeable?)" >&2; return 1; }
+  echo "  ✓ merged $branch" >&2
+  # (c) close every native sub-issue, then the parent.
+  local sub
+  for sub in $(gh api "repos/$repo/issues/$num/sub_issues" --jq '.[].number' 2>/dev/null); do
+    gh issue close "$sub" --repo "$repo" --reason completed >/dev/null 2>&1 && echo "  ✓ closed sub #$sub" >&2
+  done
+  gh issue close "$num" --repo "$repo" --reason completed >/dev/null 2>&1 && echo "  ✓ closed effort #$num" >&2
+}

package/scripts/lib/effort-plan.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# effort-plan.sh — the session-fit view (`kit effort plan` when the project ships the kit CLI).
+#
+# Reads the open efforts (label:effort), groups them by their `flow:` tag, orders each flow by the
+# native `blocked_by` edges, and packs the efforts into session-sized batches under a context budget.
+# Answers "which efforts fit in one session before the context window fills, and in what order?".
+#
+# ctx weights: S=1 · M=2 · L=4 · XL=8. The budget (KIT_SESSION_BUDGET, default 4) is how much one
+# session holds. L/XL efforts are flagged "→ delegate subs" — delegating an effort's sub-issues to
+# sub-agents in their own worktrees keeps the MAIN session light (a sub-agent's file reading happens
+# in its own context; only a summary returns), which is the real lever that widens a session
+# (rules/agent-execution-routing.md).
+#
+# Requires: gh, jq. bash 3.2 (no associative arrays — parallel indexed arrays + linear scan; N small).
+
+EFFORT_REPO="${EFFORT_REPO:-${KIT_REPO:-}}"
+
+_ep_weight() { case "$1" in S) echo 1 ;; M) echo 2 ;; L) echo 4 ;; XL) echo 8 ;; *) echo 2 ;; esac; }
+
+effort_plan() {
+  command -v gh >/dev/null 2>&1 && command -v jq >/dev/null 2>&1 || { echo "effort plan: needs gh + jq" >&2; return 1; }
+  local repo="$EFFORT_REPO" budget="${KIT_SESSION_BUDGET:-4}"
+  [[ -n "$repo" ]] || { echo "effort plan: no repo (set KIT_REPO / EFFORT_REPO)" >&2; return 1; }
+
+  # 1. open efforts + their flow:/ctx: labels (one query).
+  local raw
+  raw="$(gh issue list --repo "$repo" --label effort --state open --limit 100 \
+    --json number,title,labels \
+    --jq '.[] | [ (.number|tostring),
+                  ([.labels[].name|select(startswith("flow:"))|ltrimstr("flow:")]|first // "—"),
+                  ([.labels[].name|select(startswith("ctx:"))|ltrimstr("ctx:")]|first // "?"),
+                  .title ] | @tsv' 2>/dev/null)" \
+    || { echo "effort plan: gh query failed (check gh auth)" >&2; return 1; }
+  [[ -n "$raw" ]] || { echo "effort plan: no open efforts found" >&2; return 0; }
+
+  # 2. read into parallel arrays + fetch blocked_by per effort (small N).
+  local -a nums=() flows=() ctxs=() titles=() blocks=()
+  local n f c t
+  while IFS=$'\t' read -r n f c t; do
+    [[ -n "$n" ]] || continue
+    nums+=("$n"); flows+=("$f"); ctxs+=("$c"); titles+=("$t")
+    blocks+=("$(gh api "repos/$repo/issues/$n/dependencies/blocked_by" --jq '[.[].number]|join(",")' 2>/dev/null)")
+  done <<< "$raw"
+
+  # 3. distinct flows, first-seen order.
+  local -a flowlist=()
+  for f in "${flows[@]}"; do
+    case " ${flowlist[*]-} " in *" $f "*) ;; *) flowlist+=("$f") ;; esac
+  done
+
+  printf '\n  kit effort plan — session budget %s  (ctx S=1 M=2 L=4 XL=8 · L/XL → delegate subs)\n' "$budget"
+
+  local i j b
+  for f in "${flowlist[@]}"; do
+    printf '\n  Flow: %s\n' "$f"
+
+    # indices in this flow
+    local -a idxs=()
+    for i in "${!nums[@]}"; do [[ "${flows[$i]}" == "$f" ]] && idxs+=("$i"); done
+
+    # 4. order: Kahn-lite — emit an effort once all its in-flow blockers are placed (roots first).
+    local -a order=()
+    local placed=" " progress=1
+    while [[ "${#order[@]}" -lt "${#idxs[@]}" && "$progress" -eq 1 ]]; do
+      progress=0
+      for i in "${idxs[@]}"; do
+        case "$placed" in *" $i "*) continue ;; esac
+        local ready=1
+        for b in ${blocks[$i]//,/ }; do
+          for j in "${idxs[@]}"; do
+            if [[ "${nums[$j]}" == "$b" ]]; then
+              case "$placed" in *" $j "*) ;; *) ready=0 ;; esac
+            fi
+          done
+        done
+        if [[ "$ready" -eq 1 ]]; then order+=("$i"); placed="$placed$i "; progress=1; fi
+      done
+    done
+    # cycle / leftover safety: append anything not yet placed.
+    for i in "${idxs[@]}"; do case "$placed" in *" $i "*) ;; *) order+=("$i"); placed="$placed$i " ;; esac; done
+
+    # 5. greedy-pack into sessions: new session when budget would overflow OR the next effort is
+    #    blocked by one already in the current batch (a blocker and its dependent can't share a session).
+    local sess=1 load=0 batch=" "
+    printf '    Session %s:\n' "$sess"
+    for i in "${order[@]}"; do
+      local w; w="$(_ep_weight "${ctxs[$i]}")"
+      local neednew=0
+      (( load + w > budget )) && neednew=1
+      for b in ${blocks[$i]//,/ }; do case "$batch" in *" $b "*) neednew=1 ;; esac; done
+      if [[ "$neednew" -eq 1 && "$load" -gt 0 ]]; then
+        sess=$((sess + 1)); load=0; batch=" "
+        printf '    Session %s:\n' "$sess"
+      fi
+      load=$((load + w)); batch="$batch${nums[$i]} "
+      local note=""; case "${ctxs[$i]}" in L|XL) note="   → delegate subs" ;; esac
+      local dep=""; [[ -n "${blocks[$i]}" ]] && dep="   (after #${blocks[$i]//,/, #})"
+      # strip the "[Effort] N · " prefix + a leading "[Flow] " tag — #N and the flow are already shown.
+      local disp; disp="$(printf '%s' "${titles[$i]}" | sed -E 's/^\[Effort( [0-9]+)?\] [0-9]+ · ?//; s/^\[[A-Za-z]+\] //')"
+      printf '      #%-4s [%-2s] %s%s%s\n' "${nums[$i]}" "${ctxs[$i]}" "$disp" "$dep" "$note"
+    done
+  done
+  printf '\n'
+}

package/scripts/lib/effort.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# effort.sh — shared git-mechanics for the effort-* skill family (the effort model; rules/effort-model.md).
+#
+# Family 1 of the kit boundary (one bash home per op): consumed by the effort-{new,start,pr,close}
+# skills. The skills are thin callers — no second implementation of these ops anywhere.
+#
+# Functions:
+#   effort_link_sub <parent_num> <child_num>            link a native GitHub sub-issue (REST sub-issues API)
+#   effort_branch_num                                   echo the effort issue # parsed from the current branch
+#   effort_trace_dir <parent_num>                       echo (and mkdir -p) the trace dir under the git-common-dir
+#   effort_snapshot_subs <parent_num> [base_ref]        snapshot per-sub-issue diffs BEFORE squash (work trace)
+#   effort_title_lint <full-title>                      enforce the concise / no-jargon / flow-tagged title rule
+#   effort_set_blocked_by <issue> <blocker>             set a native GitHub blocked_by dependency edge
+#
+# Requires: gh, jq, git. bash 3.2 compatible.
+
+# Repo resolves from kit.config.json (KIT_REPO) — load it if a caller hasn't already.
+if [[ -z "${KIT_REPO:-}" ]]; then
+  _eff_root="$(git rev-parse --show-toplevel 2>/dev/null)"
+  if [[ -n "$_eff_root" && -f "$_eff_root/scripts/lib/kit-config.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "$_eff_root/scripts/lib/kit-config.sh" && load_kit_config >/dev/null 2>&1 || true
+  fi
+  unset _eff_root
+fi
+EFFORT_REPO="${EFFORT_REPO:-${KIT_REPO:-}}"
+
+# Link a child issue as a native GitHub sub-issue of a parent.
+# The sub-issues REST API takes the child's DATABASE id (not its number):
+#   POST /repos/{owner}/{repo}/issues/{parent}/sub_issues  {"sub_issue_id": <child db id>}
+effort_link_sub() {
+  local parent="$1" child="$2" child_id
+  [[ -n "$parent" && -n "$child" ]] || { echo "effort_link_sub: parent + child issue numbers required" >&2; return 1; }
+  child_id="$(gh api "repos/$EFFORT_REPO/issues/$child" --jq .id 2>/dev/null)" \
+    || { echo "effort_link_sub: could not resolve db id for #$child" >&2; return 1; }
+  gh api --method POST "repos/$EFFORT_REPO/issues/$parent/sub_issues" \
+    -F sub_issue_id="$child_id" >/dev/null 2>&1 \
+    && { echo "  ✓ linked #$child as sub-issue of #$parent" >&2; return 0; } \
+    || { echo "  ✗ failed to link #$child under #$parent (already linked? API unavailable?)" >&2; return 1; }
+}
+
+# Parse the effort issue number from an `effort/<N>-<slug>` branch. Echoes N (empty if no match).
+effort_branch_num() {
+  local branch="${1:-$(git rev-parse --abbrev-ref HEAD 2>/dev/null)}"
+  echo "$branch" | sed -nE 's#^effort/([0-9]+)-.*#\1#p'
+}
+
+# The durable trace dir for an effort: under the SHARED git-common-dir so it survives worktree prune
+# and is visible from the main checkout (an exporter can consume it later). Echoes the path.
+effort_trace_dir() {
+  local parent="$1" common
+  common="$(git rev-parse --git-common-dir 2>/dev/null)" || return 1
+  case "$common" in /*) : ;; *) common="$(cd "$common" 2>/dev/null && pwd)" || return 1 ;; esac
+  local dir="$common/traces/effort-$parent"
+  mkdir -p "$dir" 2>/dev/null || return 1
+  printf '%s' "$dir"
+}
+
+# Snapshot per-sub-issue diffs BEFORE the effort PR is squash-merged (squash collapses the per-sub
+# commit pairs that ARE the per-unit work record — see effort-model.md "Trace hard rules").
+#
+# Strategy (simple, exporter-consumable): for each commit on the effort branch that isn't on the
+# base, write its diff + metadata to $traces/effort-<N>/<seq>-<shortsha>.{diff,meta}. We map a commit
+# to a sub-issue by the LAST "#<num>" reference in its subject/body (the convention: one commit per
+# sub-issue mentioning that sub-issue). Commits with no #ref still get snapshotted (sub="").
+#
+# Args: <parent_num> [base_ref=origin/main]
+effort_snapshot_subs() {
+  local parent="$1" base="${2:-origin/main}" branch dir shas seq=0
+  [[ -n "$parent" ]] || { echo "effort_snapshot_subs: parent issue number required" >&2; return 1; }
+  branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+  dir="$(effort_trace_dir "$parent")" || { echo "effort_snapshot_subs: could not create trace dir" >&2; return 1; }
+
+  git fetch origin --quiet 2>/dev/null || true
+  # Oldest-first so <seq> increases with history.
+  shas="$(git rev-list --reverse "$base..HEAD" 2>/dev/null)"
+  if [[ -z "$shas" ]]; then
+    echo "effort_snapshot_subs: no commits between $base and HEAD — nothing to snapshot" >&2
+    return 0
+  fi
+
+  # An index file ties the snapshot together for an exporter.
+  local index="$dir/index.jsonl"
+  : > "$index"
+
+  local sha sub subj body
+  for sha in $shas; do
+    seq=$((seq + 1))
+    subj="$(git log -1 --format='%s' "$sha")"
+    body="$(git log -1 --format='%b' "$sha")"
+    # Last #<num> mentioned = the sub-issue this commit closes/implements (effort-model convention).
+    sub="$(printf '%s\n%s' "$subj" "$body" | grep -oE '#[0-9]+' | tail -1 | tr -d '#')"
+    local stub
+    stub="$(printf '%02d-%s' "$seq" "$(git rev-parse --short "$sha")")"
+    git show --no-color --format=fuller "$sha" > "$dir/$stub.diff" 2>/dev/null
+    # meta: commit→sub-issue pairing + outcome hint for the record.
+    jq -n --arg parent "$parent" --arg sub "${sub:-}" --arg sha "$sha" \
+          --arg subject "$subj" --arg branch "$branch" --arg file "$stub.diff" \
+      '{parent:($parent|tonumber), sub_issue:(if $sub=="" then null else ($sub|tonumber) end),
+        commit:$sha, subject:$subject, branch:$branch, diff_file:$file, outcome:"merged"}' \
+      > "$dir/$stub.meta"
+    cat "$dir/$stub.meta" >> "$index"
+  done
+
+  echo "  ✓ snapshotted $seq commit(s) to $dir (index.jsonl)" >&2
+  printf '%s' "$dir"
+}
+
+# ── Effort-title rule — concise, jargon-free, flow-tagged ──────────────────────────────────────────
+# The board must say what an effort delivers and which FLOW it belongs to. So the `<Name>` part of an
+# effort/sub title is a short plain-language outcome with an optional leading `[Flow]` tag from a
+# controlled vocabulary — never internal jargon, glyphs, code identifiers, parentheticals, em-dash
+# sub-clauses, or >6 words (detail goes in the body). See rules/effort-model.md § Titles.
+
+# Controlled flow vocabulary for the optional leading [Flow] title tag. Projects override via EFFORT_FLOWS.
+EFFORT_FLOWS="${EFFORT_FLOWS:-Core UI API Docs Infra Auth Data Web App}"
+# Jargon denylist — internal terms that read as noise on the board. Override via EFFORT_TITLE_JARGON.
+EFFORT_TITLE_JARGON="${EFFORT_TITLE_JARGON:-chrome seam contract claim rescue stash teardown scaffolding shim boilerplate refactor wiring}"
+
+# effort_title_lint <full-title> — 0 if the title is clean; 1 + reasons on stderr otherwise.
+# Accepts "[Effort] N · [Flow] short name" or "[Effort N] M · short name".
+effort_title_lint() {
+  local title="$1" name flow rest
+  local -a reasons=()
+  [[ -n "$title" ]] || { echo "effort_title_lint: title required" >&2; return 2; }
+
+  # 1. peel the structural prefix → the human name part.  parent: "[Effort] N · "  sub: "[Effort N] M · "
+  name="$(printf '%s' "$title" | sed -E 's/^\[Effort( [0-9]+)?\] [0-9]+ · ?//')"
+  [[ "$name" == "$title" ]] && reasons+=("missing the '[Effort] N · ' / '[Effort N] M · ' prefix")
+
+  # 2. peel one optional leading [Flow] tag and validate it against the controlled vocabulary.
+  if [[ "$name" =~ ^\[([A-Za-z]+)\]\ (.+)$ ]]; then
+    flow="${BASH_REMATCH[1]}"; rest="${BASH_REMATCH[2]}"; name="$rest"
+    case " $EFFORT_FLOWS " in
+      *" $flow "*) : ;;
+      *) reasons+=("flow tag [$flow] is not in the vocabulary ($EFFORT_FLOWS)") ;;
+    esac
+  fi
+
+  # 3. the remaining name must be a concise, plain outcome phrase.
+  case "$name" in *"("*|*")"*) reasons+=("no parentheses — detail goes in the body") ;; esac
+  case "$name" in *" — "*|*" · "*|*" / "*) reasons+=("no ' — ' / ' · ' / ' / ' sub-clauses — one clear phrase") ;; esac
+  case "$name" in *—*|*▾*|*▸*|*→*|*✓*|*✗*|*…*|*•*) reasons+=("no glyphs (— ▾ ▸ → ✓ ✗ … •) in the title") ;; esac
+  # code identifiers: file extensions, snake_case, or a code-dir path.
+  if printf '%s' "$name" | grep -qE '\.(sh|ts|tsx|js|mjs|json|css|md|ya?ml)([^A-Za-z0-9]|$)|[a-z0-9]+_[a-z0-9]+|(^|[^A-Za-z])(scripts|apps|packages|src)/'; then
+    reasons+=("no code identifiers (file names, paths, snake_case) — name the outcome")
+  fi
+  # jargon denylist (word-boundary, case-insensitive).
+  local w
+  for w in $EFFORT_TITLE_JARGON; do
+    printf '%s' "$name" | grep -qiwE "$w" && reasons+=("jargon word '$w' — use plain language")
+  done
+  # word count ≤ 6.
+  local wc; wc=$(printf '%s\n' "$name" | wc -w | tr -d ' ')
+  [[ "$wc" -gt 6 ]] && reasons+=("name is $wc words — keep it ≤ 6 (detail goes in the body)")
+
+  if [[ "${#reasons[@]}" -gt 0 ]]; then
+    { echo "✗ effort title fails the concise / no-jargon rule: $title"
+      for w in "${reasons[@]}"; do echo "    - $w"; done
+    } >&2
+    return 1
+  fi
+  return 0
+}
+
+# effort_set_blocked_by <issue> <blocker-issue> — declare the native GitHub dependency "<issue> is
+# blocked_by <blocker>" (the edge GitHub renders on the board). The API takes the blocker's DB id.
+effort_set_blocked_by() {
+  local issue="$1" blocker="$2" bid
+  [[ -n "$issue" && -n "$blocker" ]] || { echo "effort_set_blocked_by: <issue> <blocker> required" >&2; return 1; }
+  bid="$(gh api "repos/$EFFORT_REPO/issues/$blocker" --jq .id 2>/dev/null)" \
+    || { echo "effort_set_blocked_by: could not resolve db id for #$blocker" >&2; return 1; }
+  gh api --method POST "repos/$EFFORT_REPO/issues/$issue/dependencies/blocked_by" -F issue_id="$bid" >/dev/null 2>&1 \
+    && { echo "  ✓ #$issue blocked_by #$blocker" >&2; return 0; } \
+    || { echo "  ✗ failed to set #$issue blocked_by #$blocker (already set? API unavailable?)" >&2; return 1; }
+}
+
+# Self-test: `bash scripts/lib/effort.sh --selftest` exercises effort_title_lint (jargon → reject,
+# plain → accept). Runs only when executed directly.
+if [[ "${BASH_SOURCE[0]:-}" == "${0:-}" && "${1:-}" == "--selftest" ]]; then
+  _et_rc=0
+  _et_fail() { if effort_title_lint "$1" >/dev/null 2>&1; then echo "FAIL expected-reject passed: $1"; _et_rc=1; else echo "ok  reject: $1"; fi; }
+  _et_pass() { if effort_title_lint "$1" >/dev/null 2>&1; then echo "ok  accept: $1"; else echo "FAIL expected-accept rejected: $1"; effort_title_lint "$1"; _et_rc=1; fi; }
+  _et_fail "[Effort] 12 · operator chrome — Settings ▾ dropdown + layout fixes"
+  _et_fail "[Effort 12] 4 · Section tables — columns + joins (contract B)"
+  _et_fail "[Effort] 12 · refactor scripts/kit + quote-aware free-prompt args"
+  _et_pass "[Effort] 12 · [UI] operator navigation"
+  _et_pass "[Effort] 12 · effort planning conventions"
+  _et_pass "[Effort 12] 4 · module tables"
+  exit "$_et_rc"
+fi

package/scripts/lib/engine-adapter.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# engine-adapter.sh — pluggable bridge from the kit CLI to the Plan Engine.
+#
+# Family 2 of kit-engine-boundary.md: plan/ticket/Deliverable graph ops. The kit CLI is the
+# human/Claude surface; the Plan Engine Postgres graph (ADR-004/005) is the source of truth.
+# This adapter is the seam between them — and it is PLUGGABLE so the kit stays portable as a
+# product: the default mode is "off", meaning the kit runs engine-less (bash + GitHub, today's
+# behavior). cckit and clients opt in by setting the engine block in .claude/kit.config.json.
+#
+# Config (.claude/kit.config.json):
+#   "engine": { "mode": "off" | "http", "url": "https://engine.example", "token_env": "CCKIT_ENGINE_TOKEN" }
+#
+# Source it, then call engine_cmd / engine_call.  Requires: jq, curl (only when mode != off).
+
+_engine_cfg() { echo "${KIT_CONFIG:-.claude/kit.config.json}"; }
+
+engine_mode() { jq -r '.engine.mode // "off"' "$(_engine_cfg)" 2>/dev/null || echo off; }
+engine_url()  { jq -r '.engine.url  // ""'    "$(_engine_cfg)" 2>/dev/null; }
+engine_enabled() { [[ "$(engine_mode)" != "off" ]]; }
+
+# engine_call <METHOD> <path> [json-body] — returns the engine response on stdout.
+# Returns 3 when the engine is not configured (local mode), so callers can fall back to GitHub.
+engine_call() {
+  # NOTE: `route` not `path` — `path` is a special zsh parameter tied to $PATH; a `local path=…`
+  # silently corrupts the command search path under zsh (the session shell), so jq/curl then fail
+  # and engine_enabled reads "off". (delegation-brief: status/path are zsh-special.)
+  local method="$1" route="$2" body="${3:-}" url tokenvar tok
+  engine_enabled || { echo "engine: off (local mode)" >&2; return 3; }
+  url="$(engine_url)"; [[ -n "$url" ]] || { echo "engine.url not set in $(_engine_cfg)" >&2; return 3; }
+  command -v curl >/dev/null || { echo "curl required for engine mode" >&2; return 1; }
+  tokenvar="$(jq -r '.engine.token_env // ""' "$(_engine_cfg)")"
+  local -a auth=()
+  # Portable indirect expansion — bash's ${!var} is not zsh-compatible (zsh would need ${(P)var}).
+  [[ -n "$tokenvar" ]] && eval "tok=\${$tokenvar:-}"
+  # Auto-load the engine token from the untracked local secret file when the env var is unset.
+  # The token lives in <main-checkout>/scripts/.engine-secret.env (gitignored plaintext) and nothing
+  # else sources it — without this the Authorization header silently drops and effort-metrics sync
+  # buffers instead of POSTing. The secret is UNTRACKED, so it exists ONLY in the MAIN checkout, not
+  # in effort worktrees (where kit-effort-close actually runs). Resolve it via git-common-dir — the
+  # shared .git whose parent IS the main checkout, correct from any worktree — then fall back to the
+  # current checkout toplevel / this script's location. Missing file = silent no-op. zsh-safe: no
+  # `path` local, portable indirect expansion (no ${!var}).
+  if [[ -z "${tok:-}" && -n "$tokenvar" ]]; then
+    local common main_root secret_file="" cand
+    # 1) main checkout via the shared git-common-dir (works from any worktree).
+    common="$(git rev-parse --git-common-dir 2>/dev/null)"
+    if [[ -n "$common" ]]; then
+      case "$common" in /*) : ;; *) common="$PWD/$common" ;; esac
+      main_root="$(dirname "$common")"
+      [[ -f "$main_root/scripts/.engine-secret.env" ]] && secret_file="$main_root/scripts/.engine-secret.env"
+    fi
+    # 2) current checkout toplevel, then 3) relative to this script — fallbacks.
+    if [[ -z "$secret_file" ]]; then
+      for cand in "$(git rev-parse --show-toplevel 2>/dev/null)" \
+                  "$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"; do
+        [[ -n "$cand" && -f "$cand/scripts/.engine-secret.env" ]] && { secret_file="$cand/scripts/.engine-secret.env"; break; }
+      done
+    fi
+    if [[ -n "$secret_file" ]]; then
+      # shellcheck disable=SC1090
+      . "$secret_file"
+      eval "tok=\${$tokenvar:-}"
+    fi
+  fi
+  [[ -n "${tok:-}" ]] && auth=(-H "Authorization: Bearer $tok")
+  if [[ -n "$body" ]]; then
+    curl -fsS -X "$method" "${auth[@]}" -H "Content-Type: application/json" --data "$body" "$url$route"
+  else
+    curl -fsS -X "$method" "${auth[@]}" -H "Content-Type: application/json" "$url$route"
+  fi
+}
+
+# kit engine <status|ping>
+engine_cmd() {
+  case "${1:-status}" in
+    status)
+      local mode; mode="$(engine_mode)"
+      if engine_enabled; then
+        echo "engine mode: $mode"
+        echo "engine url:  $(engine_url)"
+      else
+        echo "engine mode: off (local mode) - graph ops are GitHub-backed"
+        echo "connect: set .engine in $(_engine_cfg) (see scripts/lib/engine-adapter.sh)"
+      fi
+      ;;
+    ping)
+      engine_enabled || { echo "engine: off (local mode) - nothing to ping"; return 0; }
+      engine_call GET /health && echo "" || { echo "engine unreachable" >&2; return 1; }
+      ;;
+    *) echo "unknown: kit engine ${1:-}" >&2; return 2 ;;
+  esac
+}