Merge pull request #4 from Coding-Dev-Tools/claude/rtk-command-code-pr-review-hftsym

v1.0.1: fix -u flag claims and #1282 citation found by independent audit

Author: Coding-Dev-Tools

AGENTS.md

@@ -33,9 +33,11 @@ When unsure, start raw. Lean context comes from cutting *noise*, not *signal*.
 ## Never default to lossy modes
 
 Plain `rtk <cmd>` keeps the signal — errors, diffs, stack traces, exit codes —
-and strips only noise. `-u` / `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart`
+and strips only noise. `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart`
 (2-line summary) are **lossy** — opt-in only for skimming something huge and
-unimportant, never your default.
+unimportant, never your default. (RTK's own docs still mention a `-u` short form
+for `--ultra-compact`; it was removed upstream and doesn't work — use the long
+flag.)
 
 ## Harness safety — don't let it break the tool call
 

CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this integration are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and this project aims to adhere
 to [Semantic Versioning](https://semver.org/).
 
+## [1.0.1] — 2026-06-30
+
+Follow-up accuracy pass after an independent audit against live upstream
+rtk-ai/rtk sources (commits, issues, and the current README).
+
+### Fixed
+- Removed all references to a `-u` short form of `--ultra-compact`. RTK's own
+  README still documents it, but it was removed from the CLI upstream (it
+  collided with `git push -u`) and was never restored — invoking it fails
+  outright (RTK [#2369](https://github.com/rtk-ai/rtk/issues/2369), open).
+  Every reference now uses the working long form, `--ultra-compact`.
+- Corrected the piped-output citation: RTK
+  [#1282](https://github.com/rtk-ai/rtk/issues/1282) is a correctness bug
+  (RTK can silently substitute its compressed summary for the real content on
+  a non-TTY pipe), not an ANSI/decoration issue as previously described. The
+  ANSI-codes-on-pipe claim now cites the correct issue, RTK
+  [#1409](https://github.com/rtk-ai/rtk/issues/1409) (fixed).
+- Synced SKILL.md's "Compatibility & limitations" section with README.md's —
+  it was missing the "Native tools" and "Hooks on Windows" bullets.
+
 ## [1.0.0] — 2026-06-30
 
 First stable release. The integration is now selective, accurate against the real
@@ -31,8 +51,11 @@ RTK command surface, and hardened for agent-harness use.
   trust the raw exit code for pass/fail; prefer native file/search tools; treat
   `rtk` as optional with a raw fallback when it isn't on PATH.
 - **Compatibility & limitations** documentation covering the Command Code hook
-  gap, exit-code fidelity, piped/ANSI behavior (RTK
-  [#1282](https://github.com/rtk-ai/rtk/issues/1282)), streaming, and the
-  permission surface.
+  gap, exit-code fidelity, piped-output correctness (RTK
+  [#1282](https://github.com/rtk-ai/rtk/issues/1282)), ANSI-on-pipe (RTK
+  [#1409](https://github.com/rtk-ai/rtk/issues/1409)), the non-functional `-u`
+  short flag (RTK [#2369](https://github.com/rtk-ai/rtk/issues/2369)),
+  streaming, and the permission surface.
 
+[1.0.1]: https://github.com/Coding-Dev-Tools/rtk-command-code/releases/tag/v1.0.1
 [1.0.0]: https://github.com/Coding-Dev-Tools/rtk-command-code/releases/tag/v1.0.0

README.md

@@ -42,8 +42,8 @@ command.
 Two design choices keep it net-positive:
 
 - **Signal-preserving by default.** Plain `rtk <cmd>` keeps errors, stack traces,
-  diff hunks, and exit codes and strips only noise; the lossy modes (`-u` /
-  `--ultra-compact`, `-l aggressive`, `rtk smart`) are opt-in for skimming only —
+  diff hunks, and exit codes and strips only noise; the lossy modes
+  (`--ultra-compact`, `-l aggressive`, `rtk smart`) are opt-in for skimming only —
   never the default. If a command fails or RTK can't parse its output, you get the
   full raw text back (tee fallback).
 - **Measure net, not gross.** `rtk gain` reports gross savings; the goal is *net*
@@ -173,11 +173,20 @@ things to know before relying on it:
   isn't guaranteed for every command/version. **For a pass/fail that matters
   (tests, CI gates), trust the raw exit code** — or run the command raw /
   `rtk proxy`. The tiers keep `rtk cargo test` in *plain* mode, never aggressive.
-- **Piped (non-TTY) output.** A harness captures stdout as a pipe. RTK can still
-  emit icons/decoration there (RTK issue
-  [#1282](https://github.com/rtk-ai/rtk/issues/1282)), which wastes tokens or
-  corrupts parsed output. Run anything you'll parse **raw**, and set `NO_COLOR=1`
-  if decoration leaks in.
+- **Piped (non-TTY) output can be silently wrong, not just decorated.** A harness
+  captures stdout as a pipe; RTK can substitute its compressed summary for the
+  real content there — e.g. a redirected `grep` writing a line-count summary
+  instead of the matching lines (RTK issue
+  [#1282](https://github.com/rtk-ai/rtk/issues/1282), a correctness bug). Run
+  anything you'll parse or redirect **raw**. Separately, RTK has also emitted ANSI
+  color codes into piped output before (RTK issue
+  [#1409](https://github.com/rtk-ai/rtk/issues/1409), fixed) — set `NO_COLOR=1`
+  defensively if you see escape codes leak through.
+- **`-u` is not a working flag.** RTK's own README still documents `-u` as a short
+  form of `--ultra-compact`, but it was removed upstream (it collided with
+  `git push -u`) and was never restored — using it fails outright (RTK issue
+  [#2369](https://github.com/rtk-ai/rtk/issues/2369), open). Always use the long
+  form, `--ultra-compact`.
 - **Streaming / follow.** RTK buffers output to filter it, so `-f`, `tail -f`, or
   a growing log can hang. Run those raw.
 - **PATH.** A non-interactive shell may not find `rtk`; the integration treats it

SKILL.md

@@ -13,7 +13,7 @@ compatibility: >-
   normally if it isn't installed.
 metadata:
   author: Coding-Dev-Tools
-  version: "1.0.0"
+  version: "1.0.1"
   homepage: https://github.com/rtk-ai/rtk
 allowed-tools: Bash(rtk:*) Bash(git:*) Bash(cargo:*) Bash(ls:*) Bash(cat:*) Bash(grep:*) Bash(find:*) Bash(diff:*) Bash(docker:*) Bash(kubectl:*) Bash(gh:*) Bash(glab:*) Bash(pnpm:*) Bash(npm:*) Bash(pip:*) Bash(bundle:*) Bash(ruff:*) Bash(tsc:*) Bash(eslint:*) Bash(pytest:*) Bash(go:*) Bash(jest:*) Bash(vitest:*) Bash(dotnet:*) Bash(aws:*) Bash(psql:*) Bash(prisma:*) Bash(wget:*)
 ---
@@ -68,7 +68,7 @@ remember it — and `|` pipes and `<<` heredocs bypass the rewrite.
 - 🟢 **Compress freely** — large, noisy, low-stakes output you skim:
   `rtk ls`, `rtk git status`, `rtk git log`, `rtk docker ps`, `rtk pip list`.
 - 🟡 **Default mode only** — big runs where you need the failures: `rtk cargo
-  test`, `rtk err <cmd>`. Plain `rtk` keeps errors/diffs — don't add `-u`.
+  test`, `rtk err <cmd>`. Plain `rtk` keeps errors/diffs — don't add `--ultra-compact`.
 - 🔴 **Keep full fidelity (run raw)** — diffs/patches you'll apply, JSON or
   `--format` output you'll parse, secrets, small outputs, and files you'll edit
   (use the native Read tool).
@@ -80,7 +80,7 @@ Full tiered table: [references/commands.md](references/commands.md).
 Use the *least* compression that still answers the question:
 
 ```
-raw / native Read  →  rtk <cmd> (keeps signal, default)  →  -u / -l aggressive / rtk smart (lossy, skim-only)
+raw / native Read  →  rtk <cmd> (keeps signal, default)  →  --ultra-compact / -l aggressive / rtk smart (lossy, skim-only)
 ```
 
 Start as far left as the task needs. Escalate compression only for big, boring
@@ -112,14 +112,30 @@ number. Full reference:
 - **Exit codes.** RTK aims to pass the wrapped command's exit code through, but it
   isn't guaranteed for every command/version. When a pass/fail verdict matters
   (tests, gates), trust the raw exit code or re-run raw / `rtk proxy <cmd>`.
-- **Piped output.** The harness captures stdout as a non-TTY pipe; RTK may still
-  emit icons/decoration ([RTK #1282](https://github.com/rtk-ai/rtk/issues/1282)).
-  For anything you'll parse, run raw; set `NO_COLOR=1` if decoration leaks in.
+- **Piped output can be silently wrong, not just decorated.** On a non-TTY pipe
+  RTK can substitute its compressed summary for the real content — e.g. a
+  redirected `grep` writing a line *count* summary instead of the matching lines
+  ([RTK #1282](https://github.com/rtk-ai/rtk/issues/1282), a correctness bug, not
+  a cosmetic one). Run anything you'll parse or redirect **raw**. Separately, RTK
+  has emitted ANSI color codes into piped/non-TTY output before
+  ([RTK #1409](https://github.com/rtk-ai/rtk/issues/1409), fixed); set
+  `NO_COLOR=1` defensively if you see escape codes leak through.
+- **`-u` is not a working flag.** RTK's own README still lists `-u` as a short
+  form of `--ultra-compact`, but it was removed upstream (it collided with
+  `git push -u`) and isn't restored — using it fails outright
+  ([RTK #2369](https://github.com/rtk-ai/rtk/issues/2369), open). Always use the
+  long form `--ultra-compact`.
 - **Streaming.** RTK buffers to filter, so don't wrap `-f`/follow or growing logs.
 - **PATH.** In a non-interactive shell `rtk` may not be found; the integration
   treats it as optional and falls back to raw commands.
+- **Native tools.** Command Code's built-in file/search tools (Read/Grep/Glob)
+  are lossless, give line numbers, and don't pass through RTK — prefer them over
+  `rtk read/grep/find`.
 - **Permissions.** `rtk` (and `rtk proxy`) can execute arbitrary wrapped commands
   — allow-list it deliberately.
+- **Hooks on Windows.** RTK's filters work on Windows, but its auto-rewrite hook
+  has gaps there ([RTK discussion #671](https://github.com/rtk-ai/rtk/discussions/671));
+  `.ps1` stays CRLF per `.gitattributes`.
 
 ## Prerequisite
 

references/commands.md

@@ -5,12 +5,14 @@ output**. The skill is knowing *when* that helps. Three tiers:
 
 - 🟢 **Compress freely** — large, noisy, low-stakes output you only skim.
 - 🟡 **Default mode only** — worth compressing because it's big, but you need the
-  failures: use plain `rtk` (which keeps errors/diffs), never `-u`/aggressive.
+  failures: use plain `rtk` (which keeps errors/diffs), never `--ultra-compact`/aggressive.
 - 🔴 **Keep full fidelity** — run raw; compression risks dropping what you need.
 
-Plain `rtk <cmd>` keeps the signal and strips only noise. `-u` / `--ultra-compact`, `rtk read … -l
+Plain `rtk <cmd>` keeps the signal and strips only noise. `--ultra-compact`, `rtk read … -l
 aggressive`, and `rtk smart` (2-line summary) are lossy — reserve them for
-skimming something huge and unimportant.
+skimming something huge and unimportant. (RTK's own README still lists a `-u`
+short form for `--ultra-compact`; it was removed upstream and doesn't work —
+use the long flag, see Harness notes below.)
 
 ## 🟢 Compress freely (skim-only output)
 | Instead of | Use | Why it's safe |
@@ -31,8 +33,9 @@ skimming something huge and unimportant.
 | any command you only want errors from | `rtk err <cmd>` | errors-only filter |
 | `cargo build`, `tsc`, `eslint`, `ruff`, `clippy` | `rtk cargo build`, `rtk tsc`, `rtk lint`, `rtk ruff check`, `rtk cargo clippy` | keeps diagnostics, drops progress |
 
-Don't add `-u` / aggressive here — you'd risk dropping the failing assertion or
-the `file:line` you need, which forces a re-run that costs more than it saved.
+Don't add `--ultra-compact` / aggressive here — you'd risk dropping the failing
+assertion or the `file:line` you need, which forces a re-run that costs more
+than it saved.
 
 ## 🔴 Keep full fidelity — run raw (no `rtk`)
 | Situation | Do this | Why |
@@ -49,8 +52,16 @@ the `file:line` you need, which forces a re-run that costs more than it saved.
 - **Streaming/follow** (`-f`, `tail -f`, a growing log) → run raw; RTK buffers and can hang.
 - **Exit status** → for a pass/fail verdict that matters (tests, gates), trust the
   command's raw exit code; if unsure RTK preserved it, re-run raw or `rtk proxy`.
-- **Piped output** → RTK may emit icons/decoration over a non-TTY pipe; for anything
-  you'll parse, run raw (set `NO_COLOR=1` if decoration leaks in).
+- **Piped output** → RTK can substitute its compressed summary for the real
+  content on a non-TTY pipe (e.g. a redirected `grep` writing a line-count summary
+  instead of the matches — [RTK #1282](https://github.com/rtk-ai/rtk/issues/1282),
+  a correctness bug). Run anything you'll parse or redirect raw. RTK has also
+  emitted ANSI codes into piped output before
+  ([RTK #1409](https://github.com/rtk-ai/rtk/issues/1409), fixed) — set
+  `NO_COLOR=1` defensively if escape codes leak through.
+- **`-u` doesn't work** → removed upstream (it collided with `git push -u`); using
+  it fails outright ([RTK #2369](https://github.com/rtk-ai/rtk/issues/2369), open).
+  Use `--ultra-compact`.
 - **Native tools** → prefer the built-in file/search tools over `rtk read/grep/find`.
 
 ## Analytics