1#!/usr/bin/env bash
2# Initialize planning files for a new session.
3#
4# Usage:
5#   ./init-session.sh                              # legacy: root-level task_plan.md, findings.md, progress.md
6#   ./init-session.sh [--template TYPE]            # legacy with template choice
7#   ./init-session.sh "Backend Refactor"           # slug mode: .planning/<date>-backend-refactor/
8#   ./init-session.sh --plan-dir                   # slug mode with auto-generated untitled-<short> name
9#   ./init-session.sh --plan-dir "Quick Spike"     # slug mode, explicit slug
10#   ./init-session.sh --autonomous "Long Run"      # v3 autonomous mode (opt-in): .mode + nonce + auto-attest
11#   ./init-session.sh --gated "Gated Run"          # v3 gated mode (opt-in, implies autonomous): adds Stop-gate marker
12#   ./init-session.sh --autonomous                 # v3 flags also work in legacy root mode (dotfiles at root)
13#
14# Legacy mode (zero positional args, no --plan-dir) preserves v1.x behavior so
15# upgrades stay non-breaking. Slug mode addresses parallel multi-task isolation
16# (issue #148) by writing each plan under .planning/<date>-<slug>/ and pinning
17# .planning/.active_plan so resolve-plan-dir.sh can find it.
18#
19# v3 modes (opt-in): --autonomous / --gated write a .mode marker next to the
20# plan, reset the .stop_blocks gate counter, clear any stale gate ledger, write
21# a fresh nonce for delimiter framing, and auto-attest the plan. With NO v3 flag
22# and no .mode file, behavior is byte-equivalent to v2.43.0 (no .mode, no nonce,
23# no attestation change).
24 
25set -e
26 
27TEMPLATE="default"
28PROJECT_NAME=""
29USE_PLAN_DIR=0
30MODE=""
31 
32while [ $# -gt 0 ]; do
33    case "$1" in
34        --template|-t)
35            TEMPLATE="$2"
36            shift 2
37            ;;
38        --plan-dir)
39            USE_PLAN_DIR=1
40            shift
41            ;;
42        --autonomous)
43            # autonomous wins only if --gated hasn't already been set (gated
44            # implies autonomous and is the stronger marker).
45            if [ "$MODE" != "gated" ]; then
46                MODE="autonomous"
47            fi
48            shift
49            ;;
50        --gated)
51            MODE="gated"
52            shift
53            ;;
54        *)
55            if [ -z "$PROJECT_NAME" ]; then
56                PROJECT_NAME="$1"
57            else
58                PROJECT_NAME="$PROJECT_NAME $1"
59            fi
60            shift
61            ;;
62    esac
63done
64 
65DATE=$(date +%Y-%m-%d)
66 
67SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
68SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
69TEMPLATE_DIR="$SKILL_ROOT/templates"
70 
71if [ "$TEMPLATE" != "default" ] && [ "$TEMPLATE" != "analytics" ]; then
72    echo "Unknown template: $TEMPLATE (available: default, analytics). Using default."
73    TEMPLATE="default"
74fi
75 
76# Slug mode triggers when a project name was given OR --plan-dir was passed.
77SLUG_MODE=0
78if [ -n "$PROJECT_NAME" ] || [ "$USE_PLAN_DIR" -eq 1 ]; then
79    SLUG_MODE=1
80fi
81 
82slugify() {
83    # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
84    printf '%s' "$1" \
85        | tr '[:upper:]' '[:lower:]' \
86        | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
87        | cut -c1-40
88}
89 
90short_uuid() {
91    # Probe each candidate: command -v alone is not enough on Windows because
92    # App Execution Aliases report presence but exit non-zero when run.
93    _py="${PYTHON_BIN:-}"
94    if [ -z "$_py" ]; then
95        for _c in python3 python py; do
96            if command -v "$_c" >/dev/null 2>&1 && "$_c" -c "import uuid" >/dev/null 2>&1; then
97                _py="$_c"
98                break
99            fi
100        done
101    fi
102    if [ -n "$_py" ]; then
103        "$_py" -c "import uuid; print(uuid.uuid4().hex[:8])"
104        return
105    fi
106    if command -v uuidgen >/dev/null 2>&1; then
107        uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-' | cut -c1-8
108        return
109    fi
110    # Last-ditch: seconds timestamp as 8 hex chars
111    printf '%08x' "$(date +%s)" | cut -c1-8
112}
113 
114gen_nonce() {
115    # 16 hex chars for the plan-data delimiter framing (security strand rec 8).
116    # short_uuid() yields 8 hex chars; concatenate two draws and clip to 16 so
117    # the result stays exactly 16 even if a fallback path over-produces.
118    _n1="$(short_uuid)"
119    _n2="$(short_uuid)"
120    # short_uuid's third-level fallback is printf '%08x' "$(date +%s)" with
121    # 1-second resolution: two draws in the same second return the SAME 8 hex,
122    # collapsing the nonce to the epoch value doubled (32 bits, not 64). When
123    # the halves match, mix the PID into the second half so the nonce keeps 64
124    # bits of unpredictability on the no-uuid fallback path (Alpine/minimal).
125    if [ "$_n1" = "$_n2" ]; then
126        printf '%08x%08x' "$(date +%s)" "$$" | tr -d '\n' | cut -c1-16
127    else
128        printf '%s%s' "$_n1" "$_n2" | tr -d '\n' | cut -c1-16
129    fi
130}
131 
132# Apply v3 opt-in mode side effects to a plan directory.
133#   $1 = plan dir (absolute or relative); dotfiles live directly inside it.
134#   $2 = plan file path (task_plan.md) used for auto-attestation resolution.
135# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
136apply_v3_mode() {
137    _mode_dir="$1"
138    _mode_plan="$2"
139    [ -z "$MODE" ] && return 0
140 
141    # (a) reset the gate block counter and drop any stale gate ledger so a prior
142    #     run's high block count cannot let the next run stop instantly.
143    printf '0\n' > "${_mode_dir}/.stop_blocks"
144    rm -f "${_mode_dir}/.gate_last_ledger" 2>/dev/null || true
145 
146    # (b) write a fresh 16-hex nonce for delimiter framing.
147    gen_nonce > "${_mode_dir}/.nonce"
148 
149    # write the mode marker. gated implies autonomous, so it carries both tokens.
150    if [ "$MODE" = "gated" ]; then
151        printf 'autonomous gate\n' > "${_mode_dir}/.mode"
152    else
153        printf 'autonomous\n' > "${_mode_dir}/.mode"
154    fi
155 
156    # (c) auto-attest the plan (attestation default-on in v3 modes, security
157    #     strand rec 1). attest-plan.sh resolves the same way init-session just
158    #     pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
159    #     mode it is empty and the script falls back to ./task_plan.md at root.
160    #     Run from the project root (CWD here) so both resolutions land.
161    _attest="${SCRIPT_DIR}/attest-plan.sh"
162    if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
163        PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
164    fi
165}
166 
167write_default_task_plan() {
168    cat > "$1" << 'EOF'
169# Task Plan: [Brief Description]
170 
171## Goal
172[One sentence describing the end state]
173 
174## Current Phase
175Phase 1
176 
177## Phases
178 
179### Phase 1: Requirements & Discovery
180- [ ] Understand user intent
181- [ ] Identify constraints
182- [ ] Document in findings.md
183- **Status:** in_progress
184 
185### Phase 2: Planning & Structure
186- [ ] Define approach
187- [ ] Create project structure
188- **Status:** pending
189 
190### Phase 3: Implementation
191- [ ] Execute the plan
192- [ ] Write to files before executing
193- **Status:** pending
194 
195### Phase 4: Testing & Verification
196- [ ] Verify requirements met
197- [ ] Document test results
198- **Status:** pending
199 
200### Phase 5: Delivery
201- [ ] Review outputs
202- [ ] Deliver to user
203- **Status:** pending
204 
205## Decisions Made
206| Decision | Rationale |
207|----------|-----------|
208 
209## Errors Encountered
210| Error | Resolution |
211|-------|------------|
212EOF
213}
214 
215write_default_findings() {
216    cat > "$1" << 'EOF'
217# Findings & Decisions
218 
219## Requirements
220-
221 
222## Research Findings
223-
224 
225## Technical Decisions
226| Decision | Rationale |
227|----------|-----------|
228 
229## Issues Encountered
230| Issue | Resolution |
231|-------|------------|
232 
233## Resources
234-
235EOF
236}
237 
238write_default_progress() {
239    local date_value="$1"
240    local target="$2"
241    cat > "$target" << EOF
242# Progress Log
243 
244## Session: $date_value
245 
246### Current Status
247- **Phase:** 1 - Requirements & Discovery
248- **Started:** $date_value
249 
250### Actions Taken
251-
252 
253### Test Results
254| Test | Expected | Actual | Status |
255|------|----------|--------|--------|
256 
257### Errors
258| Error | Resolution |
259|-------|------------|
260EOF
261}
262 
263write_analytics_progress() {
264    local date_value="$1"
265    local target="$2"
266    cat > "$target" << EOF
267# Progress Log
268 
269## Session: $date_value
270 
271### Current Status
272- **Phase:** 1 - Data Discovery
273- **Started:** $date_value
274 
275### Actions Taken
276-
277 
278### Query Log
279| Query | Result Summary | Interpretation |
280|-------|---------------|----------------|
281 
282### Errors
283| Error | Resolution |
284|-------|------------|
285EOF
286}
287 
288create_files_in() {
289    local target_dir="$1"
290    local plan_path="$target_dir/task_plan.md"
291    local findings_path="$target_dir/findings.md"
292    local progress_path="$target_dir/progress.md"
293 
294    if [ ! -f "$plan_path" ]; then
295        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_task_plan.md" ]; then
296            cp "$TEMPLATE_DIR/analytics_task_plan.md" "$plan_path"
297        else
298            write_default_task_plan "$plan_path"
299        fi
300        echo "Created $plan_path"
301    else
302        echo "$plan_path already exists, skipping"
303    fi
304 
305    if [ ! -f "$findings_path" ]; then
306        if [ "$TEMPLATE" = "analytics" ] && [ -f "$TEMPLATE_DIR/analytics_findings.md" ]; then
307            cp "$TEMPLATE_DIR/analytics_findings.md" "$findings_path"
308        else
309            write_default_findings "$findings_path"
310        fi
311        echo "Created $findings_path"
312    else
313        echo "$findings_path already exists, skipping"
314    fi
315 
316    if [ ! -f "$progress_path" ]; then
317        if [ "$TEMPLATE" = "analytics" ]; then
318            write_analytics_progress "$DATE" "$progress_path"
319        else
320            write_default_progress "$DATE" "$progress_path"
321        fi
322        echo "Created $progress_path"
323    else
324        echo "$progress_path already exists, skipping"
325    fi
326}
327 
328if [ "$SLUG_MODE" -eq 1 ]; then
329    SLUG="$(slugify "$PROJECT_NAME")"
330    if [ -z "$SLUG" ]; then
331        SLUG="untitled-$(short_uuid)"
332    fi
333    BASE_ID="${DATE}-${SLUG}"
334    PLAN_ID="$BASE_ID"
335    PLAN_ROOT="${PWD}/.planning"
336    counter=2
337    while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
338        PLAN_ID="${BASE_ID}-${counter}"
339        counter=$((counter + 1))
340    done
341    PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
342    mkdir -p "$PLAN_DIR"
343 
344    echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
345    echo "PLAN_ID=$PLAN_ID"
346    create_files_in "$PLAN_DIR"
347    printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
348    apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
349    echo ""
350    echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
351    echo "Pin this terminal to the plan for parallel sessions:"
352    echo "  export PLAN_ID=$PLAN_ID"
353    if [ -n "$MODE" ]; then
354        echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
355    fi
356else
357    PROJECT_NAME="${PROJECT_NAME:-project}"
358    echo "Initializing planning files for: $PROJECT_NAME (template: $TEMPLATE)"
359    create_files_in "$(pwd)"
360    apply_v3_mode "$(pwd)" "$(pwd)/task_plan.md"
361    echo ""
362    echo "Planning files initialized!"
363    echo "Files: task_plan.md, findings.md, progress.md"
364    if [ -n "$MODE" ]; then
365        echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
366    fi
367fi
368