Review Trail Finding Command Design

Implemented the trail/finding UX cleanup.

Changed:

• cmd/entire/cli/trail_cmd.go
  • Updated entire trail long help to your phrasing.
• cmd/entire/cli/trail_review_cmd.go
  • Clarified --status as lifecycle status.
  • Clarified --stale as code-version freshness.
  • Clarified apply: by default it only changes files; --resolve updates lifecycle status after successful apply.
  • Changed apply output from generic “Updated finding …” to “Resolved finding … after apply …”.
  • Made entire trail finding printing more consistent with list-style output:
    • indented header
    • shared tabular findings printer
    • added FRESHNESS column instead of a confusing stale/status pairing
    • show now prints Freshness: too.
• Updated tests accordingly.

My take:

• A finding should not be “updated with apply” in the generic sense. apply should apply code changes; --resolve is a convenience lifecycle transition.
• status and stale are worth keeping separate: status is human workflow state, freshness/staleness is whether the finding still applies to the current code version.
• The previous default print was indeed inconsistent; the new table format is closer to other CLI list outputs.

Validation:

• mise exec -- go test ./cmd/entire/cli
• mise run lint

Good catch: before this, you effectively couldn’t update finding metadata from the CLI — only lifecycle status via resolve/dismiss/reopen, or apply --resolve.

I added:

Also supports trail selection:

What stays separate:

• update = metadata/content: title, body, severity, confidence
• resolve / dismiss / reopen = lifecycle status
• apply = apply code suggestion; apply --resolve is just a convenience after successful apply

Changed files:

• cmd/entire/cli/trail_review_cmd.go
• cmd/entire/cli/trail_review_cmd_test.go

Validation:

• mise exec -- go test ./cmd/entire/cli
• mise run lint

Here’s the finding command surface after review:

Target selection

Most commands accept either:

<trail> = number, id, or branch. If omitted, current branch’s trail is used.

Commands

Filters

• --status: lifecycle state: open, resolved, dismissed, any
• --stale: code-version freshness: current, stale, any
• --severity: high, medium, low
• default view: open + current

Critical take

The split now makes sense:

• update changes finding content/metadata.
• resolve/dismiss/reopen change lifecycle.
• apply changes files only; apply --resolve is a convenience.
• stale is not lifecycle status; it is “does this finding still match current code?”

Remaining rough edges:

• --stale is still a slightly awkward flag name; “freshness” is clearer, but changing the flag may be disruptive.
• update cannot change location or suggested changes yet.
• add supports body but not explicit title.

Yes — they are effectively the same today.

Both stream the trail-scoped review/finding SSE endpoint:

Difference is mostly command shape:

• entire trail watch [<number>]

  • older/top-level trail subcommand
  • only accepts trail number or defaults to current branch
  • name suggests “all trail events”, but it actually prints finding/review events

• entire trail finding watch [<trail>]

  • lives under the finding noun, which is more accurate
  • accepts number/id/branch or --trail
  • same output/flags: --json, --show-pings, --once

My take: this is duplicate and confusing.

Best cleanup:

• Make entire trail finding watch the canonical command.
• Hide or deprecate entire trail watch, or make it an alias that points users to trail finding watch.
• If we keep trail watch, it should eventually stream broader trail lifecycle events, not just finding events.

Agreed on all points. I updated the CLI accordingly.

Decisions

• entire trail watch

  • keep as canonical watch command
  • intended for broader trail events over time

• entire trail finding watch

  • removed
  • duplicate/confusing

• --stale

  • best replacement: --freshness
  • now canonical:
  • --stale remains as deprecated alias for compatibility.

• update

  • no location update
  • no title update
  • now only:

• add

  • no title
  • correct: finding body is the primary content.

Current finding commands

Validation:

• mise exec -- go test ./cmd/entire/cli passes.

Done.

Changes made:

• Removed entire trail finding watch.
• Kept entire trail watch as the canonical watch command.
• Added canonical --freshness current|stale|any.
• Kept --stale only as deprecated alias for compatibility.
• Removed finding --title from update.
• Removed title-style display from findings; table now uses SUMMARY.
• update now supports only:
  • --body/-m
  • --severity
  • --confidence
  • --json

Validation:

• mise exec -- go test ./cmd/entire/cli passes.
• golangci-lint --new-from-rev=HEAD ./cmd/entire/cli passes.

Cleaned up.

• Removed --stale entirely.
• Kept only:
• Renamed internal list option from Stale to Freshness.
• Updated errors to say invalid freshness filter.
• Kept API query param as stale because that’s the server contract.

Validation:

• mise exec -- go test ./cmd/entire/cli
• golangci-lint --new-from-rev=HEAD ./cmd/entire/cli

Created PR: https://github.com/entireio/cli/pull/1477

Added the before/after snapshot to both:

• PR body: https://github.com/entireio/cli/pull/1477
• Trail #619 body for trail-finding-command-cleanup

Addressed and resolved the trail finding.

Change:

• Added trailReviewFreshnessStale = "stale".
• Replaced hardcoded "stale" usage in validation/counting with the constant.

Pushed commit:

• 0ecbd07e7 Use freshness constant for stale findings

Validated:

• mise exec -- go test ./cmd/entire/cli
• golangci-lint --new-from-rev=HEAD ./cmd/entire/cli

Finding is now resolved.