Changelog

Copied from the repo’s CHANGELOG.md, which is generated by just release using timbers draft changelog | claude -p --model opus. Changelog All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. 0.21.0 - 2026-05-17 Changed Scoped the post-commit pending-work gate to the first-parent line so parallel agents sharing .timbers/ no longer block each other on undocumented commits from sibling branches. Added Added TIMBERS_SKIP_CROSS_AGENT_DEBT environment variable as an escape hatch for cases where a merge commit on the first-parent line touched source files (e.g. conflict resolution). 0.20.1 - 2026-05-10 Fixed Fixed post-commit hook nudging users to document commits that timbers log would refuse (e.g. .beads/issues.jsonl-only commits), by routing both pre-commit and post-commit hooks through a shared actionable-pending check. 0.20.0 - 2026-05-07 Added Added .timbersignore support, expanded skip-rule configurability, and a revert auto-skip behavior to relax enforcement on a per-repo basis (v0.19.0 batch). Added a PR-authoring nudge to timbers prime output. Changed BREAKING: timbers prime now emits compact session-start output by default; the full operating guide moved behind --full/guide. Run timbers prime --full (or update Claude hooks to use the new hook mode) to restore prior verbosity. Compact timbers prime now prints full tb_<ts>_<sha> entry IDs (resolvable by timbers show), surfaces a hint when PRIME.md overrides workflow content, and aligns health-line truncation to 96 chars to match entries. timbers prime --json now honors the requested mode (no longer hardcoded to compact) and exposes a custom_workflow field when PRIME.md is present. Aligned stale-anchor prime output with pending for consistent reporting. Sharpened all seven built-in draft templates with anti-fabrication guards (v0.19.0 batch). Refreshed Anthropic, OpenAI, and Gemini provider model aliases to current official IDs; corrected Gemini Flash-Lite to the stable 3.1 model. Surfaced status visibility improvements (v0.19.0 batch). Internal Dropped the unused Dolt remote in favor of the embedded JSONL transport; AGENTS.md now documents the single sync channel, JSONL drift-recovery via bd export | diff, and removes bd dolt push from the session-close workflow. Replaced the minimal agent note with the full operating guide and made CLAUDE.md a symlink to AGENTS.md to reduce drift across agent environments. 0.19.0 - 2026-05-02 Added Added per-repo .timbersignore at the repo root that extends the built-in skip-rule set with prefix, exact-path, and suffix patterns for housekeeping files like vendor/ and *.lock. Added auto-skip for revert commits whose original SHA is already documented in an existing entry, avoiding ledger noise for revert-of-documented work. Added infra_skipped_since_entry to timbers status --json and a matching line in timbers status --verbose to surface how many commits were skipped since the latest entry. Changed Expanded the default skip-rule set to relax pending checks on housekeeping files (.gitignore, .editorconfig, narrowly-scoped .github/ metadata) and added default suffix skips for major-ecosystem lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, go.sum, Cargo.lock, Gemfile.lock); manifest changes (package.json, go.mod, Cargo.toml) remain pending. Fixed an exact-path matching bug where .gitignore would incorrectly match .gitignores due to prefix-only comparison. Tuned the seven built-in draft templates (changelog, decision-log, devblog, pr-description, release-notes, sprint-report, standup) for artifact-appropriate signal — including ADR Status/Date/supersession fields, changelog Added-vs-Changed disambiguation and consolidation rules, PR-description size adaptation and test-plan honesty, release-notes user-observable filtering with breaking-change migration hints, and devblog operator/collaborator voice with anti-fabrication guards. Coached timbers prime to nudge agents toward operator-voice in narrative drafts and to draft PR bodies from ledger entries via the pr-description template by default when entries cover the branch range. Refined six templates after second-opinion review to harden them against soft fabrication (emotion, theme, vague benefit) while preserving literary scaffolding. 0.18.0 - 2026-04-29 Fixed Renamed ledger files to drop colons from filenames so go install ...@latest works on tagged versions; colons in .timbers/*.json broke Go’s module zip format and proxy. Added IDToFilename and FilenameToID helpers that flip HH:MM:SS separators to dashes for filesystem encoding while preserving canonical ISO 8601 timestamps in entry IDs. FileStorage.MigrateLegacyFilenames for bulk migration of existing entries. timbers doctor --fix support for migrating legacy colon-named ledger files. Changed entryPath now emits canonical dashed filenames; reads transparently fall back to legacyEntryPath for colon-named files written by older binaries. On-write cleanup transparently removes legacy sibling files when canonical names are written. Technical Indefinite backward-compat reads preserved so forks and downstream consumers with older entries don’t need to upgrade in lockstep. Migrated 146 existing entries in this repo to the new dashed filename format. 0.17.0 - 2026-04-20 Added Added --var key=value flag to timbers draft for caller-supplied template variables, namespaced under {{vars.key}} to avoid shadowing built-ins. Added vars: map to template frontmatter for per-template default variables, applied after caller-supplied vars. Added durable ADR numbering to the decision-log template via {{vars.starting_number}}, with caller-owned offset for stable identifiers across regenerations. Added just decision-log recipe that derives the next ADR number by grepping the target file and passes it via --var. Changed Hardened parseVars with a duplicate-key check to prevent silent last-wins behavior under scripting. Changed the just decision-log pipeline to use || echo "" inside the command substitution for unambiguous empty-file and no-match handling under pipefail. Technical Extracted prepareRender helper in runDraftRender to stay under the cyclop complexity limit. Threaded caller variables through RenderContext.Vars, substituted after built-in tokens in internal/draft/render.go; unknown keys remain literal. 0.16.5 - 2026-03-31 Changed Upgraded beads to 0.63.3, replacing Dolt push/pull sync with auto-flush to .beads/issues.jsonl for simpler git-native sync Fixed Fixed timbers-on-timbers loop caused by .beads/issues.jsonl appearing in pending commits after beads auto-stage hook Broadened isLedgerOnlyCommit to isInfrastructureOnlyCommit with configurable prefix list (.timbers/, .beads/) 0.16.4 - 2026-03-31 Added Added How It Works section to README covering commit design, filter command, and link to design decisions Added design decision documentation explaining why separate commits for ledger entries is by design (council-evaluated, two rounds) Changed Updated README to clarify pre-commit hook enforcement of 1:1 commit cadence and ~2x commit count Added batch mode fallback note to README for graceful degradation when hooks are bypassed Fixed Fixed stale anchor detection to use reachability check (git merge-base --is-ancestor) instead of SHA existence — prevents phantom pending commits after rebase when old objects linger in the object store Fixed pre-commit hook to skip gracefully when .timbers/ directory is absent at worktree root Technical Added IsAncestorOf method to GitOps interface for commit reachability checks Added git merge-base --is-ancestor guard in GetPendingCommits before invoking git log 0.16.3 - 2026-03-28 Fixed Fixed doctor --fix targeting wrong settings scope when cleaning up stale Claude hooks — Detect() found stale hooks in global settings but Install(true) always wrote to project-local, so retired hooks in global settings survived --fix Changed Released v0.16.2 changelog, regenerated site examples, and cleaned leaked LLM commentary from prior release notes 0.16.2 - 2026-03-28 Fixed Fixed hook deadlock during rebase, merge, cherry-pick, and revert where agents were blocked by pending-commit checks and couldn’t log or continue Fixed --range silently dropping entries when only some anchor commits were stale; v0.15.3 fallback only triggered on zero anchor matches, missing the partial-stale case Technical Added git.IsInteractiveGitOp() that detects in-progress interactive git operations by checking .git state files; all hooks early-return during these operations Changed --range entry discovery to run both anchor-based and diff-based discovery unconditionally and union results by entry ID 0.16.0 - 2026-03-23 Fixed Fixed query --range returning empty results after squash merge, where entry anchor_commit SHAs from feature branches disappear from main history Added fallback discovery via git diff --name-only when commit-ancestry matching finds zero entries in a range Technical Added DiffNameOnly to GitOps interface to support file-based entry discovery in getEntriesByRange 0.15.3 - 2026-03-22 Fixed Fixed query --range returning empty results after squash merge by falling back to file-based entry discovery when anchor commit SHAs are no longer in main’s history 0.14.4 - 2026-03-05 Fixed Respected core.hooksPath git config for hook installation instead of hardcoding .git/hooks/, fixing compatibility with tools like beads that set a custom hooks directory Updated GeneratePreCommitHook to accept a dynamic hooksDir parameter for correct --chain backup paths 0.14.3 - 2026-03-05 Fixed Fixed chained pre-commit hook silently overriding timbers exit code, allowing commits to succeed even when pending entries should have blocked them 0.14.2 - 2026-03-05 Fixed Expanded stop hook reason to include full timbers log syntax with --why/--how flags so agents receive an actionable command instead of a bare timbers log that would fail 0.14.0 - 2026-03-04 Changed Simplified hook enforcement by dropping PreToolUse handler in favor of pre-commit blocking, which works universally across all git clients Kept Stop hook as a session-end backstop for agents that bypass pre-commit Updated hooks install help text from “warns” to “blocks” to reflect actual behavior Fixed Fixed uninstall leaving retired hooks (PostToolUse, PreToolUse) in settings by adding retiredEvents cleanup loop Removed Removed PreToolUse handler, dispatch case, and associated tests from hook enforcement 0.13.2 - 2026-03-03 Fixed Fixed timbers log hard-erroring on stale anchor after squash merge, now warns and proceeds with fallback commits Fixed timbers log --batch treating ErrStaleAnchor as fatal, matching the graceful degradation already used by pending, prime, and MCP 0.13.1 - 2026-03-03 Added Added quick health check to timbers prime output that surfaces missing hooks and integration issues at session start runQuickHealthCheck validates post-commit hook and agent environment, displaying a Health section with doctor --fix hint when issues are found 0.13.0 - 2026-03-02 Added Added timbers hook run post-commit command that prints a one-line reminder to run timbers log after commits Added timbers init --hooks flag to install the post-commit git hook Added timbers doctor check for post-commit hook presence, with --fix to auto-install it Fixed Fixed slice capacity mismatch (5→6) in post-commit hook setup Added missing IsRepo guard to prevent hook operations outside git repositories Technical Added unit tests for hook Generate, Check, and Install functions Added integration tests for init --hooks post-commit workflow 0.12.2 - 2026-03-02 Fixed Fixed timbers pending treating all pre-timbers commit history as undocumented work in new installations Fixed timbers doctor reporting false warnings about pending commits when no ledger entries exist yet Changed timbers pending and timbers doctor now detect first-use state (no entries) at the display layer and show a friendly onboarding message instead of listing every historical commit Added status field to timbers pending --json output to distinguish pending, clean, and no_entries states timbers init now suggests running timbers log --batch to document recent work as a catchup tip 0.12.1 - 2026-02-28 Added Added LLM output sanitization (SanitizeLLMOutput()) to strip thought-process leakage from --model output, plus “output discipline” prompting added to all 7 built-in templates Added notes field to site landing page marketing content Added static example generation for dense date ranges to avoid redundant LLM calls on every release Changed Replaced auth examples with cursor-based pagination examples across README and landing page Split site example generation into dynamic (per-release) and static (fixed date range) justfile recipes Parallelized site example generation Replaced declare -A with parallel arrays in example recipes for macOS bash 3.2 compatibility Updated standup examples to use --since 1d Bumped go-sdk to v1.3.1 for CVE-2026-27896 (case-insensitive JSON parsing) Fixed Removed leaked LLM commentary and duplicate sections from CHANGELOG.md and site examples 0.12.0 - 2026-02-28 Added Added --models flag to timbers draft to list supported LLM providers, model aliases, and required API keys Added --json support for timbers draft --models for agent consumption Added internal/llm package with provider metadata and alias resolution Changed Updated README, tutorial, and docs/llm-commands.md with verified piping syntax for all three supported LLM CLIs (claude, gemini, codex) Fixed Fixed Codex CLI flag placement in docs — -m belongs to codex exec, not the root codex command Fixed release dirty-tree check to exclude CHANGELOG.md and site/content/examples/ (outputs of the release process) Fixed release recipe to skip already-modified site examples, avoiding redundant LLM calls on partial reruns Fixed defensive alias copy in ProviderInfos() using maps.Copy to prevent callers from mutating package state 0.11.0 - 2026-02-27 Added Added govulncheck as a Go tool dependency with just vulncheck recipe for vulnerability scanning Added automatic landing page version update during just release Added generation capability check to timbers doctor with CLI/API key detection via llm.APIKeyEnvVars() Added just examples recipe to justfile Changed Renamed exec-summary template to standup for better discoverability Rewrote pr-description template (v4) to focus on intent and decisions rather than diff review Updated prime workflow coaching to recommend pipe-first generation defaults for subscription users Fixed Fixed devblog workflow generating empty “apology” posts when no entries exist by adding entry count check before LLM invocation Fixed terminal colors invisible on dark backgrounds (e.g., Solarized Dark) by replacing hardcoded lipgloss.Color with AdaptiveColor across all output formatting 0.10.2 - 2026-02-26 Fixed Fixed timbers prime treating stale anchor as fatal error after squash merges — now handles ErrStaleAnchor gracefully like pending and MCP already do Improved stale anchor warning messages in CLI and MCP to be actionable: explains that squash-merged branches with timbers entries are already documented, advises against catch-up logging, and notes that the anchor self-heals on next timbers log Synced MCP defaultWorkflowContent with CLI version — MCP had a stale 4-line checklist instead of the full coaching content Added Added <stale-anchor> coaching section to prime workflow, guiding agents through the correct response when anchor commits are missing from history after squash merges 0.10.1 - 2026-02-16 Changed Regenerated site examples and devblog from 69-entry ledger, replacing stale content from v0.9.0 Added provenance note to agent DX guide subtitle crediting pattern origins Updated landing page to v0.10.0 with terminal indentation fix Fixed Removed PostToolUse hook that fired but whose stdout was not surfaced by Claude Code — Stop hook already covers the same case via timbers pending at session end Technical Added retired event cleanup list for graceful hook removal on upgrade 0.10.0 - 2026-02-14 Added Added --color flag (never/auto/always) as a global persistent flag for terminal color control, fixing invisible text on Solarized Dark and other non-standard themes — all NewPrinter call sites plumbed through useColor(cmd) Added auto-commit in timbers log — entry files are now staged and committed atomically using git commit -m "timbers: document <id>" -- <path>, eliminating the gap where .timbers/*.json files were staged but never committed Added <content-safety> coaching section to prime workflow warning agents not to include PII, secrets, or sensitive data in ledger entries Added marketing landing page for Hugo site homepage with dark theme, terminal-styled code blocks, and GSAP ScrollTrigger animations Fixed Fixed PostToolUse hook to read JSON from stdin instead of empty $TOOL_INPUT environment variable, which was always empty and made the post-commit reminder a no-op since creation Fixed landing page terminal block alignment, continuation indentation, and quick start container width Technical Added legacy hook detection and upgrade logic via hasExactHookCommand and removeTimbersHooksFromEvent for replacing stale hooks automatically Added daily devblog automation at 9am UTC with workflow_dispatch chain to pages deploy 0.9.0 - 2026-02-13 Changed Rewrote agent coaching text with motivated rules — each instruction now explains why it exists, enabling models to generalize correctly instead of overtriggering on imperative language Replaced 11 instances of MUST/CRITICAL/MANDATORY with calm, motivated framing — when everything is critical, nothing is Replaced vague --notes guidance (“use when you made a real choice”) with concrete 5-point trigger criteria: 2+ approaches evaluated, obvious approach rejected, surprise encountered, future lock-in, non-obvious to teammates Structured coaching with XML section tags (<protocol>, <why-coaching>, <notes-coaching>, <commands>) for cleaner model parsing Deleted redundant “Core Rules (MANDATORY)” block that restated instructions already covered above Updated tutorial: added decision-log to template list, recommended install script over go install, updated model recommendations to recommend opus for quality content Fixed Fixed Hugo site baseURL from rbergman.github.io to gorewood.github.io after org migration Fixed devblog CI workflow failing on stale git fetch refs/notes/timbers — timbers uses .timbers/ directory storage, not git notes Fixed devblog posts not triggering site rebuild — GITHUB_TOKEN pushes don’t fire on:push workflows, added explicit workflow_dispatch chain from devblog to pages workflow Technical Switched devblog CI from weekly to daily schedule (9am UTC, --since 1d) Regenerated all site example artifacts from 55 real ledger entries with notes, replacing old 30-entry backfilled set 0.8.0 - 2026-02-13 Added Added --notes flag to timbers log for capturing deliberation context — the journey to a decision, distinct from --why which captures the verdict Added notes coaching to prime output with BAD/GOOD examples teaching “thinking out loud” style over mechanical summaries Added AgentEnv interface with registry pattern for agent-environment-neutral integrations, enabling single-file additions for new agent environments (Gemini, Cursor, Windsurf, Codex) Added ClaudeEnv as reference implementation of AgentEnv, wrapping existing Claude Code setup/teardown functions Changed Refactored init, doctor, setup, and uninstall commands to iterate AllAgentEnvs() instead of hardcoding Claude-specific logic Replaced --no-claude flag with generic --no-agent (deprecated alias preserved for backward compatibility) Tightened --why coaching to explicitly differentiate from --notes: why is the verdict, notes is the journey Preserved backward-compatible JSON keys (claude_installed, claude_removed) while generalizing step names and flags Fixed Fixed TestCommitFiles to use an isolated temp repo instead of live HEAD, which fails on merge commits where diff-tree returns empty Fixed TestRepoRoot to be worktree-compatible by replacing hardcoded directory name assertion with absolute path check Technical Extracted defaultWorkflowContent to prime_workflow.go to stay under 350-line file-length lint limit Extracted outputPrimeRecentWork from outputPrimeHuman to stay under cognitive complexity limit of 15 Added AgentEnvState slice pattern for uninstall to gather and remove all detected environments 0.7.0 - 2026-02-12 Added Added MCP server with 6 tools (pending, prime, query, show, status, log) over stdio transport via timbers serve subcommand, enabling integration with Claude Code, Cursor, Windsurf, Gemini CLI, and other MCP-compatible editors Added idempotentHint annotation to MCP read tools, allowing clients to optimize with caching and retry logic Changed Updated timbers onboard snippet with command -v guard and install URL for graceful degradation when timbers is not installed Replaced all git notes references across documentation with .timbers/ file-based storage Fixed Filtered ledger-only commits from GetPendingCommits to resolve chicken-and-egg problem where .timbers/ entry commits were always reported as undocumented Technical Moved filter functions to internal/ledger/ for sharing between CLI and MCP server Added git.CommitFiles() using diff-tree and expanded GitOps interface with isLedgerOnlyCommit helper Added validateLogInput to catch empty strings that the MCP SDK’s required-field check does not 0.6.0 - 2026-02-11 Changed Pivoted storage from git notes to flat directory files (.timbers/<id>.json), enabling atomic writes and eliminating merge conflicts in concurrent worktrees Simplified GitOps interface from 8 methods to 4 (HEAD, Log, CommitsReachableFrom, GetDiffstat) Adopted YYYY/MM/DD directory layout for .timbers/ entries to scale beyond flat-directory limits at high commit volumes Replaced ReadDir with WalkDir for recursive entry discovery across date-bucketed directories Rewrote uninstall command to clean up .timbers/ directory with recursive cleanup Removed Removed all git notes code and references (notes.go, notes_configured, remote_config fields, timbers notes push/fetch commands) Technical Migrated 37 existing ledger entries from git notes to .timbers/ flat files Extracted atomicWrite helper using temp-file-plus-rename pattern for crash-safe writes Added 14 integration tests proving file-per-entry storage is inherently merge-safe across branches 0.5.0 - 2026-02-11 Added Multi-event Claude Code hooks covering the full session lifecycle: SessionStart, PreCompact, Stop, and PostToolUse Upgrade path that preserves existing hooks when adding new reinforcement points Changed Expanded hook configuration from single SessionStart hook to four reinforcement points, addressing 0% compliance for undocumented commits with single-hook approach Generalized hook management via timbersHookConfig slice with addTimbersHooks/removeTimbersHooks functions 0.4.0 - 2026-02-10 Changed Rewrote Claude Code hook integration from shell scripts to JSON settings, fixing session-start context injection that previously had 0% adoption due to format mismatch Renamed internal/prompt package to internal/draft to match the draft command name Updated agent DX guide with v0.3+ learnings, JSON hook format documentation, and shell-script anti-pattern section Fixed Added graceful degradation when timbers is not installed — Claude Code hook now warns with install URL instead of erroring, unblocking adoption for team members without timbers Added isTimbersPrimeCommand() for backward-compatible detection of both legacy shell-script and new JSON hook formats Removed Removed legacy .claude/hooks/user_prompt_submit.sh shell script hook in favor of JSON settings Removed history/ artifacts from version control 0.3.0 - 2026-02-10 Added Added git.InitNotesRef() to create an empty notes namespace during init, so prime works immediately without requiring a manual first note Added tests for the prime guard silent-exit path and doctor --fix auto-install path Added TTY-aware lipgloss style sets to doctor and init output, following the existing uninstall pattern Added NotesRefExists guard to prime to prevent no-op runs in uninitialized repos Changed Switched Claude hooks from global to project-level by default; global install is now behind the --global flag Changed git hooks from default-on (--no-hooks to skip) to opt-in (--hooks to enable), avoiding conflicts with tools like beads that rely on pre-commit Renamed warn style to skip in init output styles for consistency Renamed gpt-5 model alias to gpt Updated agent-dx-guide documentation to reflect opt-in hooks and project-level defaults 0.2.0 - 2026-02-10 Added Added --tag filtering to timbers query command with OR semantics, supporting both repeated flags and comma-separated values Added timbers changelog command that generates markdown changelogs from ledger entries, grouped by tag Added timbers draft command (renamed from prompt) for document generation, with decision-log template in ADR format Added .env.local support for API keys via new internal/envfile package, loaded as fallback in root PersistentPreRunE Added cross-platform config directory support via new internal/config package with Dir() function, respecting TIMBERS_CONFIG_HOME, XDG_CONFIG_HOME, and Windows AppData Added CONFIG section to doctor command with checks for config dir, env files, API keys, and templates Added version check to doctor that queries GitHub releases API with graceful failure for dev builds and network errors Added draft status hint and stderr routing for errors/warnings when stdout is piped via output.Printer WithStderr() Added goreleaser configuration, GitHub Actions release workflow, and install.sh with checksum verification Added robustness for non-timbers git notes with ErrNotTimbersNote, schema validation, and ListEntriesWithStats() Added Configuration section to README documenting env file resolution, API key setup, and custom templates Added Installation section to README with curl|bash and go install methods Added MIT LICENSE, CONTRIBUTING.md, and CI workflow for test and lint Changed Renamed prompt command to draft and propagated rename across docs, justfile, and CI Surfaced draft command in prime output under a new Generating Documents section Rewrote README for open-source audience with badges and dogfood caveat Updated agent DX guide with v0.2 learnings Fixed org owner references from rbergman to gorewood in goreleaser and install script Fixed Fixed global state issue in status.go by switching to closure pattern Fixed amend.go output inconsistency Fixed uninstall.go icon usage Fixed ListTemplates override bug Fixed piped output corruption caused by errors and warnings being written to stdout instead of stderr 0.1.0 - 2026-02-10 Initial public release. ...