From 5ea976583e547ddc4df20237f65f6329a2c303fc Mon Sep 17 00:00:00 2001 From: Taylor Eernisse Date: Wed, 11 Feb 2026 08:10:51 -0500 Subject: [PATCH] docs: update README, AGENTS, and robot-mode-design for work item status README.md: - Feature summary updated to mention work item status sync and GraphQL - New config reference entry for sync.fetchWorkItemStatus (default true) - Issue listing/show examples include --status flag usage - Valid fields list expanded with status_name, status_category, status_color, status_icon_name, status_synced_at_iso - Database schema table updated for issues table - Ingest/sync command descriptions mention status enrichment phase - Adaptive page sizing and graceful degradation documented AGENTS.md: - Robot mode example shows --status flag usage docs/robot-mode-design.md: - Issue available fields list expanded with status fields Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 3 +++ README.md | 27 +++++++++++++++++---------- docs/robot-mode-design.md | 2 +- 3 files changed, 21 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2315d17..8a49bd0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -618,6 +618,9 @@ LORE_ROBOT=1 lore issues lore --robot issues -n 10 lore --robot mrs -s opened +# Filter issues by work item status (case-insensitive) +lore --robot issues --status "In progress" + # List with field selection (reduces token usage ~60%) lore --robot issues --fields minimal lore --robot mrs --fields iid,title,state,draft diff --git a/README.md b/README.md index 7141a6d..eed85e3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Gitlore -Local GitLab data management with semantic search, people intelligence, and temporal analysis. Syncs issues, MRs, discussions, and notes from GitLab to a local SQLite database for fast, offline-capable querying, filtering, hybrid search, chronological event reconstruction, and expert discovery. +Local GitLab data management with semantic search, people intelligence, and temporal analysis. Syncs issues, MRs, discussions, notes, and work item statuses from GitLab to a local SQLite database for fast, offline-capable querying, filtering, hybrid search, chronological event reconstruction, and expert discovery. ## Features @@ -8,7 +8,7 @@ Local GitLab data management with semantic search, people intelligence, and temp - **Incremental sync**: Cursor-based sync only fetches changes since last sync - **Full re-sync**: Reset cursors and fetch all data from scratch when needed - **Multi-project**: Track issues and MRs across multiple GitLab projects -- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date, draft status, reviewer, branches +- **Rich filtering**: Filter by state, author, assignee, labels, milestone, due date, draft status, reviewer, branches, work item status - **Hybrid search**: Combines FTS5 lexical search with Ollama-powered vector embeddings via Reciprocal Rank Fusion - **People intelligence**: Expert discovery, workload analysis, review patterns, active discussions, and code ownership overlap - **Timeline pipeline**: Reconstructs chronological event histories by combining search, graph traversal, and event aggregation across related entities @@ -17,6 +17,7 @@ Local GitLab data management with semantic search, people intelligence, and temp - **Raw payload storage**: Preserves original GitLab API responses for debugging - **Discussion threading**: Full support for issue and MR discussions including inline code review comments - **Cross-reference tracking**: Automatic extraction of "closes", "mentioned" relationships between MRs and issues +- **Work item status enrichment**: Fetches issue statuses (e.g., "To do", "In progress", "Done") from GitLab's GraphQL API with adaptive page sizing, color-coded display, and case-insensitive filtering - **Resource event history**: Tracks state changes, label events, and milestone events for issues and MRs - **Robot mode**: Machine-readable JSON output with structured errors, meaningful exit codes, and actionable recovery steps - **Observability**: Verbosity controls, JSON log format, structured metrics, and stage timing @@ -96,7 +97,8 @@ Configuration is stored in `~/.config/lore/config.json` (or `$XDG_CONFIG_HOME/lo "heartbeatIntervalSeconds": 30, "cursorRewindSeconds": 2, "primaryConcurrency": 4, - "dependentConcurrency": 2 + "dependentConcurrency": 2, + "fetchWorkItemStatus": true }, "storage": { "compressRawPayloads": true @@ -123,6 +125,7 @@ Configuration is stored in `~/.config/lore/config.json` (or `$XDG_CONFIG_HOME/lo | `sync` | `cursorRewindSeconds` | `2` | Seconds to rewind cursor for overlap safety | | `sync` | `primaryConcurrency` | `4` | Concurrent GitLab requests for primary resources | | `sync` | `dependentConcurrency` | `2` | Concurrent requests for dependent resources | +| `sync` | `fetchWorkItemStatus` | `true` | Enrich issues with work item status via GraphQL (requires GitLab Premium/Ultimate) | | `storage` | `dbPath` | `~/.local/share/lore/lore.db` | Database file path | | `storage` | `backupDir` | `~/.local/share/lore/backups` | Backup directory | | `storage` | `compressRawPayloads` | `true` | Compress stored API responses with gzip | @@ -184,6 +187,8 @@ lore issues --since 1m # Updated in last month lore issues --since 2024-01-01 # Updated since date lore issues --due-before 2024-12-31 # Due before date lore issues --has-due # Only issues with due dates +lore issues --status "In progress" # By work item status (case-insensitive) +lore issues --status "To do" --status "In progress" # Multiple statuses (OR) lore issues -p group/repo # Filter by project lore issues --sort created --asc # Sort by created date, ascending lore issues -o # Open first result in browser @@ -193,9 +198,9 @@ lore -J issues --fields minimal # Compact: iid, title, state, updated_at_i lore -J issues --fields iid,title,labels,state # Custom fields ``` -When listing, output includes: IID, title, state, author, assignee, labels, and update time. In robot mode, the `--fields` flag controls which fields appear in the JSON response. +When listing, output includes: IID, title, state, status (when any issue has one), assignee, labels, and update time. Status values display with their configured color. In robot mode, the `--fields` flag controls which fields appear in the JSON response. -When showing a single issue (e.g., `lore issues 123`), output includes: title, description, state, author, assignees, labels, milestone, due date, web URL, and threaded discussions. +When showing a single issue (e.g., `lore issues 123`), output includes: title, description, state, work item status (with color and category), author, assignees, labels, milestone, due date, web URL, and threaded discussions. #### Project Resolution @@ -397,7 +402,7 @@ When graph expansion encounters cross-project references to entities not yet syn ### `lore sync` -Run the full sync pipeline: ingest from GitLab, generate searchable documents, and compute embeddings. +Run the full sync pipeline: ingest from GitLab (including work item status enrichment via GraphQL), generate searchable documents, and compute embeddings. ```bash lore sync # Full pipeline @@ -413,11 +418,11 @@ The sync command displays animated progress bars for each stage and outputs timi ### `lore ingest` -Sync data from GitLab to local database. Runs only the ingestion step (no doc generation or embeddings). +Sync data from GitLab to local database. Runs only the ingestion step (no doc generation or embeddings). For issue ingestion, this includes a status enrichment phase that fetches work item statuses via the GitLab GraphQL API. ```bash lore ingest # Ingest everything (issues + MRs) -lore ingest issues # Issues only +lore ingest issues # Issues only (includes status enrichment) lore ingest mrs # MRs only lore ingest issues -p group/repo # Single project lore ingest --force # Override stale lock @@ -430,6 +435,8 @@ The `--full` flag resets sync cursors and discussion watermarks, then fetches al - You want to ensure complete data after schema changes - Troubleshooting sync issues +Status enrichment uses adaptive page sizing (100 → 50 → 25 → 10) to handle GitLab GraphQL complexity limits. It gracefully handles instances without GraphQL support or Premium/Ultimate licensing. Disable via `sync.fetchWorkItemStatus: false` in config. + ### `lore generate-docs` Extract searchable documents from ingested issues, MRs, and discussions for the FTS5 index. @@ -623,7 +630,7 @@ lore -J issues --fields iid,title,state,labels,updated_at_iso # minimal: iid, title, state, updated_at_iso ``` -Valid fields for issues: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path` +Valid fields for issues: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `status_name`, `status_category`, `status_color`, `status_icon_name`, `status_synced_at_iso` Valid fields for MRs: `iid`, `title`, `state`, `author_username`, `labels`, `draft`, `target_branch`, `source_branch`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `reviewers` @@ -714,7 +721,7 @@ Data is stored in SQLite with WAL mode and foreign keys enabled. Main tables: | Table | Purpose | |-------|---------| | `projects` | Tracked GitLab projects with metadata | -| `issues` | Issue metadata (title, state, author, due date, milestone) | +| `issues` | Issue metadata (title, state, author, due date, milestone, work item status) | | `merge_requests` | MR metadata (title, state, draft, branches, merge status, commit SHAs) | | `milestones` | Project milestones with state and due dates | | `labels` | Project labels with colors | diff --git a/docs/robot-mode-design.md b/docs/robot-mode-design.md index 4c7e9a7..5bdcf54 100644 --- a/docs/robot-mode-design.md +++ b/docs/robot-mode-design.md @@ -125,7 +125,7 @@ lore -J mrs --fields iid,title,state,draft,target_branch ### Available Fields -**Issues**: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path` +**Issues**: `iid`, `title`, `state`, `author_username`, `labels`, `assignees`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `status_name`, `status_category`, `status_color`, `status_icon_name`, `status_synced_at_iso` **MRs**: `iid`, `title`, `state`, `author_username`, `labels`, `draft`, `target_branch`, `source_branch`, `discussion_count`, `unresolved_count`, `created_at_iso`, `updated_at_iso`, `web_url`, `project_path`, `reviewers`