feat: implement git commit context tracing (ctx trace)

[parlakisik]

Link every git commit back to the decisions, tasks, learnings, and sessions that motivated it. git log shows what changed, git blame shows who — ctx trace shows why.

Embed context pointers in git commit trailers via a prepare-commit-msg hook. A new ctx trace command resolves those pointers back to the original reasoning.

New CLI commands:

• ctx trace [commit] show context for a specific commit
• ctx trace --last N show recent commits with context
• ctx trace --json machine-readable JSON output
• ctx trace file show context trail for a file
• ctx trace tag manually tag a commit with --note
• ctx trace hook enable install prepare-commit-msg hook
• ctx trace hook disable remove the hook

Three-source context detection:

1. Pending: refs accumulated from ctx add and ctx task complete
2. Staged: new entries detected in staged .context/ file diffs
3. Working state: in-progress tasks and CTX_SESSION_ID env var

Storage:
.context/state/pending-context.jsonl accumulated refs, cleared per commit
.context/trace/history.jsonl permanent commit-to-context map
.context/trace/overrides.jsonl manual tags from ctx trace tag

[cloudflare-workers-and-pages]

Deploying ctx with    Cloudflare Pages

Latest commit:	8655f26
Status:	✅  Deploy successful!
Preview URL:	https://29840438.ctx-bhl.pages.dev
Branch Preview URL:	https://feature-commit-context-traci.ctx-bhl.pages.dev

View logs

[josealekhine]

solid, well-structured feature. Murat clearly understands the codebase conventions. The PR is ready for merge with minor nits.

What looks good

• Architecture: Clean separation — internal/trace/ is a pure library (types, JSONL, git helpers, resolve), internal/cli/trace/ is the CLI wiring. Follows the existing cmd/ + core/
  pattern used elsewhere.
• Three-source collection model (pending, staged, working) is well thought out. Deduplication across sources is handled correctly.
• JSONL storage with generic readJSONL[T]/appendJSONL[T] helpers — clean and reusable.
• Git hook design: Two-hook approach (prepare-commit-msg injects trailer, post-commit records to history) avoids the pitfall of recording before the commit succeeds. Non-ctx hooks are
  detected and left alone.
• Test coverage: Tests for pending, history, overrides, collect, resolve, staged, working, plus an integration test in trace_test.go. Good edge cases (empty, missing file, short hash
  matching, dedup).
• Docs: docs/cli/trace.md and workflow docs updated. Commands.yaml entries present.
• Lint cleanup: The fmt.Fprintf(&sb, ...) migration from sb.WriteString(fmt.Sprintf(...)) is a nice QF1012 fix — reduces allocations. The gosec G703 nolint annotations are properly
  justified.

Some Nits That I will Address Separately (not merge blockers)

1. Complete() return value change — adding a third return value (int) to Complete() is a breaking change to the internal API. The MCP handler call sites were updated (good), but anyone
   calling Complete() externally will break. Worth a note in the commit message that this is an internal-only function.
2. ctx add always records as deps: Bump actions/checkout from 4 to 6 #1 — In add/cmd/root/run.go:80, new decisions/learnings are assumed to be deps: Bump actions/checkout from 4 to 6 #1 because they're prepended. This is fragile if the prepend logic ever changes. A
   comment explaining why is there, but it's a coupling to watch.
3. RecordCommit reads trailer then truncates pending — If the trailer is empty (e.g. user committed outside the hook), pending refs are silently discarded. This seems intentional but
   worth documenting that pending context is always consumed per-commit, even when no hook runs.
4. ParsePathArg handles file.go:42-60 but not Windows paths with drive letters like C:\foo. Probably fine for a unix-first tool, just noting it.
5. ShowLast iterates git log twice (once for the table, once internally per commit via CollectRefsForCommit which reads trailers). For --last 50 this could be slow since each commit
   spawns a git log -1 subprocess. The includeTrailers: true flag in ShowCommit vs false in TraceFile is a good optimization, but ShowLast uses true.
   about ensuring ctx is in PATH.

Verdict

Good to merge. The feature is self-contained, well-tested, follows project conventions, and the docs are complete. The nits above are all minor — none are blockers.

[parlakisik]

/test

[josealekhine]

🌮 .