gitlore/acceptance-criteria.md

Trace/File-History Empty-Result Diagnostics

AC-1: Human mode shows searched paths on empty results

When lore trace <path> returns 0 chains in human mode, the output includes the resolved path(s) that were searched. If renames were followed, show the full rename chain.

AC-2: Human mode shows actionable reason on empty results

When 0 chains are found, the hint message distinguishes between:

• "No MR file changes synced yet" (mr_file_changes table is empty for this project) -> suggest lore sync
• "File paths not found in MR file changes" (sync has run but this file has no matches) -> suggest checking the path or that the file may predate the sync window

AC-3: Robot mode includes diagnostics object on empty results

When total_chains == 0 in robot JSON output, add a "diagnostics" key to "meta" containing:

• paths_searched: [...] (already present as resolved_paths in data -- no duplication needed)
• hints: [string] -- same actionable reasons as AC-2 but machine-readable

AC-4: Info-level logging at each pipeline stage

Add tracing::info! calls visible with -v:

• After rename resolution: number of paths found
• After MR query: number of MRs found
• After issue/discussion enrichment: counts per MR

AC-5: Apply same pattern to lore file-history

All of the above (AC-1 through AC-4) also apply to lore file-history empty results.

---

Secure Token Resolution for Cron

AC-6: Stored token in config

The configuration file supports an optional token field in the gitlab section, allowing users to persist their GitLab personal access token alongside other settings. Existing configuration files that omit this field continue to load and function normally.

AC-7: Token resolution precedence

Lore resolves the GitLab token by checking the environment variable first, then falling back to the stored config token. This means environment variables always take priority, preserving CI/CD workflows and one-off overrides, while the stored token provides a reliable default for non-interactive contexts like cron jobs. If neither source provides a non-empty value, the user receives a clear TOKEN_NOT_SET error with guidance on how to fix it.

AC-8: lore token set command

The lore token set command provides a secure, guided workflow for storing a GitLab token. It accepts the token via a --token flag, standard input (for piped automation), or an interactive masked prompt. Before storing, it validates the token against the GitLab API to catch typos and expired credentials early. After writing the token to the configuration file, it restricts file permissions to owner-only read/write (mode 0600) to prevent other users on the system from reading the token. The command supports both human and robot output modes.

AC-9: lore token show command

The lore token show command displays the currently active token along with its source ("config file" or "environment variable"). By default the token value is masked for safety; the --unmask flag reveals the full value when needed. The command supports both human and robot output modes.

AC-10: Consistent token resolution across all commands

Every command that requires a GitLab token uses the same two-step resolution logic described in AC-7. This ensures that storing a token once via lore token set is sufficient to make all commands work, including background cron syncs that have no access to shell environment variables.

AC-11: Cron install warns about missing stored token

When lore cron install completes, it checks whether a token is available in the configuration file. If not, it displays a prominent warning explaining that cron jobs cannot access shell environment variables and directs the user to run lore token set to ensure unattended syncs will authenticate successfully.

AC-12: TOKEN_NOT_SET error recommends lore token set

The TOKEN_NOT_SET error message recommends lore token set as the primary fix for missing credentials, with the environment variable export shown as an alternative for users who prefer that approach. In robot mode, the actions array lists both options so that automated recovery workflows can act on them.

AC-13: Doctor reports token source

The lore doctor command includes the token's source in its GitLab connectivity check, reporting whether the token was found in the configuration file or an environment variable. This makes it straightforward to verify that cron jobs will have access to the token without relying on the user's interactive shell environment.