librarian: sync missing CLI help blocks in reference docs 📚

Author: EffortlessSteven

.jules/runs/c346971f-d18f-42fe-b66b-eed1583c8dc0/decision.md

@@ -2,19 +2,13 @@
 
 ## Options considered
 ### Option A (recommended)
-Update the documentation to match the current CLI schema using `cargo xtask docs --update`.
-- Fits the `tooling-governance` shard by updating the documentation to reflect reality.
+Update the documentation to match the current CLI schema using `cargo xtask docs --update`, and fix the `cargo xtask gate` failure by updating the excluded run directories.
+- Fits the `tooling-governance` shard by updating the documentation and governance tooling.
 - Aligned with the Builder style and Librarian persona, which focuses on factual doc quality and executable examples.
-- Trade-offs:
-  - Structure: Minimal impact.
-  - Velocity: Immediate fix.
-  - Governance: Ensures CLI help text is consistently represented in the docs.
 
 ### Option B
-Manually patch the Markdown to add the missing tags and text.
-- Overkill when a tooling command already exists to do this programmatically and guarantee sync.
-- More prone to drift or formatting errors.
-- Slower velocity compared to the automated tool.
+Only update the documentation, but leave the `cargo xtask gate` failure alone.
+- Since this shard covers workspace tooling (`xtask/**`), failing tests in `xtask` should be fixed along with the docs.
 
 ## Decision
-Proceed with **Option A**. The `docs/reference-cli.md` had drifted because it lacked `<!-- HELP: -->` blocks for several new commands (diff, context, check-ignore, tools, baseline, handoff). Adding these and running `cargo xtask docs --update` restores synchronization and fixes the factual drift.
+Proceed with **Option A**. The `docs/reference-cli.md` drifted because it lacked `<!-- HELP: -->` blocks. Adding these and running `cargo xtask docs --update` restores synchronization. The `cargo xtask gate` check was also failing due to missing `".jules/runs"` in its list of runtime states, which we fixed to satisfy `cargo test -p xtask`.

.jules/runs/c346971f-d18f-42fe-b66b-eed1583c8dc0/pr_body.md

@@ -1,53 +1,57 @@
 ## 💡 Summary
-Added missing CLI help markers to `docs/reference-cli.md` and synced the document using `cargo xtask docs --update`. This fixes factual drift between the reference documentation and the actual CLI implementation.
+Added missing CLI help markers to `docs/reference-cli.md` and synced the document using `cargo xtask docs --update`. Also fixed `cargo test -p xtask` which was failing because `.jules/runs` was missing from `xtask/src/tasks/gate.rs`.
 
 ## 🎯 Why
-The `docs/reference-cli.md` file was missing `<!-- HELP: <command> -->` tags for several commands: `diff`, `context`, `check-ignore`, `tools`, `baseline`, `handoff`. Because the tags were missing, `cargo xtask docs --check` failed and the documentation was outdated, which violates the `docs-executable` gate profile requiring docs and schemas to match CLI behavior.
+The `docs/reference-cli.md` file was missing `<!-- HELP: <command> -->` tags for several commands: `diff`, `context`, `check-ignore`, `tools`, `baseline`, and `handoff`. Because the tags were missing, `cargo xtask docs --check` failed and the documentation was outdated, which violates the `docs-executable` gate profile requiring docs and schemas to match CLI behavior. Separately, `gate_runtime_guard_keeps_curated_jules_deps_history` failed in CI because `cargo xtask gate` was missing `.jules/runs` from its runtime paths array.
 
 ## 🔎 Evidence
 The `cargo xtask docs --check` command failed initially:
 ```text
 Error: Documentation drift detected in /app/docs/reference-cli.md. Run `cargo xtask docs --update` to fix.
 ```
 
+The test `gate_runtime_guard_keeps_curated_jules_deps_history` failed:
+```text
+thread 'gate_runtime_guard_keeps_curated_jules_deps_history' panicked at xtask/tests/xtask_deep_w74.rs:358:5:
+gate should treat root .jules/runs as runtime state
+```
+
 ## 🧭 Options considered
 ### Option A (recommended)
-- Programmatically add the missing `<!-- HELP: <cmd> -->` tags and run `cargo xtask docs --update`.
-- Fits this repo and shard by ensuring documentation syncs mechanically with code.
+- Programmatically add the missing `<!-- HELP: <cmd> -->` tags and run `cargo xtask docs --update`. Add `.jules/runs` to `xtask/src/tasks/gate.rs`.
+- Fits this repo and shard by ensuring documentation syncs mechanically with code and tests pass.
 - Trade-offs: Structure is minimal, Velocity is high, Governance is enforced via automated tooling.
 
 ### Option B
-- Manually write out the help text into the markdown document.
-- Slower, error-prone, and likely to drift again immediately.
-- Trade-offs: Negative velocity and poor governance.
+- Only update the docs, ignoring the test failure.
+- This would leave CI broken, which is unacceptable.
 
 ## ✅ Decision
-Chose Option A. By placing the correct marker pairs and regenerating the file, the workspace tool automatically injects the latest text and passes the `--check` gate.
+Chose Option A. By placing the correct marker pairs and regenerating the file, the workspace tool automatically injects the latest text and passes the `--check` gate. Fixing the test ensures the full `xtask` test suite passes.
 
 ## 🧱 Changes made (SRP)
 - `docs/reference-cli.md`
+- `xtask/src/tasks/gate.rs`
 
 ## 🧪 Verification receipts
 ```text
-$ cargo xtask docs --check
-Error: Documentation drift detected in /app/docs/reference-cli.md. Run `cargo xtask docs --update` to fix.
-
-$ cargo xtask docs --update
-Updated /app/docs/reference-cli.md
-
 $ cargo xtask docs --check
 Documentation is up to date.
 
+$ cargo test -p xtask
+test result: ok. 36 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 5.83s
+
 $ cargo fmt -- --check
 $ cargo clippy -- -D warnings
+$ cargo check
 ```
 
 ## 🧭 Telemetry
-- Change shape: Docs update
-- Blast radius: `docs/reference-cli.md` only. No API, IO, or schema impact.
-- Risk class: Low + why: Only touches markdown text documentation via established xtask mechanisms.
-- Rollback: Revert markdown changes.
-- Gates run: `cargo xtask docs --check`, `cargo fmt -- --check`, `cargo clippy`
+- Change shape: Docs update & minor test fix
+- Blast radius: `docs/reference-cli.md` and `xtask/src/tasks/gate.rs`. No API, IO, or schema impact.
+- Risk class: Low + why: Only touches markdown text documentation via established xtask mechanisms and fixes a test array.
+- Rollback: Revert changes.
+- Gates run: `cargo xtask docs --check`, `cargo test -p xtask`, `cargo fmt -- --check`, `cargo clippy`, `cargo check`
 
 ## 🗂️ .jules artifacts
 - `.jules/runs/c346971f-d18f-42fe-b66b-eed1583c8dc0/envelope.json`

.jules/runs/c346971f-d18f-42fe-b66b-eed1583c8dc0/receipts.jsonl

@@ -1,3 +1,5 @@
 {"command": "cargo xtask docs --check", "status": "failed", "output_fragment": "Error: Documentation drift detected in /app/docs/reference-cli.md"}
 {"command": "cargo xtask docs --update", "status": "success", "output_fragment": "Updated /app/docs/reference-cli.md"}
 {"command": "cargo xtask docs --check", "status": "success", "output_fragment": "Documentation is up to date."}
+{"command": "cargo test -p xtask --test xtask_deep_w74", "status": "failed", "output_fragment": "gate_runtime_guard_keeps_curated_jules_deps_history ... FAILED"}
+{"command": "cargo test -p xtask --test xtask_deep_w74", "status": "success", "output_fragment": "gate_runtime_guard_keeps_curated_jules_deps_history ... ok"}

.jules/runs/c346971f-d18f-42fe-b66b-eed1583c8dc0/result.json

@@ -1,6 +1,7 @@
 {
   "outcome": "success",
   "files_changed": [
-    "docs/reference-cli.md"
+    "docs/reference-cli.md",
+    "xtask/src/tasks/gate.rs"
   ]
 }

xtask/src/tasks/gate.rs

@@ -78,6 +78,7 @@ const TRACKED_AGENT_RUNTIME_PATHS: &[&str] = &[
     ".jules/transcripts",
     ".jules/runtime",
     ".jules/tmp",
+    ".jules/runs",
 ];
 
 fn ensure_no_tracked_agent_runtime_state() -> Result<()> {