Repository navigation
docs: trim repository agent guidance - #4246
Conversation
worktrunk-bot
left a comment
There was a problem hiding this comment.
The Network Access trim drops the one carve-out that kept the rule consistent with shipped behavior. wt list statusline does reach the network on every redraw — src/cli/list.rs's after_long_help for it says "A stale CI status cache makes it reach the network for a second or two, so it fits a statusline the host renders in the background" — and the old text named it explicitly as not a synchronous prompt path. What's left is "A shell-prompt hot path never touches the network" in the root file and "A shell prompt must never touch the network" in src/commands/list/AGENTS.md, with the What currently reaches the wire inventory that listed statusline also gone. Read together they say a shipped path is a violation, and this guidance is exactly what gets consulted before someone changes it. Suggestion inline.
Two commands in the trimmed text no longer run as written:
docs/AGENTS.mdkeepstest:sitein the site-check list but drops thenpm --prefix docs exec playwright install webkitprerequisite the old Development section carried.docs/tests/browser-site.test.mjsopens withimport { webkit } from 'playwright', so a first run without that one-time install fails on a missing browser executable with nothing in the file to explain it.benches/AGENTS.md's "or add--chrome" follows a command whose--separator has already been shown.--chromeis awt-perf timelineflag, so appending it there passes it towt listinstead; the old file spelled the command out astimeline --chrome -- list --progressive.
<path>, <full-sha> (tests/AGENTS.md) and <name> (docs/demos/AGENTS.md) now sit outside code fences with no backticks, where Markdown parses them as HTML tags and GitHub's sanitizer drops them — the rendered lines read The file_report/?sha= endpoint and --only or ... --only .. Suggestions inline for both.
Four .config/clawpatch/features/*.json entries still cite root-AGENTS.md headings this PR removes: Hook Output Logs (twice in feat_custom_hook_logs.json, in summary and in the contextFiles reason), Time-of-check vs time-of-use in feat_custom_remove.json, and Benchmarks & Traces; Repository Caching in feat_custom_performance.json — the same class of reference the PR already swept in the two benches/AGENTS.md docstrings. Three of the four have a new home to point at (HookLog in src/commands/process.rs, the # Caching docstring in src/git/repository/mod.rs, benches/AGENTS.md). The TOCTOU rule is the one with none: the general statement — be conservative across the gap between the safety check and the operation; don't force-remove during cleanup — is dropped, and what survives is per-site notes in code (src/commands/hook_plan.rs, src/git/remove.rs). That one is worth keeping in Data Safety on its own merits, not just to fix the citation. Happy to push a commit retargeting the four citations if you want it in this PR.
…ance # Conflicts: # .config/clawpatch/features/feat_custom_hook_logs.json # .config/clawpatch/features/feat_custom_performance.json # .config/clawpatch/features/feat_custom_remove.json # .config/clawpatch/features/feat_custom_repo_cache.json # .github/AGENTS.md # .github/CLAUDE.md # AGENTS.md # CLAUDE.md # benches/AGENTS.md # benches/CLAUDE.md # docs/AGENTS.md # docs/CLAUDE.md # docs/demos/AGENTS.md # docs/demos/CLAUDE.md # plugins/worktrunk/AGENTS.md # plugins/worktrunk/CLAUDE.md # src/commands/AGENTS.md # src/commands/CLAUDE.md # src/commands/list/AGENTS.md # src/commands/list/CLAUDE.md # src/commands/list/collect/mod.rs # src/commands/picker/mod.rs # tests/AGENTS.md # tests/CLAUDE.md
The repository guidance had grown into long implementation histories, especially in the plugin instructions surfaced by #4241. This trims the nine guidance files from 2,769 lines to 380, keeping active contracts and fragile workflows while moving enduring cache semantics into the owning module docstring and updating trace and feature-spec references.
This follows #4245, which moved the guidance into
AGENTS.md. The nineCLAUDE.mdforwarding files remain in place.Verified with the plugin-layout and documentation-sync integration tests,
pre-commit, JSON parsing for the updated feature specifications, andgit diff --check.