icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-39-observability-operations.md

@@ -0,0 +1,178 @@
+# Phase 39 — Observability & Operations
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 39 |
+| Title | Observability & Operations — Hook-Based Agent Monitoring |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 28 (Remote Command Gateway), Phase 21 (SaaS Multi-Tenancy) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV's 15-agent multi-agent architecture operates across MCP servers, A2A protocol channels, dashboard endpoints, and remote gateway channels. Without real-time visibility into agent execution, tool usage, and session lifecycle, operators cannot detect anomalies, audit agent behavior, or diagnose failures. Prior to Phase 39, tool invocations were fire-and-forget with no centralized event stream, making post-mortem analysis dependent on scattered log files.
+
+The GOTCHA framework mandates that business logic remain deterministic while the AI orchestration layer handles probabilistic decisions. This separation requires an observability layer that captures every tool use event, agent execution result, and session lifecycle transition in an append-only, tamper-evident audit trail. Without HMAC-signed event integrity, the audit trail cannot satisfy NIST 800-53 AU controls for non-repudiation.
+
+Furthermore, enterprise deployments require integration with existing SIEM platforms (Splunk, ELK) for centralized monitoring. The observability layer must forward events to external systems while maintaining air-gap compatibility through buffered offline operation and graceful degradation when SIEM endpoints are unreachable.
+
+---
+
+## 2. Goals
+
+1. Capture every Claude Code hook event (pre_tool_use, post_tool_use, notification, stop, subagent_stop) in an append-only database table with HMAC-SHA256 tamper detection
+2. Provide a subprocess-based agent execution framework that invokes Claude Code CLI with structured JSONL output, retry logic, and safe environment filtering
+3. Forward events to enterprise SIEM platforms (Splunk, ELK) via HTTP POST with backlog buffering for disconnected scenarios
+4. Stream events to the dashboard via SSE (Server-Sent Events) for real-time agent activity visualization
+5. Maintain air-gap compatibility by storing all events locally first and forwarding opportunistically
+6. Log all agent executions with token usage, duration, status, and session correlation for cost tracking and performance analysis
+
+---
+
+## 3. Architecture
+
+```
+Claude Code Hooks (.claude/hooks/)
+  pre_tool_use.py ──┐
+  post_tool_use.py ──┤
+  notification.py ───┼──→ send_event.py ──→ hook_events table (append-only)
+  stop.py ───────────┤         │                    │
+  subagent_stop.py ──┘         │                    ↓
+                               ├──→ SSE Manager ──→ Dashboard /events
+                               │
+                               └──→ SIEM Forwarder ──→ Splunk / ELK
+                                        │
+                                   Backlog Buffer (offline)
+
+Agent Executor
+  agent_executor.py ──→ Claude Code CLI (subprocess)
+         │                    │
+         ├──→ JSONL parse     │
+         ├──→ Retry logic     │
+         └──→ agent_executions table (append-only)
+```
+
+Hook events are captured at the Claude Code integration layer. Each hook fires a Python script that calls `send_event.py`, which stores the event in the `hook_events` table with an HMAC-SHA256 signature computed from the event payload and a shared secret (sourced from AWS Secrets Manager or environment variable). Events are simultaneously pushed to the SSE manager for real-time dashboard streaming and queued for SIEM forwarding.
+
+The agent executor wraps Claude Code CLI invocations as subprocesses with JSONL output parsing, configurable retry delays, safe environment variable filtering (only allowlisted env vars passed), and structured result storage in the `agent_executions` table.
+
+---
+
+## 4. Requirements
+
+### 4.1 Hook Event Capture
+
+#### REQ-39-001: Post-Tool-Use Logging
+The system SHALL log every tool use completion to the `hook_events` table, including tool name, input parameters (truncated to 2000 chars), output summary, duration, and session ID.
+
+#### REQ-39-002: HMAC-SHA256 Event Signing
+The system SHALL compute an HMAC-SHA256 signature for each event payload using a secret key sourced from the configured secrets provider. The signature SHALL be stored alongside the event for tamper detection verification.
+
+#### REQ-39-003: Append-Only Event Storage
+The `hook_events` table SHALL be append-only with no UPDATE or DELETE operations, satisfying NIST 800-53 AU-9 (Protection of Audit Information).
+
+#### REQ-39-004: Payload Truncation
+Event payloads SHALL be truncated to 2000 characters maximum to prevent database bloat from large tool outputs.
+
+### 4.2 Agent Execution Framework
+
+#### REQ-39-005: Subprocess-Based Agent Invocation
+The agent executor SHALL invoke Claude Code CLI as a subprocess with `stdin=DEVNULL`, structured JSONL output parsing, and configurable timeout.
+
+#### REQ-39-006: Retry Logic
+The agent executor SHALL support configurable retry delays (default: [1, 3, 5] seconds) with exponential backoff for transient failures including rate limiting.
+
+#### REQ-39-007: Safe Environment
+The agent executor SHALL pass only allowlisted environment variables to the subprocess, preventing credential leakage.
+
+#### REQ-39-008: Execution Logging
+All agent executions SHALL be logged to the `agent_executions` table with token usage, duration, status, error details, and session correlation ID.
+
+### 4.3 SIEM Forwarding
+
+#### REQ-39-009: SIEM HTTP Forwarding
+The system SHALL forward events to configured SIEM endpoints (Splunk HEC, ELK/Logstash) via HTTP POST with configurable URL, authentication, and batch size.
+
+#### REQ-39-010: Backlog Buffering
+When SIEM endpoints are unreachable, the system SHALL buffer events locally and forward them when connectivity is restored.
+
+### 4.4 Dashboard Integration
+
+#### REQ-39-011: SSE Event Streaming
+The system SHALL stream events to the dashboard via Server-Sent Events with a connection status indicator and 3-second debounce batching (D99).
+
+#### REQ-39-012: Event Timeline
+The dashboard `/events` page SHALL display a real-time timeline of agent activity with filtering by hook type, tool name, and session.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `hook_events` | Append-only storage of all Claude Code hook events with HMAC signatures, payload, tool name, hook type, session ID, timestamp |
+| `agent_executions` | Append-only storage of all agent CLI invocations with token usage, duration, status, error details, model, prompt hash |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/agent/send_event.py` | Shared event utility — stores event in DB, forwards to SSE and SIEM |
+| `tools/agent/agent_executor.py` | Subprocess-based Claude Code CLI invocation with retry, JSONL parsing, safe env |
+| `tools/agent/agent_models.py` | Data models for agent request, response, retry codes, execution status |
+| `.claude/hooks/post_tool_use.py` | Hook script — logs tool results to hook_events table |
+| `.claude/hooks/notification.py` | Hook script — logs user notifications |
+| `.claude/hooks/stop.py` | Hook script — captures session completion |
+| `.claude/hooks/subagent_stop.py` | Hook script — logs subagent task results |
+| `tools/dashboard/api/events.py` | Flask blueprint for SSE event streaming |
+| `tools/dashboard/sse_manager.py` | SSE connection management and event dispatch |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D31 | HMAC-SHA256 event signing for hooks | Tamper detection without PKI overhead; secret via AWS Secrets Manager or env var |
+| D35 | Agent executor stores JSONL output in `agents/` dir | Auditable, replayable, consistent with observability pattern |
+| D29 | SSE over WebSocket for dashboard live updates | Flask-native, simpler, no additional deps, unidirectional sufficient |
+| D99 | SSE live updates debounce to 3-second batches | Prevents API hammering while keeping dashboard near-real-time |
+| D6 | Audit trail is append-only/immutable | No UPDATE/DELETE — NIST 800-53 AU compliance |
+
+---
+
+## 8. Security Gate
+
+**Observability Gate:**
+- Hook events table must have HMAC signatures verifiable for tamper detection
+- Agent executions must be logged with token usage and duration for cost tracking
+- SIEM forwarding must be configured for IL4+ deployments
+- Dashboard SSE stream must reflect events within 2 seconds
+- No plaintext secrets in agent executor environment (safe env filtering enforced)
+
+---
+
+## 9. Commands
+
+```bash
+# Agent execution
+python tools/agent/agent_executor.py --prompt "echo hello" --model sonnet --json
+python tools/agent/agent_executor.py --prompt "fix tests" --model opus --max-retries 3
+
+# Dashboard events
+# Start dashboard: python tools/dashboard/app.py
+# Navigate to /events for real-time event timeline (SSE)
+
+# Configuration
+# args/observability_config.yaml — Hook, executor, dashboard, SIEM settings
+```

icdev/data/docs/features/phase-40-nlq-compliance-queries.md

@@ -0,0 +1,176 @@
+# Phase 40 — NLQ Compliance Queries
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 40 |
+| Title | Natural Language Compliance Queries |
+| Status | Implemented |
+| Priority | P2 |
+| Dependencies | Phase 39 (Observability & Operations), Phase 21 (SaaS Multi-Tenancy) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV's operational database contains 193 tables spanning compliance assessments, audit trails, security findings, project status, agent telemetry, and supply chain data. Compliance officers, ISSOs, and program managers need to query this data to answer questions like "Show all CAT1 STIG findings for project X" or "Which projects have expired cATO evidence?" — but they lack SQL expertise and should not be expected to learn the database schema.
+
+Prior to Phase 40, all compliance data access required either navigating dashboard pages (limited to pre-built views) or writing raw SQL queries against the database (requiring technical expertise and risking accidental data modification). Neither approach serves the needs of non-technical compliance stakeholders who need ad-hoc answers to specific compliance questions.
+
+Furthermore, the append-only audit trail (NIST 800-53 AU controls) must be protected from any modification, even accidental. A natural language query interface that generates SQL must enforce strict read-only access, blocking any query that could modify data. The system must also maintain a full audit trail of all queries executed, including generated SQL, execution time, and query status.
+
+---
+
+## 2. Goals
+
+1. Enable natural language queries against the ICDEV compliance database through the web dashboard `/query` page
+2. Generate SQL from natural language using Amazon Bedrock (Claude) with schema context and few-shot examples
+3. Enforce strict read-only SQL execution — block all DML/DDL operations (DROP, DELETE, UPDATE, INSERT, ALTER, CREATE, TRUNCATE, ATTACH, DETACH)
+4. Provide a pattern-based fallback SQL generator for air-gapped environments without Bedrock access
+5. Log every query to the `nlq_queries` audit table with generated SQL, execution status, and actor identity
+6. Integrate with the SSE event system (Phase 39) for real-time query event streaming on the `/events` page
+
+---
+
+## 3. Architecture
+
+```
+User (Dashboard /query)
+         │
+         ↓
+   NLQ Processor (nlq_processor.py)
+         │
+    ┌────┴────┐
+    │         │
+    ↓         ↓
+ Bedrock   Pattern-Based
+ (Claude)   (Fallback)
+    │         │
+    └────┬────┘
+         │
+         ↓
+   SQL Validator ──→ BLOCKED (if DML/DDL detected)
+         │
+         ↓
+   Safe Executor (read-only connection, 500 row limit, 10s timeout)
+         │
+         ├──→ nlq_queries table (audit trail)
+         └──→ SSE Manager ──→ /events page
+```
+
+The NLQ processor extracts the database schema (tables, columns, types, row counts) and sends it to Bedrock alongside few-shot examples from `context/dashboard/nlq_examples.json` and a system prompt from `hardprompts/dashboard/nlq_system_prompt.md`. The generated SQL passes through a strict validator that rejects any non-SELECT query. Safe execution uses a read-only database connection with a 500-row limit and 10-second timeout.
+
+When Bedrock is unavailable (air-gapped or rate-limited), a pattern-based fallback matches common query patterns to pre-built SQL templates. All queries are logged to `nlq_queries` with status (success, error, blocked) and forwarded to the SSE event stream.
+
+---
+
+## 4. Requirements
+
+### 4.1 Natural Language Processing
+
+#### REQ-40-001: NLQ-to-SQL Generation
+The system SHALL generate SQL queries from natural language input using Amazon Bedrock (Claude) with database schema context, table descriptions, and few-shot examples.
+
+#### REQ-40-002: Schema Context Injection
+The system SHALL extract and inject the current database schema (table names, column names, column types, row counts) into the LLM prompt to enable accurate SQL generation.
+
+#### REQ-40-003: Few-Shot Examples
+The system SHALL use curated NLQ-to-SQL examples from `context/dashboard/nlq_examples.json` to improve generation accuracy for common compliance queries.
+
+#### REQ-40-004: Pattern-Based Fallback
+The system SHALL provide a pattern-based SQL generator that matches common query patterns when Bedrock is unavailable, ensuring air-gap compatibility.
+
+### 4.2 Security Enforcement
+
+#### REQ-40-005: Read-Only SQL Enforcement
+The system SHALL reject any generated SQL that does not start with SELECT or WITH. The system SHALL block: DROP, DELETE, UPDATE, INSERT, ALTER, CREATE, TRUNCATE, ATTACH, DETACH, and multi-statement queries.
+
+#### REQ-40-006: Dangerous PRAGMA Blocking
+The system SHALL block dangerous SQLite PRAGMA statements that could modify database behavior or expose internal state.
+
+#### REQ-40-007: Row Limit Enforcement
+The system SHALL enforce a maximum row limit of 500 rows (configurable) on all query results to prevent resource exhaustion.
+
+#### REQ-40-008: Query Timeout
+The system SHALL enforce a 10-second execution timeout on all queries to prevent long-running operations from blocking the system.
+
+### 4.3 Audit Trail
+
+#### REQ-40-009: Query Audit Logging
+Every query SHALL be logged to the `nlq_queries` table with: natural language input, generated SQL, execution status (success/error/blocked), execution time, result row count, and actor identity.
+
+### 4.4 Dashboard Integration
+
+#### REQ-40-010: Query Dashboard Page
+The dashboard SHALL provide a `/query` page with a natural language input field, SQL preview, result table display, and query history.
+
+#### REQ-40-011: SSE Event Integration
+Query events SHALL be streamed to the `/events` SSE timeline, including query submission, execution, and result status.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `nlq_queries` | Audit trail of all NLQ queries — natural language input, generated SQL, status (success/error/blocked), execution time, row count, actor, timestamp |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/dashboard/nlq_processor.py` | NLQ-to-SQL pipeline — schema extraction, Bedrock generation, SQL validation, safe execution |
+| `tools/dashboard/api/nlq.py` | Flask blueprint for NLQ API endpoints (POST /api/nlq/query) |
+| `tools/dashboard/api/events.py` | Flask blueprint for SSE event streaming (shared with Phase 39) |
+| `tools/dashboard/sse_manager.py` | SSE connection management (shared with Phase 39) |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D30 | Bedrock for NLQ-to-SQL (not OpenAI) | Air-gap safe via GovCloud, consistent with D23 COA generation, available in government regions |
+| D34 | Read-only SQL enforcement for NLQ | Append-only audit trail (D6) must not be compromised by NLQ queries; defense in depth |
+| D29 | SSE for real-time query events | Consistent with Phase 39 SSE infrastructure; Flask-native, unidirectional |
+
+---
+
+## 8. Security Gate
+
+**NLQ Security Gate:**
+- All generated SQL must pass read-only validation (no DML/DDL)
+- Blocked queries must be logged with full context for security review
+- Query execution timeout must be enforced (10 seconds max)
+- Row limit must be enforced (500 rows max)
+- All queries must be audit-logged to `nlq_queries` table regardless of status
+- Pattern-based fallback must be available for air-gapped deployments
+
+---
+
+## 9. Commands
+
+```bash
+# Start dashboard with NLQ support
+python tools/dashboard/app.py
+
+# Navigate to /query for natural language compliance queries
+# Navigate to /events for real-time event timeline (SSE)
+
+# Configuration
+# args/nlq_config.yaml — Bedrock model, row limits, blocked SQL patterns, SSE heartbeat
+
+# Context files
+# context/dashboard/nlq_examples.json — Few-shot NLQ-to-SQL examples
+# context/dashboard/schema_descriptions.json — Human-readable table descriptions
+
+# Hard prompts
+# hardprompts/dashboard/nlq_system_prompt.md — Bedrock system prompt for SQL generation
+```

icdev/data/docs/features/phase-41-parallel-cicd.md

@@ -0,0 +1,169 @@
+# Phase 41 — Parallel CI/CD
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 41 |
+| Title | Parallel CI/CD — Git Worktree Task Isolation |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 39 (Observability & Operations), Phase 11 (CI/CD Integration) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV's CI/CD integration (Phase 11) processes issues sequentially — each workflow (plan, build, test, review) runs on the main working directory with a single git branch. When multiple GitLab issues require concurrent processing, workflows block each other, leading to bottlenecks and increased cycle time. In DoD environments where multiple development teams submit work simultaneously via GitLab task boards, sequential processing is a critical limitation.
+
+Git worktrees provide a mechanism for parallel, conflict-free execution by creating isolated working directory copies that share the same repository history but operate on independent branches. Combined with sparse checkout (only checking out the target directory for each task), worktrees minimize disk usage while providing full isolation. Each worktree gets its own CUI classification marker, ensuring classification awareness even in parallel execution.
+
+Additionally, GitLab task boards serve as the primary work intake mechanism for many DoD teams. Automated detection of ICDEV workflow tags in GitLab issues, combined with worktree-based isolation, enables a fully automated parallel CI/CD pipeline where multiple tasks progress concurrently without git conflicts or branch collisions.
+
+---
+
+## 2. Goals
+
+1. Enable parallel, conflict-free CI/CD workflow execution through git worktree isolation with sparse checkout
+2. Automate GitLab task board monitoring with `{{icdev: workflow}}` tag-based routing to ICDEV workflows
+3. Create per-task isolated branches and worktrees with CUI classification markers
+4. Track worktree and task claim state in the database for deduplication and lifecycle management
+5. Provide worktree lifecycle commands (create, list, cleanup, status) for manual and automated use
+6. Clean up worktrees automatically after workflow completion or failure
+
+---
+
+## 3. Architecture
+
+```
+GitLab Task Board
+  Issue #1: {{icdev: build}} ──┐
+  Issue #2: {{icdev: sdlc}}  ──┤
+  Issue #3: {{icdev: comply}} ──┤
+                                ↓
+          gitlab_task_monitor.py (polls every 20s)
+                │
+          ┌─────┼──────────┐
+          ↓     ↓          ↓
+    Claim #1  Claim #2  Claim #3
+    (dedup)   (dedup)   (dedup)
+          │     │          │
+          ↓     ↓          ↓
+    worktree  worktree  worktree
+    trees/    trees/    trees/
+    task-1/   task-2/   task-3/
+    (sparse)  (sparse)  (sparse)
+          │     │          │
+          ↓     ↓          ↓
+    Build    SDLC      Comply
+    workflow  workflow  workflow
+    (detached subprocess)
+          │     │          │
+          ↓     ↓          ↓
+    Cleanup  Cleanup   Cleanup
+    (auto)   (auto)    (auto)
+```
+
+The GitLab task monitor polls open issues with the `icdev` label every 20 seconds. It parses issue bodies for `{{icdev: workflow}}` tags and maps them to ICDEV workflow commands. For each unclaimed task, it creates a database claim (deduplication), provisions an isolated worktree with sparse checkout of the target directory, and spawns the mapped workflow as a detached subprocess. Task progress is reported back to GitLab as issue comments. After completion, worktrees are cleaned up and claims updated.
+
+---
+
+## 4. Requirements
+
+### 4.1 Git Worktree Isolation
+
+#### REQ-41-001: Worktree Creation
+The system SHALL create isolated git worktrees in `trees/<task-id>/` with a dedicated branch `icdev-<task-id>` for each task.
+
+#### REQ-41-002: Sparse Checkout
+The system SHALL use git sparse checkout to include only the target directory for each task, minimizing disk usage and checkout time.
+
+#### REQ-41-003: CUI Classification Marker
+Each worktree SHALL include a CUI classification marker file indicating the classification level of the work being performed.
+
+#### REQ-41-004: Worktree Cleanup
+The system SHALL automatically clean up worktrees after workflow completion or failure, removing the working directory and pruning the worktree reference.
+
+### 4.2 GitLab Task Board Integration
+
+#### REQ-41-005: Issue Polling
+The GitLab task monitor SHALL poll open issues with the `icdev` label every 20 seconds (configurable).
+
+#### REQ-41-006: Tag-Based Routing
+The system SHALL parse issue bodies for `{{icdev: workflow}}` tags and route to the corresponding ICDEV workflow: intake, build, sdlc, comply, secure, modernize.
+
+#### REQ-41-007: Task Claim Deduplication
+The system SHALL track claimed tasks in the `gitlab_task_claims` table to prevent duplicate processing of the same issue.
+
+#### REQ-41-008: Progress Reporting
+The system SHALL update GitLab issues with progress comments during workflow execution and final status on completion.
+
+### 4.3 Workflow Execution
+
+#### REQ-41-009: Detached Subprocess Execution
+Workflows SHALL be spawned as detached subprocesses within their respective worktrees, enabling true parallel execution.
+
+#### REQ-41-010: Lifecycle Tracking
+Worktree state (created, active, completed, failed, cleaned) SHALL be tracked in the `ci_worktrees` table.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `ci_worktrees` | Worktree lifecycle tracking — task ID, branch name, path, status (created/active/completed/failed/cleaned), creation time, cleanup time |
+| `gitlab_task_claims` | Issue claim deduplication — issue ID, workflow type, claim status, claimed_at, completed_at, worker ID |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/ci/modules/worktree.py` | Git worktree lifecycle management — create, list, cleanup, status with sparse checkout and CUI markers |
+| `tools/ci/triggers/gitlab_task_monitor.py` | GitLab issue polling, tag extraction, task claiming, workflow spawning |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D32 | Git worktrees with sparse checkout for task isolation | Zero-conflict parallelism, per-task branches, classification markers, minimal disk usage |
+| D33 | GitLab tags `{{icdev: workflow}}` for task routing | Mirrors existing VCS abstraction, uses tag syntax familiar to GitLab users, declarative routing |
+
+---
+
+## 8. Security Gate
+
+**Parallel CI/CD Gate:**
+- Each worktree must have a CUI classification marker matching the project classification level
+- Task claims must be deduplicated — no duplicate processing of the same GitLab issue
+- Worktrees must be cleaned up after workflow completion (no stale worktrees with CUI data)
+- GitLab issue comments must include `[ICDEV-BOT]` identifier to prevent bot loops
+- All workflow spawning must be logged to the audit trail
+
+---
+
+## 9. Commands
+
+```bash
+# Worktree management
+python tools/ci/modules/worktree.py --create --task-id test-123 --target-dir src/ --json
+python tools/ci/modules/worktree.py --list --json
+python tools/ci/modules/worktree.py --cleanup --worktree-name icdev-test-123
+python tools/ci/modules/worktree.py --status --worktree-name icdev-test-123
+
+# GitLab task board monitor
+python tools/ci/triggers/gitlab_task_monitor.py                    # Start monitor (polls every 20s)
+python tools/ci/triggers/gitlab_task_monitor.py --dry-run          # Preview without spawning
+python tools/ci/triggers/gitlab_task_monitor.py --once             # Single poll and exit
+
+# Configuration
+# args/worktree_config.yaml — Sparse checkout, cleanup policy, GitLab polling, tag-to-workflow mapping
+```