## Currently investigating:
- (none)

## Researched / Ready for implementation:
- Workspace lint inheritance rollout: Add `[lints] workspace = true` to all crates (currently only anthropic-async has it). Then add xtask policy check to `verify` command that ensures all workspace members have lint inheritance enabled. Prevents drift when new crates are added. Reference: OpenAI Codex repo has 100% lint inheritance across 58 crates.

## Blocked / Sequenced:
These items have dependencies and should be done in order.

### Blocked by: Configuration system
- SQLite migration for thoughts (see "To plan/design" section)

### Blocked by: SQLite migration
- Token tracking with tiktoken instead of KB for thoughts files. Research completed:
  - tiktoken-rs already in workspace (used by gpt5-reasoner with o200k_base encoding)
  - `write_document()` is trivial: replace `content.len()` with `count_tokens(content)`
  - `list_documents()` is the problem: currently uses `meta.len()` (filesystem metadata). To get tokens, would need to read+tokenize every file (~80-300ms for 50 files vs ~5ms for metadata-only)
  - Sidecar caching approach considered but adds complexity that SQLite eliminates
  - DEFERRED: With SQLite, token count becomes a column computed on write, queried on list. No caching needed.
  - Research doc: `thoughts/completed/2026-01-10_to_2026-01-30_google_supported_schema/research/tiktoken_file_tracking_migration.md`

- agentic_logging integration for linear-tools and pr_comments. Research completed:
  - Only `linear-tools` needs logging from the linear family (linear-schema and linear-queries are libs without tool methods)
  - `pr_comments` also needs logging (3 tools) — NOW IMPLEMENTED with duplicated ToolLogCtx
  - Recommended pattern: simple function-call helper (not ToolLogCtx context pattern)
  - DEFERRED: agentic_logging's file-based primitives (LogWriter, JSONL, day-bucketing, fd-lock) will be obsolete once thoughts moves to SQLite. The ToolCallRecord schema survives but storage layer changes completely.
  - CLEANUP NEEDED: ToolLogCtx is duplicated in `coding-agent-tools/src/logging.rs` and `pr-comments/src/logging.rs`.
    When refactoring, move ToolLogCtx to agentic_logging with parameterized server name.
  - Research docs: `thoughts/completed/2026-01-10_to_2026-01-30_google_supported_schema/research/agentic_logging_integration_audit.md` and `agentic_logging_extraction_analysis.md`

## To plan/design:

### `gwt-worktree` follow-up work

- TODO(3): Consider a CLI/tooling layer on top of `crates/infra/gwt-worktree/` for direct user-facing worktree operations.
- TODO(3): Consider a pure-gix backend alternative if we later want to reduce libgit2 coupling while preserving the current plan/execute API.

### Optional config escape hatch for project-wide orchestrator session listing

- TODO(3): Consider an `agentic.toml` boolean to opt orchestrator session browsing into project-wide listing instead of launch-directory scope. Deferred for now because it feels like scope creep and probably not worth this migration PR.

### SQLite migration for thoughts (blocked by: config system, which is mostly done now)

- Current file-based structure (thoughts/{branch}/ with research/, plans/, artifacts/, logs/) would become database tables. Key questions:
  - Schema design: documents table, tool_calls table, branches table?
  - Sync strategy without git (SQLite replication? export/import?)
  - Config/storage unification across entire codebase
  - What happens to agentic_logging crate? Becomes thin wrapper over DB writes?
  - I'm also considering postgres. Some deeper thoughts around postgres vs sqlite and the full agent setup come to mind.
- Note: The "Unified Canonical Identity System" for references (full repos.json migration) should be folded into this work - canonical identity becomes a DB column with unique index, repos.json deleted entirely.

### Thoughts setup experience + v1 removal (after config system - I think this is done now)
- Re-look at the brand-new thoughts setup experience. How can we make that more streamlined?
- Should enforce/require a primary "thoughts" repo, and have an initial setup command that populates it with everything it needs.
- Currently initializes the old v1 config - that's not used anywhere anymore.
- Should completely get rid of v1 and all the logic related to it. No need for backwards compatibility when user count is low.

### Discord search tool (ENG-392)
- Search tool for Discord context, similar to Linear search tool. Not the same as glittercowboy/discord-mcp (server admin).
- Probably only needs one tool for searching, maybe a second for reading context around results.
- Could bundle with Linear tools in same agent.

### Wire live opencode command-path integration tests into CI

- TODO(1): `crates/services/opencode-rs/tests/integration.rs:6-18,53-55,153-156` and `apps/opencode-orchestrator-mcp/tests/integration.rs:24-26,125-128` show the live tests are both `#[ignore]`-gated and require `OPENCODE_INTEGRATION` / `OPENCODE_ORCHESTRATOR_INTEGRATION`, while `.github/workflows/ci.yml:71-87` and `.github/workflows/ci.yml:223-238` never set those env vars or pass `--ignored`. Result: CI never exercises the real `POST /session/{id}/command` path, which is how the recent `messageID` validator regression in `opencode-rs` slipped through. Decide where these should run (probably nightly), wire the env vars in, and run the ignored tests there.

### Decide on idempotency semantics for opencode-rs command dispatch retries

- TODO(1): `crates/services/opencode-rs/src/http/messages.rs:94-99` (`command()`) currently uses `post_json_with_retry`, but upstream opencode 1.14.19 does not dedupe by `messageID` (`references/anomalyco/opencode@r-refs~2ftags~2fv1.14.19/packages/opencode/src/session/prompt.ts:940-942,1276-1293`, `packages/opencode/src/session/projectors.ts:83-96`). A retry fired after server-side execution has begun (e.g., connection dropped mid-response) can cause duplicate command execution. Decide between (a) disabling transport retries on `/session/{id}/command` to fail fast, (b) implementing a real server-side idempotency contract upstream, or (c) accepting at-least-once semantics and documenting it. Currently the code path is documented but unchanged.

## To classify/investigate:

- TODO(2): ENG-762 follow-up — add Node/NAPI abort-signal propagation so JS callers can drive `ToolContext` cancellation instead of always using `ToolContext::default()`.
- TODO(2): ENG-762 follow-up — define mutation-tool cancellation semantics beyond local post-commit monitoring, including whether/when remote rollback is possible.
- TODO(2): ENG-762 follow-up — have orchestrator monitoring call OpenCode `sessions().abort()` once the API contract and side effects are clearly defined.
- TODO(2): ENG-762 follow-up — adopt cancellation for `cli_just_search` if the subprocess helper shape remains stable.
- TODO(2): ENG-762 follow-up — adopt cancellation for remaining blocking-style tools such as `thoughts_get_repo_refs` and `review_diff_snapshot`.
- TODO(2): ENG-762 follow-up — add Windows-specific process-group/process-tree handling for `claudecode-rs`.
- TODO(2): ENG-762 follow-up — revisit `[lints] workspace = true` rollout for `agentic-tools-core`, `agentic-tools-mcp`, `claudecode`, and `gpt5_reasoner` after unrelated clippy cleanup is separated from cancellation work.

### CLAUDE.md cargo commands → just commands
The xtask autogen system generates raw cargo commands in per-crate CLAUDE.md files (`crates/meta/xtask/src/claude.rs:183-196`), but our primary agents don't use bash and the root CLAUDE.md already documents the preferred `just crate-*` commands. This creates inconsistency where per-crate docs show cargo commands while root docs show just commands. Update xtask to generate:
- `just crate-check <crate>` instead of `cargo fmt -p ... && cargo clippy -p ...`
- `just crate-test <crate>` instead of `cargo test -p ...`
- `just crate-build <crate>` instead of `cargo build -p ...`

Affects 32 CLAUDE.md files. Low effort change in xtask, automatic propagation via `just xtask-sync`.

### Test-support crate consolidation
EnvGuard (RAII environment variable isolation) is duplicated across 6 crates:
- `agentic-config/src/test_support.rs` (pub(crate), impl AsRef<Path>)
- `anthropic-async/src/test_support.rs` (pub, with_set/with_removed closures, #[must_use])
- `gpt5-reasoner/src/test_support.rs` (pub(crate), includes DirGuard)
- `exa-async/src/test_support.rs` (pub, minimal)
- `linear-tools/src/test_support.rs` (pub, plus JSON fixture builders)
- `agentic-logging/src/lib.rs:206-217` (inline, weaker variant)

Consider creating `crates/infra/test-support/` with unified EnvGuard adopting anthropic-async's pattern (closure API, #[must_use]) and optionally DirGuard from gpt5-reasoner. Domain-specific fixtures (linear-tools JSON builders) should remain local.

Existing TODO(2) at `agentic-config/src/test_support.rs:23-25` acknowledges this.

### References cleanup commands (follow-up work after ENG-454)
The core ENG-454 issues have been addressed. Remaining follow-up work:

**1. `references remove` doesn't clean up repos.json**
- Current: Only removes from local `.thoughts/config.json`, not from `~/.thoughts/repos.json`
- Mitigation: `references remove` now suggests running `doctor --fix` to clean up stale mappings
- Future: Consider `unmap`/`purge` commands for explicit repos.json cleanup (deferred)

**2. Clone directory cleanup**
- `doctor --fix` removes mappings but does NOT delete clone directories (by design)
- Users must manually `rm -rf` stale clone directories
- Future: Consider `--prune-dirs` flag for explicit directory cleanup (deferred)

**COMPLETED in ENG-454:**
- ✓ `doctor` error messages now correctly suggest `doctor --fix` (not `sync`)
- ✓ `doctor --fix` handles NotADirectory, NotAGitRepo, OriginMismatch (auto_managed only)
- ✓ `doctor --fix` deterministically consolidates duplicate canonical identities
- ✓ `references remove` uses canonical identity matching (SSH/HTTPS variants work)
- ✓ Same-repo-name collisions prevented by hierarchical clone paths

### Orchestrator-style agents (ENG-460) - blocked by: config + SQLite
- I need to have a way to run higher-level orchestrator-style agents. I'm thinking like where I could just press tab in opencode to
  switch to an "orchestrator" agent that can then spawn an entire opencode agent with a command. We could even just start with only
  supporting `research`. Where it can spawn the entire research loop ad hoc, get the response, and then read the research document once
  it's done. Or even better, we figure out how to make the setup look good as an enum of `research` `create_plan_init`,
  `create_plan_final`, and `implement_plan`. We'll have to support resuming existing sessions to support create_plan_final. Maybe opencode
  exposes some ID that we can use for resuming. Then we'll have to implement some type of automatic insertion of user message when
  `implement_plan` (or others) are running, to be able to get like some summarized version written to an artifact or something of progress
  made so far before the limit is up. Okay, so I'm sorta thinking it needs multiple tools? One for a session. One for resuming a session.
  And maybe one for searching sessions or something? That last one isn't thought out yet and maybe shouldn't be included in the original.
  But the "naive" approach could just be listing the last X sessions to get IDs and such? That would be doable and useful without much
  extra thought. Then the enum for type of response, which are tied to the commands, and in addition to the enum of types of commands
  there should be a "no-template" option or something. For scenarios like the last turn of create_plan_final where it asks if you want to
  persist it and really all you need to say is "yes". I think the same style of functionality as claude code, where the final assistance
  response is returned back, makes sense to me. We can probably continue that trend. I think all of our "final assistant responses" are
  already setup to be clear of what happened and such. Status: needs verification.
- Ambient git repo detection failures should be handled consistently across tool registries (TODO(2)):
  avoid empty owner/repo fallbacks; prefer clear, fast errors and consider a shared override mechanism.
- README.md could use a huge refresh. We'll be at the point where we can have all-inclusive instructions for setting up for any repo soon. Would be a lot better than just "Here is a list of tools" if we mentioned how they are used and what they are for and how to do the entire setup.
- a command for basically "Are you sure you're finished? What did you do or not do?" that can be run at the end of implement_plan. I find myself consistently asking this as a quick check. Using language like "reflect deeply on everything you did, did you cut any corners or make any changes to the plan?" etc. I also tend to need to say "Don't make any edits or anything, I just want to know the answer" to make sure claude doesn't get fix hungry.

- Just tool improvements (two separate issues):
  - Cache/refresh: just commands need to refresh when justfiles change. Right now they only populate based on when they first launch? Not sure of specifics - could be caching is broken.
  - Output format (ENG-344): agent-wrap.sh truncates output, agent can't see actual errors. Desire to potentially handle output format in the just tool itself instead of the bash wrapper - needs more thought on implications.
- Pagination UX needs improvement across tools. pr_comments and just_execute both need pagination support, and the explicit pagination
instructions ("Showing X out of Y, call again for more") should be solved elegantly at the framework level rather than per-tool. The ls
tool has good phrasing but pr_comments only partially ported that style. Consider: should agentic-tools-utils pagination module provide
a standard output formatter? Or should pagination messaging be part of the MCP response schema itself?
- Check to see if I'm setting server-specific timeouts for the various MCP servers of if the timeout is up to the client.
- PRs merged from release-plz don't automatically run
`xtask-sync` and thus out of date things aren't really caught
until the next cycle of PR. That's obviouslly unideal but I'm
unsure what the best fix would be.
- Need way to select different branches for references. For the
  time latest branch isn't the same as latest release of a
project. Either than or tooling for interacting with cargo cache
in a clean/streamlined abstraction. Probably both would be ideal
long term.

- TODO(2): `thoughts`: `status --detailed` flag is accepted but currently has no effect (unused parameter in `apps/thoughts/src/commands/status.rs`).
- TODO(2): `thoughts`: `sync` code comment claims "repository-aware sync" but behavior does not filter by repo (see `apps/thoughts/src/commands/sync.rs`).
- TODO(2): `agentic-bin`: missing `[package.metadata.binstall]` unlike other shipped binaries (see `apps/agentic/Cargo.toml`).
- TODO(2): `opencode-orchestrator-mcp`: stale "five tools" comment despite six tools being registered (see `apps/opencode-orchestrator-mcp/src/main.rs` vs registry).

## To validate:
- ENG-397: Linear MCP should return issue URL after creation. May already be implemented - needs verification.

## Old (probably delete):
- (none)
