feat(session-log): /log-session command + 6-field format spec (#114)

## Context

Roadmap **P0.2** from the [2026-04-19 overnight research implementation
roadmap](https://github.com/mojwang/mojwang.tech/blob/main/../../../../../ai/workspace/claude/resources/agentic-research/2026-04-19-implementation-roadmap.md).
Unblocks **P0.3** (\`/grade-session\` retroactive grading) and **P5.1**
(meta-agent) — both need a real log with real rows.

PR #112 shipped documentation for a 5-field cost-log format but never
shipped a writer. This PR ships the writer and extends the format to 6
fields: adds \`agent_sha\` so later analysis can correlate outcomes with
specific agent-prompt versions (P5.1 requirement).

## Format (pipe-separated)

\`\`\`
YYYY-MM-DDTHH:MM:SS | topic | dispatches | models | outcome | agent_sha
\`\`\`

Outcome enum: \`shipped | partial | reverted | blocked | plan-only |
(empty)\`. Empty = "grade later," filled retroactively by
\`/grade-session\` (forthcoming in P0.3).

## Design decisions

- **Slash command + shell script, NOT a Stop hook.** Claude Code's
\`Stop\` hook fires every turn, not session end, so a hook-driven
autolog would misfire on partial turns. One explicit \`/log-session\`
per session is cleaner and gives the user control over
topic/dispatches/models (fields no hook could auto-capture).
- **Timestamp instead of just date** — multiple sessions per day are
common.
- **Auto-captured fields:** timestamp (\`date\`), agent_sha (\`git log\`
on \`.claude/agents/\`).
- **\`--outcome\` sentinel:** \`--outcome \"\"\` explicitly marks
ungraded, skipping the prompt; missing \`--outcome\` prompts
interactively.
- **Pipe-char sanitization:** user fields replace \`|\` with \`;\` so
malformed input doesn't break column parsing.
- **Log file gitignored** — personal state, not a shared artifact.

## Files

- \`scripts/log-session.sh\` — new, executable, \`shellcheck\` clean,
follows \`#!/usr/bin/env bash\` + \`set -euo pipefail\` convention
- \`.claude/commands/log-session.md\` — new slash-command wrapper
- \`docs/CLAUDE_AGENTS.md\` — updated format doc (6 fields, broader
outcome enum, usage example)
- \`.gitignore\` — adds \`scripts/.session-cost.log\`

## Usage

\`\`\`
/log-session --topic \"P0.2 session-logger infra\" --dispatches \"—\"
--models \"sonnet\" --outcome \"shipped\"
\`\`\`

Missing flags prompt interactively.

## Verification

- [x] \`shellcheck scripts/log-session.sh\` — clean
- [x] Happy path: \`--topic … --outcome shipped\` writes a row
- [x] Empty outcome: \`--outcome \"\"\` writes a row with blank 5th
field
- [x] Invalid outcome: \`--outcome bogus\` exits 2 with clear error
- [x] Pipe sanitization: topic containing \`|\` is rewritten as \`;\`
- [x] Gitignored: log file doesn't appear in \`git status\`

## Out of scope (deferred to P0.3)

- \`/grade-session\` retroactive grading (walks ungraded rows)
- \`weekly-review\` command update to surface ungraded sessions
- SessionStart hook nudge (\"N ungraded sessions\")
- Auto-capture of dispatches + models via transcript parsing (Claude
Code doesn't expose transcripts to hooks)

Author: mojwang

.claude/commands/log-session.md

@@ -0,0 +1,39 @@
+---
+description: Append a row to scripts/.session-cost.log capturing this session's directional cost signal (topic, dispatches, models, outcome). Auto-captures timestamp + agent_sha. Outcome can be left empty to grade retroactively via /grade-session.
+allowed-tools: Bash
+---
+
+# Log Session
+
+Run the session logger script, forwarding any user-supplied args:
+
+```
+./scripts/log-session.sh $ARGUMENTS
+```
+
+## Usage
+
+All flags are optional — the script prompts for missing required fields:
+
+```
+/log-session --topic "<one-liner>" --dispatches "<agent x tier or —>" --models "<comma-sep>" --outcome "<enum or empty>"
+```
+
+Example:
+
+```
+/log-session --topic "P0.2 session-logger infra" --dispatches "—" --models "sonnet" --outcome "shipped"
+```
+
+`--outcome ""` is valid — a blank outcome means "grade later." Use `/grade-session` (forthcoming in P0.3) to fill in retroactively.
+
+## Fields
+
+- **topic**: one-line session summary
+- **dispatches**: agent count × tier (e.g. `Explore x3, Plan x1` or `—` for direct work)
+- **models**: comma-separated as provided (e.g. `haiku,sonnet`) — logged as-is, no dedup
+- **outcome**: one of `shipped | partial | reverted | blocked | plan-only` — or empty to grade later
+
+Captured automatically:
+- **timestamp**: ISO 8601 local time
+- **agent_sha**: short SHA of the most recent commit that touched `.claude/agents/` as of logging time (correlates outcomes with prompt versions; reflects end-of-session state if agents were edited mid-session)

.gitignore

@@ -90,3 +90,6 @@ product-brief.md
 
 # Claude Code worktree metadata
 .claude/worktrees/
+
+# Session cost log (populated by /log-session at end of each session)
+scripts/.session-cost.log

docs/CLAUDE_AGENTS.md

@@ -176,20 +176,28 @@ Model routing is enforced via agent frontmatter. Each agent has a `model:` field
 
 ### Session cost log
 
-At session end, append a single line to `scripts/.session-cost.log` (append-only, gitignored, reviewed at weekly review):
+At session end, append a single line to `scripts/.session-cost.log` (append-only, gitignored, reviewed at weekly review). Populated via the `/log-session` slash command, which runs `scripts/log-session.sh`:
 
 ```
-YYYY-MM-DD | <session_topic> | <dispatches> | <models_used> | <outcome>
+YYYY-MM-DDTHH:MM:SS | <session_topic> | <dispatches> | <models_used> | <outcome> | <agent_sha>
 ```
 
-Fields:
-- **date**: ISO date
-- **session_topic**: one-line summary ("/mind aspects Phase 6 B-C-D")
-- **dispatches**: agent count × tier, e.g. `Explore×3, Plan×1, impl×5` or `—` for direct work
-- **models_used**: comma-separated, deduped — `haiku,sonnet` / `sonnet,opus`
-- **outcome**: one-word rollup — `shipped`, `blocked`, `partial`, `plan-only`
+Fields (pipe-separated, six total):
+- **timestamp**: ISO 8601 local time (auto-captured). Use timestamps, not just date — multiple sessions per day are common.
+- **session_topic**: one-line summary ("/mind aspects Phase 6 B-C-D"). User-supplied.
+- **dispatches**: agent count × tier, e.g. `Explore×3, Plan×1, impl×5` or `—` for direct work. User-supplied.
+- **models_used**: comma-separated, user-supplied as-is (e.g. `haiku,sonnet` / `sonnet,opus`). No dedup — the order and count the user types is what gets logged.
+- **outcome**: one of `shipped | partial | reverted | blocked | plan-only`. User-supplied at session end; empty is valid and means "grade later" (fill in retroactively via `/grade-session`).
+- **agent_sha**: short SHA of the most recent commit that touched `.claude/agents/` as of logging time (auto-captured via `git log -1`). Ties a row to a specific agent-prompt version so later analysis can correlate outcomes with prompt changes. Caveat: if agents are edited mid-session, this SHA reflects end-of-session state, not start.
 
-Not exact token counting — Claude Code doesn't expose that. Gives directional cost awareness over time. Patterns emerge at weekly review: "research-heavy sessions cost more than implementation sessions," "sessions with >10 dispatches usually needed Graphite instead of manual stacks."
+Usage:
+```
+/log-session --topic "session summary" --dispatches "Explore×3" --models "haiku,sonnet" --outcome "shipped"
+```
+
+Missing flags are prompted interactively. `--outcome ""` explicitly marks the row ungraded.
+
+Not exact token counting — Claude Code doesn't expose that. Gives directional cost awareness over time. Patterns emerge at weekly review: "research-heavy sessions cost more than implementation sessions," "sessions with >10 dispatches usually needed Graphite instead of manual stacks," "the planner has a higher shipped-rate on SHA X than SHA Y."
 
 See [`STACKED_PRS.md`](./STACKED_PRS.md) for when manual stacking indicates missing tooling.
 

scripts/log-session.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Append a single row to scripts/.session-cost.log capturing this
+# session's directional cost signal (dispatches, models, outcome) plus
+# an agent_sha that ties the row to a specific `.claude/agents/` version.
+#
+# Invoked by the /log-session slash command at end of a session, or
+# directly from the shell. Fields are documented in
+# docs/CLAUDE_AGENTS.md.
+#
+# Roadmap reference: P0.2 from the 2026-04-19 overnight research.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+LOG_PATH="$REPO_ROOT/scripts/.session-cost.log"
+
+TOPIC=""
+DISPATCHES=""
+MODELS=""
+OUTCOME=""
+# Only outcome has a legitimate empty value (grade later via /grade-session).
+# A sentinel lets `--outcome ""` bypass the prompt explicitly; missing
+# --outcome still prompts interactively.
+OUTCOME_SET=0
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [--topic "..."] [--dispatches "..."] [--models "..."] [--outcome "..."]
+
+Appends one row to scripts/.session-cost.log.
+
+Missing required fields are prompted interactively. Outcome is validated
+against the enum: shipped | partial | reverted | blocked | plan-only
+(empty allowed — grade later via /grade-session).
+
+Fields:
+  --topic        One-line session summary (required)
+  --dispatches   Agent count x tier, e.g. "Explore x3, Plan x1" or "—"
+  --models       Comma-separated models used, e.g. "haiku,sonnet"
+  --outcome      One of: shipped | partial | reverted | blocked | plan-only | (empty)
+EOF
+}
+
+# Defense against `--flag` passed with no value (e.g. last arg of the
+# line) or with another flag as its value. Without these guards, `set -u`
+# aborts on `$2` with "unbound variable" — opaque for the user. The
+# short-circuit `$# -lt 2` keeps `$2` from being evaluated when there's
+# only one arg left.
+_require_value() {
+    local flag="$1"; shift
+    if [[ $# -lt 1 || "$1" == -* ]]; then
+        echo "Error: $flag requires a value" >&2
+        usage >&2
+        exit 2
+    fi
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --topic)      _require_value "$1" "${@:2:1}"; TOPIC="$2"; shift 2 ;;
+        --dispatches) _require_value "$1" "${@:2:1}"; DISPATCHES="$2"; shift 2 ;;
+        --models)     _require_value "$1" "${@:2:1}"; MODELS="$2"; shift 2 ;;
+        --outcome)    _require_value "$1" "${@:2:1}"; OUTCOME="$2"; OUTCOME_SET=1; shift 2 ;;
+        -h|--help)    usage; exit 0 ;;
+        *)            echo "Unknown arg: $1" >&2; usage >&2; exit 2 ;;
+    esac
+done
+
+# Prompt for missing required fields. Outcome is optional (grade later).
+if [[ -z "$TOPIC" ]]; then
+    read -r -p "Session topic (one line): " TOPIC
+fi
+if [[ -z "$DISPATCHES" ]]; then
+    read -r -p "Dispatches (e.g. 'Explore x3, Plan x1' or '—'): " DISPATCHES
+fi
+if [[ -z "$MODELS" ]]; then
+    read -r -p "Models used (comma-separated, e.g. 'haiku,sonnet'): " MODELS
+fi
+if [[ $OUTCOME_SET -eq 0 ]]; then
+    read -r -p "Outcome (shipped|partial|reverted|blocked|plan-only, empty = grade later): " OUTCOME
+fi
+
+# Validate outcome enum when non-empty.
+case "$OUTCOME" in
+    ""|shipped|partial|reverted|blocked|plan-only) ;;
+    *)
+        echo "Invalid outcome: '$OUTCOME'" >&2
+        echo "Must be one of: shipped | partial | reverted | blocked | plan-only | (empty)" >&2
+        exit 2
+        ;;
+esac
+
+# Guard against pipe characters in fields — they'd break the pipe-
+# delimited format. Replace with ' ; ' (with spaces) as a deliberately
+# visible sentinel so sanitized rows stand out in any weekly-review
+# listing and prompt a manual cleanup.
+sanitize() {
+    local value="${1//|/ ; }"
+    value="${value//$'\n'/ }"
+    printf '%s' "$value"
+}
+TOPIC=$(sanitize "$TOPIC")
+DISPATCHES=$(sanitize "$DISPATCHES")
+MODELS=$(sanitize "$MODELS")
+
+TIMESTAMP=$(date '+%Y-%m-%dT%H:%M:%S')
+
+# Short SHA of the most recent commit that touched .claude/agents/.
+# Ties a row to a specific agent-prompt version so we can correlate
+# outcomes with prompt changes later (P5.1 meta-agent).
+AGENT_SHA="unknown"
+if command -v git >/dev/null 2>&1 && git -C "$REPO_ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+    sha=$(git -C "$REPO_ROOT" log -1 --format=%h -- .claude/agents/ 2>/dev/null || true)
+    if [[ -n "$sha" ]]; then
+        AGENT_SHA="$sha"
+    fi
+fi
+
+# Ensure the log file exists (gitignored; first run creates it).
+mkdir -p "$(dirname "$LOG_PATH")"
+touch "$LOG_PATH"
+
+ROW="$TIMESTAMP | $TOPIC | $DISPATCHES | $MODELS | $OUTCOME | $AGENT_SHA"
+printf '%s\n' "$ROW" >> "$LOG_PATH"
+
+echo "Logged: $ROW"
+echo "→ $LOG_PATH"