From 6a2a19cc9e05c00f10190cf942c2542cb1ae032a Mon Sep 17 00:00:00 2001 From: mika kuns Date: Mon, 10 Aug 2026 10:47:17 +0200 Subject: [PATCH] docs(worker): record the findings store and fix the git-test skip convention --- src/ClaudeDo.Worker/CLAUDE.md | 23 +++++++++++++++++++++++ tests/ClaudeDo.Worker.Tests/CLAUDE.md | 4 +++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/src/ClaudeDo.Worker/CLAUDE.md b/src/ClaudeDo.Worker/CLAUDE.md index e00d3147..e52acd66 100644 --- a/src/ClaudeDo.Worker/CLAUDE.md +++ b/src/ClaudeDo.Worker/CLAUDE.md @@ -27,6 +27,8 @@ Worker/ session-context/token-auth types, WindowsTerminalLauncher (ITerminalLauncher) Refine/ — RefineRunner + RefinePrompt (hub `RefineTask`) External/ — ExternalMcpService + sibling tool classes (always-on MCP for general sessions) + Findings/ — FindingsStore + FindingsStoreLocator: the per-project `.claudedo/` trap store + Git/ — GitExcludeWriter (`.git/info/exclude`) + GitHead, shared by skill seeding and findings Config/ — WorkerConfig Hub/ — WorkerHub, HubBroadcaster Logging/ — LogRingBuffer (30-min window) + BroadcastLogSink (Serilog → footer + overlay) @@ -180,6 +182,27 @@ TaskRunner/TaskMergeService/TaskResetService) **and** every Serilog Warn/Error, filtered to avoid feedback loops). The sink also buffers **all** levels into `LogRingBuffer` for `GetRecentLogs`. +## Findings store + +Each list's working directory gets a `.claudedo/` folder: one markdown file per finding under +`traps/`, plus an `INDEX.md` that `FindingsStore` **rebuilds from disk on every save** (so findings +deleted or renamed by hand self-heal). Findings are traps and invariants only — lasting, +non-obvious, behaviour-changing. A fixed bug is git history, not a finding. + +- **Written** via one `save_finding` tool registered on *both* MCP surfaces: `External/FindingsMcpTools` + (needs a `list` argument; refuses rather than guessing when several lists qualify) and + `Runner/TaskRunFindingsMcpTools` (resolves the list from `TaskRunMcpContextAccessor`). Same slug + overwrites. Both go through `FindingsStoreLocator`, which always resolves to the list's + `WorkingDir` — the **main checkout**, never a worktree copy, or parallel runs would collide on + `INDEX.md`. +- **Read** with plain `Read`; there is deliberately no read tool. `TaskRunner.BuildFindingsPointer` + adds one system-prompt layer naming the index, and only when the index file exists. +- `ListEntity.FindingsTracked` decides whether the folder is committed. When false, `FindingsStore` + writes `/.claudedo/` to `.git/info/exclude` via `GitExcludeWriter` — per-clone, no tracked file + touched. +- `INDEX.md` is read by every run, so it must stay short: `FindingsStore.WarnThreshold` (80) flips + `nearCapacity` in the tool result as a prune signal. + ## Config `~/.todo-app/worker.config.json`: diff --git a/tests/ClaudeDo.Worker.Tests/CLAUDE.md b/tests/ClaudeDo.Worker.Tests/CLAUDE.md index 3971bda9..73777db8 100644 --- a/tests/ClaudeDo.Worker.Tests/CLAUDE.md +++ b/tests/ClaudeDo.Worker.Tests/CLAUDE.md @@ -27,7 +27,9 @@ viewmodel behaviour driven from Worker fakes. - Test classes implement `IDisposable` and create fixtures in constructor - Helper factory methods for entities: `MakeTask()`, `CreateListAsync()`, `SeedListAsync()` - Concurrency tests use `TaskCompletionSource` as gates for deterministic ordering -- Git-dependent tests are conditionally skipped via `Skip = ...` when git is not available +- Git-dependent tests bail out with an early `if (!GitRepoFixture.IsGitAvailable()) return;` at the top + of the method body — a plain `[Fact]`, **not** xUnit's `Skip = ...` and not `SkippableFact` + (that package is not referenced). Such tests report as passed, not skipped, when git is missing. ## Running