@theglitchking/persistent-planning 3.0.0 → 3.1.0

package/scripts/init-phase.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+###############################################################################
+# init-phase.sh - Create a new phase in lg-mode persistent-planning
+#
+# Usage:
+#   bash scripts/init-phase.sh "Phase Name"
+#
+# Creates:
+#   .planning/<phase-slug>/phase.md         (HEWTD-frontmattered phase template)
+#   .planning/<phase-slug>/notes.md         (cross-cutting notes for the phase)
+#   .planning/.meta/workspace.json          (mode = lg, on first phase init)
+#
+# Refuses to run unless mode is lg. Run init-planning.sh for sm-mode tasks.
+###############################################################################
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+case "${1:-}" in
+  -h|--help)
+    cat <<EOF
+Usage: bash scripts/init-phase.sh "Phase Name"
+
+Creates:
+  .planning/<phase-slug>/phase.md
+  .planning/<phase-slug>/notes.md
+  .planning/.meta/workspace.json (on first phase init, with mode=lg)
+
+Refuses to run unless mode is lg. Run init-planning.sh for sm-mode tasks.
+
+Examples:
+  bash scripts/init-phase.sh "Foundation"
+  bash scripts/init-phase.sh "Multi-corpus refactor"
+EOF
+    exit 0
+    ;;
+  "")
+    planning_err "Phase name required."
+    echo ""
+    echo "Usage: bash scripts/init-phase.sh \"Phase Name\""
+    echo "       bash scripts/init-phase.sh --help"
+    exit 1
+    ;;
+esac
+
+PHASE_NAME="$1"
+PHASE_SLUG=$(planning_slugify "$PHASE_NAME")
+
+if [[ -z "$PHASE_SLUG" ]]; then
+  planning_err "Phase name must contain at least one alphanumeric character."
+  exit 1
+fi
+
+# Refuse to run in sm mode
+MODE=$(planning_mode)
+if [[ "$MODE" != "lg" ]]; then
+  planning_err "Current mode is '$MODE' but init-phase.sh requires lg mode."
+  echo ""
+  echo "Switch to lg mode by running:"
+  echo "  /start-planning --mode lg \"<phase name>\""
+  echo "or by editing .planning/.meta/workspace.json directly."
+  exit 1
+fi
+
+ROOT=$(planning_root)
+PLANNING="$(planning_dir)"
+META="$(planning_meta_dir)"
+WORKSPACE_JSON="$(planning_workspace_json)"
+TODAY=$(planning_today)
+PHASE_DIR="${PLANNING}/${PHASE_SLUG}"
+TEMPLATE_DIR="${ROOT}/templates/lg"
+
+# Fallback: when run from the installed plugin location, templates live in the
+# plugin's own directory, not the project root.
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  TEMPLATE_DIR="${SCRIPT_DIR}/../templates/lg"
+fi
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  planning_err "Cannot locate templates/lg directory. Tried:"
+  echo "  ${ROOT}/templates/lg"
+  echo "  ${SCRIPT_DIR}/../templates/lg"
+  exit 1
+fi
+
+planning_log "Initializing phase: ${PHASE_NAME}"
+
+# Bootstrap .planning/.meta/workspace.json if missing
+mkdir -p "$META"
+if [[ ! -f "$WORKSPACE_JSON" ]]; then
+  CONTRIB=0
+  if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+    CONTRIB=$(git -C "$ROOT" log --since="90 days ago" --format='%ae' 2>/dev/null | sort -u | wc -l | tr -d ' ')
+  fi
+  cat > "$WORKSPACE_JSON" <<EOF
+{
+  "schema_version": "1.0",
+  "mode": "lg",
+  "auto_detected": true,
+  "detected_contributors": ${CONTRIB},
+  "created_at": "$(date -Iseconds)"
+}
+EOF
+  planning_ok "Created .planning/.meta/workspace.json (mode=lg, contributors=${CONTRIB})"
+fi
+
+# Create phase directory
+mkdir -p "$PHASE_DIR"
+
+# Render phase.md
+planning_render_and_log \
+  "${TEMPLATE_DIR}/phase.md" \
+  "${PHASE_DIR}/phase.md" \
+  "phase.md at ${PHASE_DIR}/phase.md" \
+  "PHASE_TITLE_PLACEHOLDER=${PHASE_NAME}" \
+  "PHASE_SLUG_PLACEHOLDER=${PHASE_SLUG}" \
+  "PHASE_DATE_PLACEHOLDER=${TODAY}"
+
+# Render notes.md (scoped to the phase)
+planning_render_and_log \
+  "${TEMPLATE_DIR}/notes.md" \
+  "${PHASE_DIR}/notes.md" \
+  "notes.md at ${PHASE_DIR}/notes.md" \
+  "NOTES_TITLE_PLACEHOLDER=${PHASE_NAME} — Notes" \
+  "NOTES_SCOPE_PLACEHOLDER=${PHASE_SLUG}" \
+  "NOTES_DATE_PLACEHOLDER=${TODAY}"
+
+# Add .planning/ to .gitignore if missing (preserve existing behavior)
+GITIGNORE="${ROOT}/.gitignore"
+if [[ -f "$GITIGNORE" ]] && ! grep -q "^\.planning/" "$GITIGNORE"; then
+  echo ".planning/" >> "$GITIGNORE"
+  planning_ok "Added .planning/ to .gitignore"
+fi
+
+echo ""
+planning_ok "Phase '${PHASE_NAME}' ready at .planning/${PHASE_SLUG}/"
+echo ""
+echo "Next steps:"
+echo "  1. Edit .planning/${PHASE_SLUG}/phase.md to describe the phase goal"
+echo "  2. Add tasks with: /start-task \"<task name>\" --parent ${PHASE_SLUG}"
+echo "  3. Add cross-cutting context to .planning/${PHASE_SLUG}/notes.md"

package/scripts/init-planning.sh

@@ -0,0 +1,256 @@
+#!/bin/bash
+
+###############################################################################
+# init-planning.sh - Persistent Planning Directory Setup
+#
+# Part of the persistent-planning plugin by TheGlitchKing
+# https://github.com/TheGlitchKing/persistent-planning
+#
+# Usage:
+#   bash scripts/init-planning.sh [task-name]
+#   bash scripts/init-planning.sh "Refactor database layer"
+#
+# What it does:
+#   1. Creates .planning/[task-slug]/ directory (separate per task)
+#   2. Creates task_plan.md with templates
+#   3. Creates notes.md with templates
+#   4. Adds .planning/ to .gitignore (optional)
+#   5. Confirms creation and provides next steps
+#
+# Multiple tasks example:
+#   /start-planning "Refactor auth"      -> .planning/refactor-auth/
+#   /start-planning "Debug memory leak"  -> .planning/debug-memory-leak/
+#   Both plans coexist without conflicts!
+###############################################################################
+
+set -e
+
+# Validate that task name was provided
+if [ -z "$1" ]; then
+    echo "Error: Task name required"
+    echo ""
+    echo "Usage: bash scripts/init-planning.sh \"Your Task Name\""
+    echo ""
+    echo "Examples:"
+    echo "  bash scripts/init-planning.sh \"Refactor authentication\""
+    echo "  bash scripts/init-planning.sh \"Debug API performance\""
+    exit 1
+fi
+
+TASK_NAME="$1"
+
+# Convert task name to slug
+# "Refactor Authentication" -> "refactor-authentication"
+task_name_to_slug() {
+    local name="$1"
+    name=$(echo "$name" | tr '[:upper:]' '[:lower:]')
+    name=$(echo "$name" | sed 's/[[:space:]_]\+/-/g')
+    name=$(echo "$name" | sed 's/[^a-z0-9-]//g')
+    name=$(echo "$name" | sed 's/^-\+\|-\+$//g')
+    name=$(echo "$name" | sed 's/-\+/-/g')
+    echo "$name"
+}
+
+TASK_SLUG=$(task_name_to_slug "$TASK_NAME")
+
+# Validate slug
+if [ -z "$TASK_SLUG" ]; then
+    echo "Error: Task name must contain at least one alphanumeric character"
+    echo "Provided: $TASK_NAME"
+    exit 1
+fi
+
+# Determine project root
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLANNING_DIR="${PROJECT_ROOT}/.planning"
+TASK_DIR="${PLANNING_DIR}/${TASK_SLUG}"
+
+# Color codes
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${BLUE}Initializing Planning Structure${NC}"
+echo ""
+
+# Step 1: Create .planning directory
+if [ ! -d "$PLANNING_DIR" ]; then
+    mkdir -p "$PLANNING_DIR"
+    echo -e "${GREEN}+${NC} Created .planning/ directory"
+else
+    echo -e "${YELLOW}*${NC} .planning/ directory exists"
+fi
+
+# Step 2: Create task directory
+if [ ! -d "$TASK_DIR" ]; then
+    mkdir -p "$TASK_DIR"
+    echo -e "${GREEN}+${NC} Created task directory: ${CYAN}.planning/${TASK_SLUG}/${NC}"
+else
+    echo -e "${YELLOW}*${NC} Task directory already exists: ${CYAN}.planning/${TASK_SLUG}/${NC}"
+fi
+
+# Step 3: Create task_plan.md
+TASK_PLAN_FILE="${TASK_DIR}/task_plan.md"
+if [ ! -f "$TASK_PLAN_FILE" ]; then
+    cat > "$TASK_PLAN_FILE" << 'EOF'
+# Task Plan: TASK_NAME_PLACEHOLDER
+
+## Goal
+[One sentence describing the end state]
+
+## Phases
+- [ ] Phase 1: Plan and setup
+- [ ] Phase 2: Research/gather information
+- [ ] Phase 3: Execute/build
+- [ ] Phase 4: Review and deliver
+- [ ] Phase 5: Validate success through comprehensive testing (MANDATORY)
+- [ ] Phase 6: Documentation pass -- create/update/deprecate docs (MANDATORY)
+
+> Phases 5 and 6 are mandatory and MUST stay the last two phases of this plan.
+> Insert new work above them; never after. Renumber them if you add phases.
+>
+> - **Validate success**: prove the work with tests that fail if the change breaks.
+> - **Documentation pass**: create/update/deprecate every doc this change touches --
+>   what it is, where it lives, how to fix it, how to operate it, why it matters.
+>   If hit-em-with-the-docs is installed, use it for this pass.
+
+## Key Questions
+1. [Question to answer]
+2. [Question to answer]
+
+## Decisions Made
+- [Decision]: [Rationale]
+
+## Errors Encountered
+- [Error]: [Resolution]
+
+## Status
+**Currently in Phase 1** - Setting up planning structure
+
+---
+
+## Notes
+- This file persists across sessions
+- Update status after each phase
+- Mark completed phases with [x]
+- Save research to notes.md instead of stuffing context
+
+## On Completion
+This plan is complete when every checkbox above is checked. That IS the
+completion signal -- there is no separate status to remember to flip.
+
+When complete, archive it instead of deleting it:
+
+    /plan-status                  # confirm this plan reads COMPLETE
+    /archive-plan TASK_SLUG_PLACEHOLDER    # -> .planning/.archive/TASK_SLUG_PLACEHOLDER/
+
+Archiving moves this directory to the gitignored .planning/.archive/ and stamps
+it archived. Nothing is destroyed.
+EOF
+
+    sed -i "s/TASK_NAME_PLACEHOLDER/${TASK_NAME}/g" "$TASK_PLAN_FILE"
+    sed -i "s/TASK_SLUG_PLACEHOLDER/${TASK_SLUG}/g" "$TASK_PLAN_FILE"
+    echo -e "${GREEN}+${NC} Created task_plan.md"
+else
+    echo -e "${YELLOW}*${NC} task_plan.md already exists (not overwritten)"
+fi
+
+# Step 4: Create notes.md
+NOTES_FILE="${TASK_DIR}/notes.md"
+if [ ! -f "$NOTES_FILE" ]; then
+    cat > "$NOTES_FILE" << 'EOF'
+# Notes: TASK_NAME_PLACEHOLDER
+
+## Key Findings
+- [Finding 1]
+- [Finding 2]
+
+## Research Sources
+- [Source 1]: [URL or reference]
+- [Source 2]: [URL or reference]
+
+## Synthesized Findings
+
+### [Category/Topic 1]
+- [Finding]
+- [Finding]
+
+### [Category/Topic 2]
+- [Finding]
+- [Finding]
+
+## Decisions Made
+- [Decision]: [Rationale]
+- [Decision]: [Rationale]
+
+## Errors & Solutions
+- [Error]: [Resolution]
+- [Error]: [Resolution]
+
+---
+
+## Append-Only Log
+Store findings here as you discover them. This builds a searchable history.
+
+### [Date/Time]
+- [What I found/did]
+EOF
+
+    sed -i "s/TASK_NAME_PLACEHOLDER/${TASK_NAME}/g" "$NOTES_FILE"
+    echo -e "${GREEN}+${NC} Created notes.md"
+else
+    echo -e "${YELLOW}*${NC} notes.md already exists (not overwritten)"
+fi
+
+# Step 5: Update .gitignore
+if [ -f "${PROJECT_ROOT}/.gitignore" ]; then
+    if ! grep -q "^\.planning/" "${PROJECT_ROOT}/.gitignore"; then
+        echo ".planning/" >> "${PROJECT_ROOT}/.gitignore"
+        echo -e "${GREEN}+${NC} Added .planning/ to .gitignore"
+    else
+        echo -e "${YELLOW}*${NC} .planning/ already in .gitignore"
+    fi
+else
+    echo -e "${YELLOW}*${NC} No .gitignore found (not added)"
+fi
+
+# Step 6: List other active tasks
+OTHER_TASKS=$(find "$PLANNING_DIR" -maxdepth 1 -type d -not -name ".planning" -not -path "$TASK_DIR" 2>/dev/null | wc -l)
+if [ "$OTHER_TASKS" -gt 0 ]; then
+    echo ""
+    echo -e "${CYAN}Other active tasks:${NC}"
+    find "$PLANNING_DIR" -maxdepth 1 -type d -not -name ".planning" -not -path "$TASK_DIR" | sort | while read dir; do
+        task_slug=$(basename "$dir")
+        echo "   .planning/${task_slug}/"
+    done
+fi
+
+# Step 7: Confirmation
+echo ""
+echo -e "${GREEN}=====================================${NC}"
+echo -e "${GREEN}Task Plan Ready${NC}"
+echo -e "${GREEN}=====================================${NC}"
+echo ""
+
+echo -e "${BLUE}Task:${NC} ${TASK_NAME}"
+echo -e "${BLUE}Location:${NC} .planning/${TASK_SLUG}/"
+echo ""
+
+echo -e "${BLUE}Files:${NC}"
+echo "  task_plan.md   (your task plan)"
+echo "  notes.md       (research & findings)"
+echo ""
+
+echo -e "${BLUE}Next steps:${NC}"
+echo "  1. Edit .planning/${TASK_SLUG}/task_plan.md to define your phases"
+echo "  2. As you work, update the Status section"
+echo "  3. Save findings to .planning/${TASK_SLUG}/notes.md"
+echo "  4. Re-read task_plan.md before major decisions"
+echo ""
+
+echo -e "${BLUE}Cleanup:${NC}"
+echo "  rm -rf .planning/${TASK_SLUG}/  # Remove this task"
+echo "  rm -rf .planning/               # Remove all tasks"
+echo ""

package/scripts/init-task.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+###############################################################################
+# init-task.sh - Create a new task under a phase in lg-mode persistent-planning
+#
+# Usage:
+#   bash scripts/init-task.sh "Task Name" --parent <phase-slug>
+#
+# Creates:
+#   .planning/<phase-slug>/<task-slug>/task.md
+#   .planning/<phase-slug>/<task-slug>/notes.md
+#   .planning/<phase-slug>/<task-slug>/atoms/   (empty dir for future atoms)
+#
+# Refuses if mode is not lg, or if --parent doesn't reference an existing phase.
+###############################################################################
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/lib/planning.sh"
+
+# Parse arguments
+TASK_NAME=""
+PARENT_PHASE=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --parent)
+      PARENT_PHASE="$2"
+      shift 2
+      ;;
+    -h|--help)
+      cat <<EOF
+Usage: bash scripts/init-task.sh "Task Name" --parent <phase-slug>
+
+Examples:
+  bash scripts/init-task.sh "HEWTD schema extension" --parent foundation
+  bash scripts/init-task.sh "Multi-corpus refactor" --parent semantic-memory-core
+EOF
+      exit 0
+      ;;
+    *)
+      if [[ -z "$TASK_NAME" ]]; then
+        TASK_NAME="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+if [[ -z "$TASK_NAME" || -z "$PARENT_PHASE" ]]; then
+  planning_err "Both task name and --parent <phase-slug> are required."
+  echo "Usage: bash scripts/init-task.sh \"Task Name\" --parent <phase-slug>"
+  exit 1
+fi
+
+TASK_SLUG=$(planning_slugify "$TASK_NAME")
+
+if [[ -z "$TASK_SLUG" ]]; then
+  planning_err "Task name must contain at least one alphanumeric character."
+  exit 1
+fi
+
+# Refuse non-lg
+MODE=$(planning_mode)
+if [[ "$MODE" != "lg" ]]; then
+  planning_err "Current mode is '$MODE' but init-task.sh requires lg mode."
+  exit 1
+fi
+
+ROOT=$(planning_root)
+PLANNING="$(planning_dir)"
+TODAY=$(planning_today)
+PHASE_DIR="${PLANNING}/${PARENT_PHASE}"
+TASK_DIR="${PHASE_DIR}/${TASK_SLUG}"
+TEMPLATE_DIR="${ROOT}/templates/lg"
+
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  TEMPLATE_DIR="${SCRIPT_DIR}/../templates/lg"
+fi
+if [[ ! -d "$TEMPLATE_DIR" ]]; then
+  planning_err "Cannot locate templates/lg directory."
+  exit 1
+fi
+
+# Validate parent phase exists
+if [[ ! -f "${PHASE_DIR}/phase.md" ]]; then
+  planning_err "Parent phase not found: .planning/${PARENT_PHASE}/phase.md"
+  echo "Create the phase first with:"
+  echo "  /start-planning \"<phase name>\"     (which runs init-phase.sh in lg mode)"
+  exit 1
+fi
+
+planning_log "Initializing task: ${TASK_NAME} (parent: ${PARENT_PHASE})"
+
+mkdir -p "${TASK_DIR}/atoms"
+
+planning_render_and_log \
+  "${TEMPLATE_DIR}/task.md" \
+  "${TASK_DIR}/task.md" \
+  "task.md at ${TASK_DIR}/task.md" \
+  "TASK_TITLE_PLACEHOLDER=${TASK_NAME}" \
+  "TASK_SLUG_PLACEHOLDER=${TASK_SLUG}" \
+  "PHASE_SLUG_PLACEHOLDER=${PARENT_PHASE}" \
+  "TASK_DATE_PLACEHOLDER=${TODAY}"
+
+planning_render_and_log \
+  "${TEMPLATE_DIR}/notes.md" \
+  "${TASK_DIR}/notes.md" \
+  "notes.md at ${TASK_DIR}/notes.md" \
+  "NOTES_TITLE_PLACEHOLDER=${TASK_NAME} — Notes" \
+  "NOTES_SCOPE_PLACEHOLDER=${PARENT_PHASE}/${TASK_SLUG}" \
+  "NOTES_DATE_PLACEHOLDER=${TODAY}"
+
+echo ""
+planning_ok "Task '${TASK_NAME}' ready at .planning/${PARENT_PHASE}/${TASK_SLUG}/"
+echo ""
+echo "Next steps:"
+echo "  1. Edit .planning/${PARENT_PHASE}/${TASK_SLUG}/task.md to describe the goal"
+echo "  2. Add atoms with: /start-atom \"<atom name>\" --parent ${TASK_SLUG}"
+echo "     (or add inline atom checkboxes in task.md for simple atoms)"

package/scripts/lib/planning.sh

@@ -0,0 +1,161 @@
+#!/bin/bash
+###############################################################################
+# scripts/lib/planning.sh - Shared helpers for persistent-planning init scripts
+#
+# Source this file from init-phase.sh, init-task.sh, init-atom.sh, and any
+# other planning-related script that needs slug, root, mode, or template
+# rendering helpers.
+#
+# Usage:
+#   #!/bin/bash
+#   set -e
+#   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+#   source "${SCRIPT_DIR}/lib/planning.sh"
+#
+# Provides:
+#   - planning_slugify "Some Name"   →  "some-name" (echoed)
+#   - planning_root                  →  prints project root (CLAUDE_PROJECT_DIR or pwd)
+#   - planning_dir                   →  prints "<root>/.planning"
+#   - planning_meta_dir              →  prints "<root>/.planning/.meta"
+#   - planning_workspace_json        →  prints "<meta>/workspace.json"
+#   - planning_mode                  →  prints active mode (sm | lg) via detect-mode.sh
+#   - planning_today                 →  prints today's date as YYYY-MM-DD
+#   - planning_render_template "<src>" "<dest>" "PLACEHOLDER1=value1" "PLACEHOLDER2=value2" ...
+#       Renders a template file by sed-substituting PLACEHOLDER tokens.
+#       Refuses to overwrite existing dest unless PLANNING_FORCE=1 in env.
+#   - planning_color_<name>          →  ANSI color codes (green, blue, yellow, cyan, red, reset)
+#                                       (only set when stdout is a tty; empty otherwise)
+#   - Color-coded log helpers: planning_log, planning_ok, planning_warn, planning_err
+###############################################################################
+
+# Color codes (only when stdout is a tty)
+if [[ -t 1 ]]; then
+  planning_color_green='\033[0;32m'
+  planning_color_blue='\033[0;34m'
+  planning_color_yellow='\033[1;33m'
+  planning_color_cyan='\033[0;36m'
+  planning_color_red='\033[0;31m'
+  planning_color_reset='\033[0m'
+else
+  planning_color_green=''
+  planning_color_blue=''
+  planning_color_yellow=''
+  planning_color_cyan=''
+  planning_color_red=''
+  planning_color_reset=''
+fi
+
+planning_log()  { printf "${planning_color_blue}[planning]${planning_color_reset} %s\n" "$*"; }
+planning_ok()   { printf "${planning_color_green}[planning]${planning_color_reset} %s\n" "$*"; }
+planning_warn() { printf "${planning_color_yellow}[planning]${planning_color_reset} %s\n" "$*"; }
+planning_err()  { printf "${planning_color_red}[planning]${planning_color_reset} %s\n" "$*" >&2; }
+
+planning_slugify() {
+  local name="$1"
+  name=$(echo "$name" | tr '[:upper:]' '[:lower:]')
+  name=$(echo "$name" | sed 's/[[:space:]_]\+/-/g')
+  name=$(echo "$name" | sed 's/[^a-z0-9-]//g')
+  name=$(echo "$name" | sed 's/^-\+\|-\+$//g')
+  name=$(echo "$name" | sed 's/-\+/-/g')
+  echo "$name"
+}
+
+planning_root() {
+  echo "${CLAUDE_PROJECT_DIR:-$(pwd)}"
+}
+
+planning_dir() {
+  echo "$(planning_root)/.planning"
+}
+
+planning_meta_dir() {
+  echo "$(planning_dir)/.meta"
+}
+
+planning_workspace_json() {
+  echo "$(planning_meta_dir)/workspace.json"
+}
+
+planning_today() {
+  date '+%Y-%m-%d'
+}
+
+planning_mode() {
+  # Resolve via detect-mode.sh (in the same scripts/ dir as the caller's library).
+  local lib_dir
+  lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  local detect="${lib_dir}/../detect-mode.sh"
+  if [[ -x "$detect" ]]; then
+    bash "$detect"
+  else
+    echo "sm"
+  fi
+}
+
+# planning_render_template <template_src> <dest_path> <PLACEHOLDER1=value1> ...
+# Renders a template file by sed-substituting placeholders.
+#
+# Return codes:
+#   0  → rendered fresh
+#   2  → skipped (dest already exists; pass PLANNING_FORCE=1 to overwrite)
+#   1  → error (template not found, etc.)
+#
+# Callers can branch on the return code to log accurately.
+planning_render_template() {
+  local src="$1"
+  local dest="$2"
+  shift 2
+
+  if [[ ! -f "$src" ]]; then
+    planning_err "Template not found: $src"
+    return 1
+  fi
+
+  if [[ -f "$dest" && "${PLANNING_FORCE:-0}" != "1" ]]; then
+    planning_warn "Destination already exists, skipping: $dest"
+    planning_warn "  (re-run with PLANNING_FORCE=1 to overwrite)"
+    return 2
+  fi
+
+  # Copy template to dest
+  cp "$src" "$dest"
+
+  # Apply substitutions
+  for kv in "$@"; do
+    local key="${kv%%=*}"
+    local value="${kv#*=}"
+    # Use a safe delimiter (~) since values may contain /
+    # Escape & and ~ in value
+    local escaped_value
+    escaped_value=$(printf '%s\n' "$value" | sed -e 's/[\&~]/\\&/g')
+    sed -i "s~${key}~${escaped_value}~g" "$dest"
+  done
+  return 0
+}
+
+# planning_render_and_log <template_src> <dest_path> <relative_label> <PLACEHOLDER=val> ...
+# Wraps planning_render_template with accurate logging:
+#   - Prints "Created <relative_label>" only when the template was actually rendered
+#   - Prints nothing extra when skipped (the warn from render_template already covered it)
+#   - Lets the script continue (set -e tolerant) regardless of skip vs render
+planning_render_and_log() {
+  local src="$1"
+  local dest="$2"
+  local label="$3"
+  shift 3
+
+  local rc=0
+  planning_render_template "$src" "$dest" "$@" || rc=$?
+  case $rc in
+    0)
+      planning_ok "Created ${label}"
+      ;;
+    2)
+      # Already covered by the warn inside planning_render_template
+      ;;
+    *)
+      planning_err "Failed to render ${label} (rc=$rc)"
+      return $rc
+      ;;
+  esac
+}