Documentation corrections and memories additions by Leonte-Tudor · Pull Request #3 · mareurs/codescout

Leonte-Tudor · 2026-03-29T20:32:38Z

Documentation corrections and memories additions

…ompat) rmcp 1.3.0 marked StreamableHttpServerConfig as #[non_exhaustive], breaking struct literal construction with ..Default::default(). Switch to the builder API (.with_cancellation_token()) which works across all rmcp 1.x versions.

Four-tier cleanup batch after I1 wrap. Tier 1 — Tool-misbehavior promotion (overdue per CLAUDE.md MANDATORY): - docs/issues/bug-tracker.md: added #2 (read_file json_path on array elements), #3 (read_file line range past midpoint), #4 (grep on @tool_ buffer false-negatives). All promoted from F-1/F-2/F-11 in i1-session-friction.md. - i1-session-friction.md Index + per-entry statuses flipped to promoted-to-bug-tracker with bug-tracker.md pointers. Tier 2 — librarian(audit_doc_refs) ran on 5 files. 113 refs / 41 resolved / 58 broken / 13 unknown. This session's shipped artifacts (eval, template, CLAUDE.md additions) scanned clean — only 1 cross-repo ref + 1 notation false-positive flagged. Tier 3 — memory writes (outside repo, not in this commit): ~/.claude/projects/.../memory/concurrent-work-rules.md, eval-before-rewrite-discipline.md, two-concretes-threshold.md + MEMORY.md pointers. Tier 4 — eval expansion 7 → 15 cases: - docs/evals/reconnaissance-trigger.md: added 8 new cases (refactor-shape- named, refactor-internal, compile-error, completion-claim, multi-file integration, test-for-scouted-symbol, plan-status query, architectural decision). - Re-ran empirical baseline against fresh general-purpose subagent. Score: 12/15 (80%, below 87% threshold). 3 FAILs: Case 6 + Case 14 (refactor / multi-task-work unanchored), Case 15 (case-design questionable — subagent routed to brainstorming, defensible). - Iteration log row added. Refactor + plan-context phrases now have TWO concretes per the two-concretes rule (see ~/.claude memory) — v0.2 description rewrite is now earned but deferred to a focused session. Plus — earlier in session but uncommitted: - CLAUDE.md ### Concurrent-Work Rules: graduates W-7 (reflog recovery) + F-13 (reset race) into a permanent project rule. Never git reset to a relative ref during concurrent work; always quote SHA after git reflog in the same command.

…dit notes Plan doc (docs/superpowers/plans/2026-05-17-i1-refactor.md): - Flip all 56 step checkboxes from [ ] to [x] — every task step done. - Append "## Post-execution notes" recording the live-verification outcomes (T-3/T-9/T-10/T-12 each empirically confirmed via /mcp gather + augment cycle on the L1 dogfood goal-tracker), plus a concise F-N mitigation list pointing to docs/trackers/i1-session-friction.md for full detail. Audit doc (docs/trackers/findings-goal-audit.md): - #1 H-8 (evidence_commits anchoring): keep status=open, mark as partial-mitigation. T-9 landed refresh_meta.last_refresh_at + commit_count_since_last (live-verified W-8) but the prompt still lacks the explicit 'fill evidence_commits with commits touching goal paths since refresh_meta.last_refresh_at' instruction. Failure mode partially repeatable; not yet fixed. - #5 S-4 (done reason no gate evidence): keep status=open, mark as partial-mitigation. T-12 + D11 landed the note event with tag=gate_check carrying text + structured evidence (live-verified W-9); the Stop hook in codescout-companion still doesn't read these events for done-branch reason text. - Augmentation params (L2a audit_issues): notes updated to mirror prose, plus 'live-verified' annotation on entries directly validated by W-8/W-9 (H-11, A-3, F-A, Yak S4). - L1 goal-tracker augmentation params refreshed inline (not committed — catalog state): C-3 status flipped to done per kernel-deterministic basis, signal #3 (task_list_complete) met, new progress_log entry, refresh_meta inserted. Honest discipline: a finding is fixed when its concrete failure mode can't repeat. H-8 and S-4 have partial mechanisms now; full fix is a follow-up prompt edit + companion-repo hook edit respectively.

Adds gated debug-only probe tool and resource provider used to measure Claude Code's MCP channel caps. Both register only when CODESCOUT_PROBE=1 is set in the server env. - src/tools/probe.rs: ProbeTool with 8,820-byte sentinel-laden description - src/mcp_resources/probe.rs: ProbeProvider exposing probe://description-test (8,997 bytes) and probe://body-test (19,996 bytes) - src/server.rs / src/tools/mod.rs / src/mcp_resources/mod.rs: gated registration - docs/architecture/mcp-channel-caps.md: empirical findings — both instructions and per-tool description fields truncate at ~2KB, resources not exposed to model, tool results respect MAX_MCP_OUTPUT_TOKENS - docs/superpowers/specs/2026-05-19-mcp-prompt-channel-redesign-design.md - docs/superpowers/plans/2026-05-19-mcp-prompt-channel-redesign.md - Allowlist expansion for prompt-surfaces-consistency test (LHS keywords added by Iron Law #3 in the rewritten source.md)

…ne (defect #1) get_or_start_via_mux inferred mux liveness from the ownership flock alone: a held flock routed straight to the connect-retry loop and, when the socket was unreachable (a wedged/mid-restart mux, or a stale .sock left by a dead holder), exhausted all 5 retries and surfaced a bare ECONNREFUSED/ENOENT via last_err.unwrap() — no respawn, no actionable message. Defect #1 of the 2026-06-11 mux/RocksDB-lock bug. Liveness is now flock AND socket reachability, in a bounded 2-round loop: - happy path unchanged (held flock + healthy socket connects on attempt 0, zero added latency); - held flock + unreachable socket re-arbitrates the flock — freed => the holder died and left a stale .sock => respawn (process::run unlinks it before re-binding); still-held => a live wedged mux => mux_socket_unreachable_error, an actionable RecoverableError naming the lock + socket and routing to fuser. New free helper claim_mux_lock() is the testable liveness arbiter (Some=free, None=held). Defect #3 (direct-fallback collision) was already code-fixed by the single-owner guards in get_or_start; only its live verification remained — bug file updated to record both. Tests: claim_mux_lock_some_when_free_none_when_held (in-process flock, no subprocess — flock(2) conflicts across OFDs even within one process), mux_socket_unreachable_error_names_situation_and_routes_to_holder. Full lib suite 2744 passed, 9 ignored; clippy --all-targets -D warnings clean. Live end-to-end verification still pending (status stays open). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Ran the deferred live e2e against the rebuilt binary (post-c8746b70) on a throwaway rust workspace, isolated from the live kotlin muxes. All four liveness states pass: happy (held flock + healthy socket), fresh spawn (free flock), wedged (held flock + dead socket → actionable mux_socket_unreachable error + fuser hint), and recovery (holder cleared → round-0 respawn). The wedged case also live-confirmed defect #3's production fallback-refusal guard. Defects #1/#2/#3 are now fixed AND verified; status open → fixed. closed: date + archive move deferred to the master ship (Standard Ship Sequence step 4). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Design for bug #3 (prevention) and the cleanup half of #2/#3. Two components: persistence-gated refuse of temp-dir artifact writes into a file-backed catalog (in-memory-catalog tests unaffected, env-var escape hatch); and a batch dry-run prune over doctor-identified dead roots using a "parent-also-gone" derivation rule, reusing the existing guarded prune_dead_root primitive (no new deletion semantics). Ongoing GC lifecycle (missing_since / hide-from-find / auto-prune / status surfacing) explicitly deferred to a follow-up spec. Pruning the real global catalog is a separate, explicitly-approved step. Relates docs/issues/2026-07-17-tmp-probe-artifacts-pollute-global-catalog.md Relates docs/issues/2026-07-17-catalog-dead-rows-no-gc.md Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…he score A query about Neapolitan pizza dough returns five trackers, no score, hints:{}. The response to a query that matches nothing is shape-identical to one that matches at #1. semantic_find (src/librarian/catalog/find.rs:245-278) exits its widening loop on page FULLNESS, not relevance: k starts at max(limit*5,100), doubles to K_CAP=2000, and returns as soon as `all_rows.len() >= target`. store.knn hands back ids only, so the distance never survives line 260 -- ArtifactRow has no score field and nothing downstream can rebuild one. The comment at find.rs:274 already names the condition ("Selective filter starved the page"); the defect is that the caller is never told. Filed with a three-call reproduction, the third of which is the control: the same paraphrase query WITH kind="tracker" returns eight unrelated trackers, and WITHOUT it returns the two genuinely-best artifacts at #1 and #3 -- both kind:bug, which the filter had excluded. Repro re-run after filing and reproduced byte-identically. Also F-41: I hit this and reported "semantic ranking doesn't find these" to the user off that filtered query, with no control. Wrong, and retracted in-session when the user asked for proof. That is the third datapoint for W-26 (a comparison establishes that two groups differ, never which knob names the group) and fires its promote-when -- the third case being my own report rather than a third-party system, hedged in a way that read as careful rather than unverified. Not claimed: semantic search is fine. Retrieval, embedding and the kind filter all work -- a verbatim-title query returns the target at #1 through the same filter.

…ts own review rejected Scouting docs/trackers/run-command-pipeline.md before putting its open design questions to a human found the file's entry point aimed at discarded work. Its section Resume ended "write run_pipeline_inner per strategy A"; the Architectural review rejects Strategy A -- "two pipeline-buffering mechanisms in tree" -- and Tracker updates records "Lean C". The review was appended above the Resume and the Resume was never updated, so the section written to be read first routed an implementer to the design the review threw out. Four repairs, applied through the catalog and following the repo's dated-record convention -- original analysis kept, correction appended above it: Resume rewritten as a six-step order that reads the review before the design surfaces and rules #7 before #3, because Strategy C makes per-stage timeout and per-stage cancellation impossible by construction. That is the one irreversible choice in the set and it deserves to be ruled first, not discovered late. Open item #10 struck VOID: no wired companion hook exists. No hooks.json PreToolUse matcher targets run_command, measured 2026-08-27 and recorded in detect_il3_violation's own doc comment. Concern 3 re-founded on the live gate. Its premise -- the companion hook is command-blind -- is dead, but the conclusion survives and strengthens: detect_il3_violation(command) takes a single string at src/tools/run_command/mod.rs:211, so a command+pipeline schema would blind codescout itself across every MCP client rather than just Claude Code. The stages-XOR-command decision now rests on better evidence than the argument originally written for it, and its stated Confidence: high survives. Concern 1 and 2 line refs re-anchored: inject_tee 145-186 -> 175-228, call site :288 -> :406; run_command_inner is now :279-605. exec_one_stage (open item #9) still returns 0 symbol matches, so Concern 2's prerequisite is unmet. The foreground-exec sub-range is marked as DERIVED from two anchors rather than read, and the "nine dispatch modes" count is marked as NOT re-derived -- both so the next reader does not inherit an inference as a measurement. No design decision was made; all ten surfaces stay open. A note event on the artifact records the same, so the repair is distinguishable from a ruling. Also opens docs/trackers/design-backlog-session-log.md with three entries, two of them corrections to claims this session published before scouting them: design-backlog-session-log:F-1 (med) -- a plan's `status: draft` means two opposite things. get_guide("tracker-conventions") defines it for trackers as "scoped / watching, not yet active"; this repo uses it on plans to mean "shipped, deliberately unarchived while a named residual is open". Triage ranked 2026-05-30-per-request-workspace-pinning.md as stalled at 94 days when its resume tracker says draft "on purpose" and phases 0-3 plus 4a were verified at the bytes 2026-08-28. Both surfaces share one catalog status column and nothing marks which vocabulary a row speaks. design-backlog-session-log:F-2 (low) -- a grep-derived tool count was scoped to the regex's shape, not to the registry. Arc::new\([A-Z] cannot match Arc::new(crate::tools::guide::GetGuide::new()) at src/server.rs:351, so the published split of 20 base + 6 librarian should have been 21 + 5. The total, 26, was right only because it was back-derived from the advertised tool list and then attributed to a split that had not been read. design-backlog-session-log:F-3 (high) -- the Resume finding above, with the class left open: an append-only design document leaves its oldest navigational section last, where the reader is told to start. No guard exists. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Session-Id: 72abb1c0-0e5f-4cfa-8f50-20cb4af5474d

…er than only closing #7 R3 (2026-09-02, marius): design surface #7 ruled Strategy C -- shell-pipeline rewrite with per-stage tee taps, generalizing inject_tee from "tee the penultimate stage" to "tee every stage". A and B stay rejected on Concern 1's and Concern 2's original grounds. Recorded as a CONFIRMATION rather than a trade-off, and the entry says why. When #7 first went to a human it carried a real cost -- "per-stage timeout and per-stage cancellation become impossible by construction" -- and was framed as the one irreversible choice in the set. Both halves were falsified first, on separate days by separate methods: per-stage cancellation withdrawn because no caller can reach it (design-backlog-session-log:F-4, found by naming the caller and the surface), and per-stage timeout shown available in the shell rather than in Rust (design-backlog-session-log:F-7, found by running it -- PIPESTATUS=0 124 0 on a bounded middle stage). C was therefore ruled with no established cost remaining, and Concern 1's positive argument -- one mechanism rather than two -- carried it unopposed. Concern 1's "now harder" list is superseded by R3 and kept as the dated record that argued for it, with the measurement block marked as current. R3 RE-OPENS a surface rather than only closing them. #3 (timeout policy) asked "total or per-stage?" and leaned total partly BECAUSE per-stage was believed impossible. F-7 removed that constraint, so the old lean now rests on nothing but simplicity. Both are implementable. Recorded as task T7 rather than left to inherit a lean whose support is gone -- a falsified constraint does not only unblock the decision it blocked, it can un-justify a neighbouring decision that was quietly leaning on it. The recommendation on #3 is still total, on different grounds: no caller wanting per-stage timeout has been named, which is the same test that retired per-stage cancellation. Total is correct until one is, not because the alternative is impossible. Unblocks #4/#5/#8 (all encoded sequential stages; under C they follow from PIPESTATUS) and #9. Revisit-when unchanged from Concern 1: a streaming-output requirement breaks the single-shell-process assumption; backgrounded pipelines re-open #7, not #2. Confidence high on the choice, medium on one input -- `timeout` on Windows Git Bash is unverified. That bears on #3, not on R3: C's selection does not depend on it, since total timeout works on both platforms via the existing tokio::time::timeout. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Session-Id: 72abb1c0-0e5f-4cfa-8f50-20cb4af5474d

…seven of ten surfaces settled R5 -- #3 timeout policy: total wall-clock, via the existing tokio::time::timeout on the single bash -c child. No per-stage budget in the schema. Under Strategy C this is not new code; it is the mechanism already in run_command_inner applied to one child that happens to contain a pipeline. Ruled on merit rather than on impossibility, which is why #3 was re-opened at all. The original lean rested partly on per-stage being impossible and F-7 falsified that. The standing reason is now the test that retired per-stage cancellation in F-4: no caller wanting per-stage timeout has been named. Only the producer stage realistically runs long and a total budget covers it; a budget on a grep guards against a hang that can only be caused by its producer, which the total budget already catches. Recorded explicitly as a REVERSIBLE no. Per-stage remains reachable at any time as `timeout <n> <stage>` beside the tee tap -- no schema migration, no architectural change, no reopening of #7. Declining a cheap and available capability for want of a caller is a different act from declining an impossible one, and a later reader should not be able to mistake the second for the first. R5 also retires the surface's own wording. #3 reads "each stage gets remaining = total - elapsed", a sequential notion -- the same assumption that made #4, #5 and #8 undecidable as written. Under C there is nothing to decrement: one child, one deadline, all stages inside it. Third instance of that assumption in one surfaces list, and the last. Side effect: the Windows question from F-7 is defused for the default path. `timeout`'s availability on Git Bash was the open caveat; with total ruled, nothing on the default path depends on it and it becomes a precondition only for an opt-in that does not exist. R6 -- #1 schema: top-level `stages: [str]` XOR `command: str`, mutually exclusive. Recorded as a ruling because it had been LEANING since Concern 3 without ever being decided, and a lean is not a decision -- F-3 is this same tracker's record of what an unresolved lean does when a later reader treats it as settled. Re-founded, because Concern 3's stated argument is dead. It reasoned from the companion hook being command-blind; that hook is unwired (no hooks.json PreToolUse matcher targets run_command, measured 2026-08-27). The live argument is stronger: detect_il3_violation takes a single string and runs at src/tools/run_command/mod.rs:211 before resolve_refs, so under a command+pipeline schema it would see stage 0 only and IL-3 enforcement would go blind to pipelines for every MCP client rather than merely for Claude Code. Implementation note the ruling implies: detect_il3_violation must be applied to EVERY stage, not to a joined string. Joining stages to reuse the existing call would re-introduce exactly the blindness R6 exists to prevent, one layer down. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Session-Id: 72abb1c0-0e5f-4cfa-8f50-20cb4af5474d

…he source-gate bug's own caveat R7 settles design surface #6 and prescribes the fix for docs/issues/2026-09-01-source-gate-refuses-the-whole-compound-command.md in one move, because they are the same defect from two directions: that bug is the shipped instance, #6 is the unbuilt one. The rule: a gate's predicate is per-command. Evaluate it per-command, refuse the whole call, and name the offender. For #6 concretely, every stage runs is_dangerous_command, check_source_file_access AND detect_il3_violation; any offending stage refuses the whole pipeline before any stage runs, matching R2's pre-execution refusal and for the same reason. Per-stage @ack_* stays deferred. Substrate check discharges a caveat the bug file left open about itself. It records "the gate source has not been read yet, and this file's claim is therefore about observed behaviour only." Read now: detect_il3_violation mod.rs:211 decomposes -- strip_heredoc_bodies, pipeline_segments is_dangerous_command inner.rs:298 whole string check_source_file_access inner.rs:315 whole string The behavioural inference was right about the what and wrong about the cost. The Fix section's "one splitter, not two" requirement is ALREADY SATISFIED: pipeline_segments (src/util/path_security.rs:1111-1123) splits on &&, ||, ; and newline, quote-safe via split_outside_quotes which tracks quote state across line breaks, and carries its own archived bug for the newline case. strip_heredoc_bodies is at :911. All three gates live in the same module as both helpers, so the repair is two more call sites for a private function already beside them -- no new parser, no plumbing, nothing to keep in sync. CLAUDE.md's Parsers Over a Namespace counts four independent shell gates in this process each separately mis-parsing a heredoc; reusing this one is how that count stops at four. Also narrows the bug's own Root cause. It says "both gates evaluate a per-command property over a per-string scope". IL-3 does decompose and does name its offending segment; what it shares with the source gate is only the all-or-nothing REFUSAL, which the Fix section argues is correct and should stay. So the live defect is narrower than stated: two gates that do not decompose, one of which also does not name. Bug file updated in place with the reading, the narrowing, and the running firing count -- six across two sessions, two of them on this session's own commands. And R6 makes the pipeline case free: stages: [str] arrives already decomposed, so no parser runs at all for a pipeline call and per-stage gating is a for loop over a list that exists. A second, unplanned argument for the XOR schema -- it does not merely keep the gates sighted, it removes the parse they would otherwise need. Out of scope, adopting the bug file's own reasoning: do not run the permitted clauses anyway. Partial execution of a refused command is a worse contract than refusing all of it, because the caller cannot tell which side effects happened. Task list updated: T4, T7 and T8 closed. Seven of the ten design surfaces are now ruled (#1 R6, #2 R2, #3 R5, #4/#5/#8 R4, #6 R7, #7 R3), plus R1 on the shell. Remaining: #9, which is Rust rather than judgement. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Session-Id: 72abb1c0-0e5f-4cfa-8f50-20cb4af5474d

My own test, shipped hours ago, and the same defect class I spent the last hour fixing in someone else's fixture. a_nested_independent_checkout_is_walked_through_not_reported compared relative paths against forward-slash literals without normalising separators. Its sibling four lines away DID normalise. On Unix both pass — '\' never appears in a tempdir path — so the omission was invisible locally and on every ubuntu and macos lane: windows-latest: [".worktrees\\wt-a", "checkout\\inner-wt", "deep\\a\\b\\c\\wt-b"] compared against "checkout/inner-wt" IC-9 again: an assertion whose haystack embeds environment-controlled text — here the platform separator — satisfied by coincidence. The remedy is not remembering the .replace; it is leaving one place where it can be written. rel_slash() is now that place and both callers use it. WHAT THIS COST, and it is a method error not a typo: I had been treating "four Windows lanes failing" as one problem. It was three. 1. LockFileEx access mode 19 tests fixed 6d89a69 2. JSON escape in a fixture 2 tests fixed 52cb093 3. this separator comparison 1 test this commit I only ever opened the `default` lane, where #3 was buried under the other 21. The no-features and local-embed lanes each had exactly ONE failure — this test — and had said so for two runs. That is the same error as the 2-of-21 sample that produced the retracted diagnosis earlier tonight: examine a subset, generalise, be wrong about the rest. Twice in one investigation. Windows-gnu (wine 11.16) is GREEN as of run 33577436407, which verifies #1 and #2. 5 config_propagation tests green locally. Committed by pathspec: another session's 7 bug files, the cluster ledger and a session log are staged in the shared index. Session-Id: 0771abbc-d120-45e6-81a5-292ab6611969

Leonte-Tudor added 3 commits March 29, 2026 15:04

Documentation corrections and memories additions

9e60512

Merge remote-tracking branch 'refs/remotes/origin/master'

5dfd406

Leonte-Tudor closed this Mar 29, 2026

Navigation Menu

Documentation corrections and memories additions - #3

Documentation corrections and memories additions#3
Leonte-Tudor wants to merge 3 commits into
mareurs:masterfrom
Leonte-Tudor:master

Leonte-Tudor commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Leonte-Tudor commented Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant