CONTRIBUTING.md

@@ -480,11 +480,9 @@ variable, or otherwise falls under an existing category, tag it with a
 `# COMPONENT` header (`<category>/<subcategory>`, e.g.
 `overrides/key-bindings`) and guard it with `__fish_config_op_enabled`. See
 the [README's Minimal Mode section](README.md#minimal-mode) for the full
-category list and toggle semantics, and
-`AGENTS/specs/2026-08-17-opinionated-component-subcategories-design.md` for
-the underlying design. Most new functions are *not* opinionated components
-— only tag something if it fits an existing category; this isn't something
-to force.
+category list and toggle semantics. Most new functions are *not*
+opinionated components — only tag something if it fits an existing
+category; this isn't something to force.
 
 ## Documentation Pipeline
 

completions/tailscale.fish

@@ -236,7 +236,7 @@ end
 # $__fish_config_dir/completions precedes /usr/share/fish/vendor_completions.d,
 # so the vendor file is never sourced and there is nothing to erase. It also
 # executed the tailscale binary at startup. Verified: completion output is
-# byte-identical with and without it. See AGENTS/specs/2026-09-07-startup-latency-design.md D2.
+# byte-identical with and without it.
 
 # Remove any pre-existing completions for the program since we will be handling all of them.
 complete -c tailscale -e

functions/__fish_config_sync_logging.fish

@@ -54,7 +54,7 @@ function __fish_config_sync_logging --description 'Sync C5 logging state: sentin
     # function carried its own inferior copy (tee instead of a PTY, no
     # progress-bar rendering, hard-coded /usr/bin/paru|yay), which fought
     # the canonical generator for the wrapper file on every version-marker
-    # mismatch. See startup-latency-JOB-BRIEF-FINDINGS.md §2.
+    # mismatch.
     #
     # Routed through _fish_source_scoped: both files `return` early on
     # several guard checks, and a sourced `return` exits the *calling*

functions/__fish_help_header.fish

@@ -67,8 +67,8 @@ function __fish_help_header --argument-names name
     # accurate at runtime: in dops.fish it finds the header above
     # `function docker` rather than attributing it to the file stem.
     # One blank separator line is tolerated -- sponge_filter_secrets.fish
-    # is the only file that has one, and JOB-BRIEF-FINDINGS.md records it
-    # so this skip is not mistaken for dead code.
+    # is the only file that has one. Do not remove this tolerance as dead
+    # code.
     set -l lines (string split \n -- (command cat $file))
     set -l pat '^\s*function\s+'(string escape --style=regex -- $name)'(\s|$)'
     set -l start 0

tests/test-guards.fish

@@ -141,10 +141,10 @@ set -e __fish_config_opinionated
 section "cascade: C5 logging is opt-in"
 
 # Uses the REAL __fish_config_op_logging name because the opt-in list lives
-# inside the cascade keyed on it. AGENTS.md: "C5 is opt-in (do not 'fix' this)"
-# -- unset or unrecognized means off, and the master switch cannot enable it.
-# If any of these three fail, that is a real defect: record it in
-# JOB-BRIEF-FINDINGS.md, do not repair the guard.
+# inside the cascade keyed on it. C5 logging is opt-in by design (see
+# docs/fish-config.md's "C5 -- Logging and Capture" section): unset or
+# unrecognized means off, and the master switch cannot enable it. If any of
+# these three fail, that is a regression in the guard itself, not the test.
 set -e __fish_config_op_logging __fish_config_opinionated
 
 __fish_config_op_cascade __fish_config_op_logging

tests/test-help.fish

@@ -202,8 +202,8 @@ function test_help_never_executes_destructive_path
 end
 
 # Functions published in the manual that are exempt from the -h/--help
-# rule. Rationale per entry: AGENTS/specs/2026-09-07-header-driven-help-design.md
-# §4. This array is the ONLY machine-readable copy of the exempt set.
+# rule. Rationale per entry is in the EXEMPT-* comments below. This array
+# is the ONLY machine-readable copy of the exempt set.
 #
 # EXEMPT-A -- shadows a same-named binary, or forwards $argv to one named
 # tool that owns its own --help. Intercepting would hide that tool's help,
@@ -228,8 +228,8 @@ function test_every_user_facing_function_has_help
         # manualtools.parse_functions.
         contains -- "# CATEGORY" (string trim -- $lines); or continue
         # Resolve the real defined name; the file stem can disagree with it
-        # (formerly dops.fish defined `docker` -- see JOB-BRIEF-FINDINGS.md
-        # §1, fixed by splitting it into dops.fish and docker.fish).
+        # (formerly dops.fish defined `docker`, fixed by splitting it into
+        # dops.fish and docker.fish).
         set -l name (string match -rg '^\s*function\s+(\S+)' -- $lines)[1]
         test -n "$name"; or continue
         set name (string trim -c "'\"" -- $name)