feat(issues): add started_at timestamp (GH#2796) (#3206)

* fix: enable auto-export by default with canonical issues.jsonl name (GH#2973)

Users expected JSONL export to refresh automatically but export.auto
defaulted to false, requiring explicit opt-in. Also the default filename
(export.jsonl) didn't match the canonical issues.jsonl used in docs and
git hooks. Change defaults: export.auto=true, export.path=issues.jsonl,
export.git-add=true so viewers (bv) and git workflows see fresh data
without extra configuration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(init): add auto-export prompt and document export.* config (GH#2973)

Interactive bd init now asks whether to enable auto-export (default: yes).
Users can opt out during setup instead of discovering the setting later.

Also documents the export.* config namespace in bd config --help with
all four keys (export.auto, export.path, export.interval, export.git-add)
and adds export examples.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(issues): add started_at timestamp (GH#2796)

Adds a `started_at` field to issues that is auto-populated when an
issue transitions to in_progress status. Preserved across subsequent
status changes.

- Migration 0027 adds started_at column to issues and wisps tables
- ManageStartedAt() in issueops mirrors ManageClosedAt() pattern
- Query filter support: `started>2026-01-01`, `started<...`
- Displayed in `bd show` between Created and Updated
- Exposed in --json output via struct tag

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: gofmt alignment in update.go and types.go

Amp-Thread-ID: https://ampcode.com/threads/T-019d887d-4eb1-7648-96be-8d906797c382
Co-authored-by: Amp <amp@ampcode.com>

* fix(claim): set started_at when claiming via --claim (GH#2796)

ClaimIssueInTx had its own bespoke UPDATE that only wrote assignee, status,
and updated_at. Since `bd update --claim` is the canonical way agents transition
issues to in_progress, started_at was left NULL in the common case. Set it on
first transition, mirroring ManageStartedAt's guard (preserve existing value on
re-claim).

Also document the `started` field in `bd query --help`.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
matt wilkie 2026-04-14 09:24:08 -07:00 • committed by GitHub
commit f03d4e7fac
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 118 additions and 12 deletions

View file

@ -48,6 +48,7 @@ Supported fields:
notes Search in notes (contains)
created Creation date/time
updated Last update date/time
started Date/time issue first transitioned to in_progress
closed Close date/time
id Issue ID (supports wildcards: bd-*)
spec Spec ID (supports wildcards)

View file

@ -108,6 +108,9 @@ func formatIssueMetadata(issue *types.Issue) string {
// Line 2: Created · Updated · Due/Defer
timeParts := []string{}
timeParts = append(timeParts, fmt.Sprintf("Created: %s", issue.CreatedAt.Format("2006-01-02")))
if issue.StartedAt != nil {
timeParts = append(timeParts, fmt.Sprintf("Started: %s", issue.StartedAt.Format("2006-01-02")))
}
timeParts = append(timeParts, fmt.Sprintf("Updated: %s", issue.UpdatedAt.Format("2006-01-02")))
if issue.DueAt != nil {

View file

@ -180,6 +180,8 @@ func (e *Evaluator) applyComparison(comp *ComparisonNode, filter *types.IssueFil
return e.applyUpdatedFilter(comp, filter)
case "closed", "closed_at":
return e.applyClosedFilter(comp, filter)
case "started", "started_at":
return e.applyStartedFilter(comp, filter)
case "id":
return e.applyIDFilter(comp, filter)
case "spec", "spec_id":
@ -401,6 +403,27 @@ func (e *Evaluator) applyClosedFilter(comp *ComparisonNode, filter *types.IssueF
return nil
}
func (e *Evaluator) applyStartedFilter(comp *ComparisonNode, filter *types.IssueFilter) error {
t, err := e.parseTimeValue(comp)
if err != nil {
return fmt.Errorf("invalid started time: %w", err)
}
switch comp.Op {
case OpGreater:
filter.StartedAfter = &t
case OpGreaterEq:
filter.StartedAfter = &t
case OpLess:
filter.StartedBefore = &t
case OpLessEq:
endOfDay := time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 999999999, t.Location())
filter.StartedBefore = &endOfDay
default:
return fmt.Errorf("started does not support %s operator", comp.Op.String())
}
return nil
}
func (e *Evaluator) applyIDFilter(comp *ComparisonNode, filter *types.IssueFilter) error {
if comp.Op != OpEquals {
return fmt.Errorf("id only supports = operator")
@ -690,6 +713,8 @@ func (e *Evaluator) buildComparisonPredicate(comp *ComparisonNode) (func(*types.
return e.buildUpdatedPredicate(comp)
case "closed", "closed_at":
return e.buildClosedPredicate(comp)
case "started", "started_at":
return e.buildStartedPredicate(comp)
case "id":
return e.buildIDPredicate(comp)
case "spec", "spec_id":
@ -905,6 +930,19 @@ func (e *Evaluator) buildClosedPredicate(comp *ComparisonNode) (func(*types.Issu
}, nil
}
func (e *Evaluator) buildStartedPredicate(comp *ComparisonNode) (func(*types.Issue) bool, error) {
t, err := e.parseTimeValue(comp)
if err != nil {
return nil, fmt.Errorf("invalid started time: %w", err)
}
return func(i *types.Issue) bool {
if i.StartedAt == nil {
return false
}
return e.compareTime(comp.Op, *i.StartedAt, t)
}, nil
}
func (e *Evaluator) buildTimePredicate(op ComparisonOp, t time.Time, getter func(*types.Issue) time.Time) (func(*types.Issue) bool, error) {
return func(i *types.Issue) bool {
return e.compareTime(op, getter(i), t)

View file

@ -39,11 +39,24 @@ func ClaimIssueInTx(ctx context.Context, tx *sql.Tx, id string, actor string) (*
now := time.Now().UTC()
// Conditional UPDATE: only succeeds if assignee is currently empty.
result, err := tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s
SET assignee = ?, status = 'in_progress', updated_at = ?
WHERE id = ? AND (assignee = '' OR assignee IS NULL)
`, issueTable), actor, now, id)
// Also set started_at on first transition to in_progress (GH#2796); preserve
// any existing value so re-claims don't overwrite the original start time.
var (
result sql.Result
)
if oldIssue.StartedAt == nil {
result, err = tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s
SET assignee = ?, status = 'in_progress', updated_at = ?, started_at = ?
WHERE id = ? AND (assignee = '' OR assignee IS NULL)
`, issueTable), actor, now, now, id)
} else {
result, err = tx.ExecContext(ctx, fmt.Sprintf(`
UPDATE %s
SET assignee = ?, status = 'in_progress', updated_at = ?
WHERE id = ? AND (assignee = '' OR assignee IS NULL)
`, issueTable), actor, now, id)
}
if err != nil {
return nil, fmt.Errorf("failed to claim issue: %w", err)
}

View file

@ -225,6 +225,14 @@ func BuildIssueFilterClauses(query string, filter types.IssueFilter, tables Filt
whereClauses = append(whereClauses, "closed_at < ?")
args = append(args, filter.ClosedBefore.Format(time.RFC3339))
}
if filter.StartedAfter != nil {
whereClauses = append(whereClauses, "started_at > ?")
args = append(args, filter.StartedAfter.Format(time.RFC3339))
}
if filter.StartedBefore != nil {
whereClauses = append(whereClauses, "started_at < ?")
args = append(args, filter.StartedBefore.Format(time.RFC3339))
}
if filter.DeferAfter != nil {
whereClauses = append(whereClauses, "defer_until > ?")
args = append(args, filter.DeferAfter.Format(time.RFC3339))

View file

@ -47,7 +47,7 @@ func InsertIssueIntoTable(ctx context.Context, tx *sql.Tx, table string, issue *
INSERT INTO %s (
id, content_hash, title, description, design, acceptance_criteria, notes,
status, priority, issue_type, assignee, estimated_minutes,
created_at, created_by, owner, updated_at, closed_at, external_ref, spec_id,
created_at, created_by, owner, updated_at, started_at, closed_at, external_ref, spec_id,
compaction_level, compacted_at, compacted_at_commit, original_size,
sender, ephemeral, no_history, wisp_type, pinned, is_template,
mol_type, work_type, source_system, source_repo, close_reason,
@ -57,7 +57,7 @@ func InsertIssueIntoTable(ctx context.Context, tx *sql.Tx, table string, issue *
) VALUES (
?, ?, ?, ?, ?, ?, ?,
?, ?, ?, ?, ?,
?, ?, ?, ?, ?, ?, ?,
?, ?, ?, ?, ?, ?, ?, ?,
?, ?, ?, ?,
?, ?, ?, ?, ?, ?,
?, ?, ?, ?, ?,
@ -78,6 +78,7 @@ func InsertIssueIntoTable(ctx context.Context, tx *sql.Tx, table string, issue *
assignee = VALUES(assignee),
estimated_minutes = VALUES(estimated_minutes),
updated_at = VALUES(updated_at),
started_at = VALUES(started_at),
closed_at = VALUES(closed_at),
external_ref = VALUES(external_ref),
source_repo = VALUES(source_repo),
@ -86,7 +87,7 @@ func InsertIssueIntoTable(ctx context.Context, tx *sql.Tx, table string, issue *
`, table),
issue.ID, issue.ContentHash, issue.Title, issue.Description, issue.Design, issue.AcceptanceCriteria, issue.Notes,
issue.Status, issue.Priority, issue.IssueType, NullString(issue.Assignee), NullInt(issue.EstimatedMinutes),
issue.CreatedAt, issue.CreatedBy, issue.Owner, issue.UpdatedAt, issue.ClosedAt, NullStringPtr(issue.ExternalRef), issue.SpecID,
issue.CreatedAt, issue.CreatedBy, issue.Owner, issue.UpdatedAt, issue.StartedAt, issue.ClosedAt, NullStringPtr(issue.ExternalRef), issue.SpecID,
issue.CompactionLevel, issue.CompactedAt, NullStringPtr(issue.CompactedAtCommit), NullIntVal(issue.OriginalSize),
issue.Sender, issue.Ephemeral, issue.NoHistory, issue.WispType, issue.Pinned, issue.IsTemplate,
issue.MolType, issue.WorkType, issue.SourceSystem, issue.SourceRepo, issue.CloseReason,

View file

@ -13,7 +13,7 @@ import (
// use this constant to avoid column-list drift between scan sites.
const IssueSelectColumns = `id, content_hash, title, description, design, acceptance_criteria, notes,
status, priority, issue_type, assignee, estimated_minutes,
created_at, created_by, owner, updated_at, closed_at, external_ref, spec_id,
created_at, created_by, owner, updated_at, started_at, closed_at, external_ref, spec_id,
compaction_level, compacted_at, compacted_at_commit, original_size, source_repo, close_reason,
sender, ephemeral, no_history, wisp_type, pinned, is_template,
await_type, await_id, timeout_ns, waiters,
@ -34,7 +34,7 @@ type IssueScanner interface {
func ScanIssueFrom(s IssueScanner) (*types.Issue, error) {
var issue types.Issue
var createdAtStr, updatedAtStr sql.NullString // TEXT columns - must parse manually
var closedAt, compactedAt, dueAt, deferUntil sql.NullTime
var startedAt, closedAt, compactedAt, dueAt, deferUntil sql.NullTime
var estimatedMinutes, originalSize, timeoutNs sql.NullInt64
var createdBy sql.NullString
var assignee, externalRef, specID, compactedAtCommit, owner sql.NullString
@ -49,7 +49,7 @@ func ScanIssueFrom(s IssueScanner) (*types.Issue, error) {
&issue.ID, &contentHash, &issue.Title, &issue.Description, &issue.Design,
&issue.AcceptanceCriteria, &issue.Notes, &issue.Status,
&issue.Priority, &issue.IssueType, &assignee, &estimatedMinutes,
&createdAtStr, &createdBy, &owner, &updatedAtStr, &closedAt, &externalRef, &specID,
&createdAtStr, &createdBy, &owner, &updatedAtStr, &startedAt, &closedAt, &externalRef, &specID,
&issue.CompactionLevel, &compactedAt, &compactedAtCommit, &originalSize, &sourceRepo, &closeReason,
&sender, &ephemeral, &noHistory, &wispType, &pinned, &isTemplate,
&awaitType, &awaitID, &timeoutNs, &waiters,
@ -73,6 +73,9 @@ func ScanIssueFrom(s IssueScanner) (*types.Issue, error) {
if contentHash.Valid {
issue.ContentHash = contentHash.String
}
if startedAt.Valid {
issue.StartedAt = &startedAt.Time
}
if closedAt.Valid {
issue.ClosedAt = &closedAt.Time
}

View file

@ -18,7 +18,8 @@ func IsAllowedUpdateField(key string) bool {
"status": true, "priority": true, "title": true, "assignee": true,
"description": true, "design": true, "acceptance_criteria": true, "notes": true,
"issue_type": true, "estimated_minutes": true, "external_ref": true, "spec_id": true,
"closed_at": true, "close_reason": true, "closed_by_session": true,
"started_at": true,
"closed_at": true, "close_reason": true, "closed_by_session": true,
"source_repo": true,
"sender": true, "wisp": true, "wisp_type": true, "no_history": true, "pinned": true,
"mol_type": true,
@ -59,6 +60,34 @@ func ManageClosedAt(oldIssue *types.Issue, updates map[string]interface{}, setCl
return setClauses, args
}
// ManageStartedAt auto-sets started_at when transitioning to in_progress.
// If the issue already has a started_at, it is preserved (not overwritten).
func ManageStartedAt(oldIssue *types.Issue, updates map[string]interface{}, setClauses []string, args []interface{}) ([]string, []interface{}) {
statusVal, hasStatus := updates["status"]
_, hasExplicitStartedAt := updates["started_at"]
if hasExplicitStartedAt || !hasStatus {
return setClauses, args
}
var newStatus string
switch v := statusVal.(type) {
case string:
newStatus = v
case types.Status:
newStatus = string(v)
default:
return setClauses, args
}
if newStatus == string(types.StatusInProgress) && oldIssue.StartedAt == nil {
now := time.Now().UTC()
setClauses = append(setClauses, "started_at = ?")
args = append(args, now)
}
return setClauses, args
}
// DetermineEventType returns the appropriate event type for an update.
func DetermineEventType(oldIssue *types.Issue, updates map[string]interface{}) types.EventType {
statusVal, hasStatus := updates["status"]
@ -157,6 +186,9 @@ func UpdateIssueInTx(ctx context.Context, tx *sql.Tx, id string, updates map[str
// Auto-manage closed_at (set on close, clear on reopen).
setClauses, args = ManageClosedAt(oldIssue, updates, setClauses, args)
// Auto-manage started_at (set on transition to in_progress). (GH#2796)
setClauses, args = ManageStartedAt(oldIssue, updates, setClauses, args)
args = append(args, id)
//nolint:gosec // G201: issueTable comes from WispTableRouting (hardcoded constants)

View file

@ -0,0 +1,2 @@
ALTER TABLE issues DROP COLUMN started_at;
ALTER TABLE wisps DROP COLUMN started_at;

View file

@ -0,0 +1,2 @@
ALTER TABLE issues ADD COLUMN started_at DATETIME;
ALTER TABLE wisps ADD COLUMN started_at DATETIME;

View file

@ -40,6 +40,7 @@ type Issue struct {
CreatedAt time.Time `json:"created_at"`
CreatedBy string `json:"created_by,omitempty"` // Who created this issue (GH#748)
UpdatedAt time.Time `json:"updated_at"`
StartedAt *time.Time `json:"started_at,omitempty"` // When this issue transitioned to in_progress (GH#2796)
ClosedAt *time.Time `json:"closed_at,omitempty"`
CloseReason string `json:"close_reason,omitempty"` // Reason provided when closing
ClosedBySession string `json:"closed_by_session,omitempty"` // Claude Code session that closed this issue
@ -1192,6 +1193,8 @@ type IssueFilter struct {
UpdatedBefore *time.Time
ClosedAfter *time.Time
ClosedBefore *time.Time
StartedAfter *time.Time
StartedBefore *time.Time
// Empty/null checks
EmptyDescription bool