docs(8a5b-e07b): update CLAUDE.md and ticket CLI reference for archived exclusion

Story 2067-6d1c: document --include-archived flag, archived exclusion
defaults, batch_close_operations, single reduce_all_tickets per invocation,
and --mode=close benchmark option.

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

Author: JoeOakhartNava

CLAUDE.md

@@ -54,7 +54,7 @@ Priority: 0-4 (0=critical, 4=backlog). Never use "high"/"medium"/"low".
 
 ## Architecture
 
-**Ticket system v3 (event-sourced)**: Orphan git branch `tickets` mounted at `.tickets-tracker/`. JSON event files per ticket; Python reducer (`ticket-reducer.py`) compiles state on-demand. Writes are serialized with `fcntl.flock` to prevent concurrent corruption. CLI: `plugins/dso/scripts/ticket <subcommand>` (full reference: `plugins/dso/docs/ticket-cli-reference.md`). **Jira bridge**: `.claude/scripts/dso ticket sync` (incremental default, `--full` to force, `--check` for dry-run). Requires `JIRA_URL`, `JIRA_USER`, `JIRA_API_TOKEN`.
+**Ticket system v3 (event-sourced)**: Orphan git branch `tickets` mounted at `.tickets-tracker/`. JSON event files per ticket; Python reducer (`ticket-reducer.py`) compiles state on-demand. Writes are serialized with `fcntl.flock` to prevent concurrent corruption. CLI: `plugins/dso/scripts/ticket <subcommand>` (full reference: `plugins/dso/docs/ticket-cli-reference.md`). **Archived-ticket exclusion**: All scan operations (`ticket list`, `ticket deps`, `ticket-graph.py` dep lookups) exclude archived tickets by default; `ticket show` always includes them. `ticket list` and `ticket deps` accept `--include-archived` to override. `ticket transition close` uses a single `batch_close_operations` scan (no repeated reducer calls). `ticket-graph.py` uses a single `reduce_all_tickets` call per invocation. **Jira bridge**: `.claude/scripts/dso ticket sync` (incremental default, `--full` to force, `--check` for dry-run). Requires `JIRA_URL`, `JIRA_USER`, `JIRA_API_TOKEN`.
 **Hook architecture**: Consolidated dispatchers (`pre-bash.sh` + `post-bash.sh`). All hooks are jq-free — use `parse_json_field`, `json_build`, and `python3` for JSON parsing. See `plugins/dso/hooks/dispatchers/` and `plugins/dso/hooks/lib/`. **Review gate (two-layer defense-in-depth)**: Layer 1 — `pre-commit-review-gate.sh` (git pre-commit hook); default-deny allowlist from `review-gate-allowlist.conf`; checks review-status + diff hash; formatting-only mismatches self-heal via `ruff format`. Layer 2 — `review-gate.sh` (PreToolUse hook, wraps `review-gate-bypass-sentinel.sh`); blocks `--no-verify`, `-n`, `core.hooksPath=` override, `git commit-tree`, direct `.git/hooks/` writes, direct writes/deletions to `test-gate-status` and `test-exemptions` (only `record-test-status.sh` and `record-test-exemption.sh` are authorized writers). **Test gate (two-layer defense-in-depth)**: Layer 1 — `pre-commit-test-gate.sh` (git pre-commit hook); verifies `test-gate-status` for each staged source file with an associated test (fuzzy matching or `.test-index`). Test dirs: `test_gate.test_dirs` in `.claude/dso-config.conf` (default: `tests/`). `.test-index` format: `source/path.ext: test/path1.ext, test/path2.ext` (one per line; `#` comments ok). **RED marker format**: `source/path.ext: test/path.ext [first_red_test_name]` — `[marker]` marks boundary between GREEN (passing) and RED (not yet implemented) tests; failures at or after marker are tolerated. RED tests must be at end of test file. **TDD workflow**: Add test at end of file + `[test_name]` marker to `.test-index` — e.g., `source/foo.sh: tests/test_foo.sh [test_new_feature]`. Remove marker after implementation passes. **Epic closure**: blocked while any `[marker]` entries remain in `.test-index`. Layer 2 — `review-gate-bypass-sentinel.sh` blocks direct writes/deletions to `test-gate-status` and `test-exemptions`.
 **Validation gate**: `validate.sh` writes state; hooks block sprint/epic if validation hasn't passed. `--verbose` for real-time progress.
 **Agent routing**: `discover-agents.sh` resolves routing categories to agents via `agent-routing.conf`; all fall back to `general-purpose`. See `plugins/dso/docs/INSTALL.md`. **Named-agent dispatch** (via `subagent_type`, defined in `plugins/dso/agents/`):

plugins/dso/docs/ticket-cli-reference.md

@@ -220,21 +220,23 @@ $ .claude/scripts/dso ticket show --format=llm w21-a3f7
 List all tickets.
 
 ```
-.claude/scripts/dso ticket list [--format=llm]
+.claude/scripts/dso ticket list [--format=llm] [--include-archived]
 ```
 
 **Arguments:**
 
 | Argument | Required | Description |
 |---|---|---|
 | `--format=llm` | No | JSONL output — one minified ticket per line (see Output Formats section) |
+| `--include-archived` | No | Include archived tickets in output (default: archived tickets are excluded) |
 
 **Output:** Default: a JSON array of compiled ticket state objects. `--format=llm`: JSONL, one object per line.
 
 **Behavior:**
 
 - Runs the reducer on every ticket directory in `.tickets-tracker/`
 - Hidden directories (names starting with `.`) are skipped
+- Archived tickets are excluded by default; pass `--include-archived` to include them
 - Tickets that fail to reduce produce an error-state entry: `{"ticket_id": "...", "status": "error", "error": "reducer_failed"}`; these are included in the output array rather than causing an early exit
 - Aggregate unresolved bridge alert count is emitted to stderr if non-zero
 
@@ -435,7 +437,7 @@ $ .claude/scripts/dso ticket unlink w21-a3f7 w21-b9c2
 Show the dependency graph for a ticket.
 
 ```
-.claude/scripts/dso ticket deps <ticket_id> [--tickets-dir=<path>]
+.claude/scripts/dso ticket deps <ticket_id> [--tickets-dir=<path>] [--include-archived]
 ```
 
 **Arguments:**
@@ -444,6 +446,7 @@ Show the dependency graph for a ticket.
 |---|---|---|
 | `ticket_id` | Yes | The ticket whose dependency graph to show |
 | `--tickets-dir=<path>` | No | Override the tracker directory (defaults to `.tickets-tracker/`) |
+| `--include-archived` | No | Include archived tickets in the dep graph (default: archived tickets are excluded) |
 
 **Output:** JSON object with the following fields:
 
@@ -466,6 +469,8 @@ Show the dependency graph for a ticket.
 
 **Behavior:**
 
+- Archived tickets are excluded from the dep graph by default; pass `--include-archived` to include them
+- If the queried ticket itself is archived, the command exits with an error unless `--include-archived` is passed: `Error: ticket '<id>' is archived. Use --include-archived to include archived tickets.`
 - Uses a graph cache keyed by content hash of all ticket directories to avoid redundant reducer calls on repeated queries
 - Tombstone-aware: archived/tombstoned tickets count as closed for `ready_to_work` computation
 - Blockers include: tickets with a `depends_on` relation stored in this ticket's directory, and tickets with a `blocks` relation targeting this ticket stored in their own directory
@@ -475,13 +480,16 @@ Show the dependency graph for a ticket.
 | Code | Meaning |
 |---|---|
 | `0` | JSON dep graph printed to stdout |
-| `1` | Ticket not found |
+| `1` | Ticket not found or ticket is archived (without `--include-archived`) |
 
 **Example:**
 
 ```
 $ .claude/scripts/dso ticket deps w21-a3f7
 {"ticket_id":"w21-a3f7","deps":[{"target_id":"w21-b9c2","relation":"blocks"}],"blockers":[],"ready_to_work":true}
+
+$ .claude/scripts/dso ticket deps w21-a3f7 --include-archived
+{"ticket_id":"w21-a3f7","deps":[{"target_id":"w21-b9c2","relation":"blocks"}],"blockers":[],"ready_to_work":true}
 ```
 
 ---
@@ -704,6 +712,55 @@ $ .claude/scripts/dso ticket bridge-fsck --tickets-tracker=/path/to/tracker
 
 ---
 
+### `ticket-benchmark.sh`
+
+Benchmark the ticket list or close command against a seeded ticket system.
+
+```
+plugins/dso/scripts/ticket-benchmark.sh [-n <count>] [--threshold <seconds>] [--mode=list|close]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|---|---|---|
+| `-n <count>` | No | Number of tickets to seed (default: `300`; `0` = use existing repo tickets) |
+| `--threshold <seconds>` | No | Max acceptable wall-clock time in seconds. Defaults: `3s` for n≤300, `10s` for n≤1000, `30s` for n>1000 (list mode); `10s` (close mode) |
+| `--mode=list\|close` | No | Benchmark mode (default: `list`). `list` measures `ticket list` wall-clock time. `close` seeds a mixed population and measures `ticket transition open→closed`. |
+
+**Behavior:**
+
+- When run without `-n` (or with `-n 0`) inside a repo with an initialized ticket system, benchmarks the existing tickets
+- Otherwise creates a temporary git repo, seeds N tickets, and benchmarks that
+- `close` mode seeds a mix of open, in-progress, and archived tickets, then measures a single `ticket transition open→closed` including all `batch_close_operations` work
+
+**Exit codes:**
+
+| Code | Meaning |
+|---|---|
+| `0` | Elapsed time was below the threshold |
+| `1` | Elapsed time exceeded the threshold |
+| `2` | Invalid arguments |
+
+**Output:**
+
+```
+Elapsed: X.XXs for N tickets                                        (list mode)
+Elapsed: X.XXs for closing ticket with N non-archived tickets in tracker  (close mode)
+```
+
+**Example:**
+
+```
+$ plugins/dso/scripts/ticket-benchmark.sh --mode=list -n 300
+Elapsed: 1.23s for 300 tickets
+
+$ plugins/dso/scripts/ticket-benchmark.sh --mode=close -n 100
+Elapsed: 0.87s for closing ticket with 100 non-archived tickets in tracker
+```
+
+---
+
 ## Environment Variables
 
 | Variable | Used by | Description |