refactor: simplify ParseClauseSegment verb-extraction loop

Drop the `quotedFirstVerb` flag and gate the walk solely on `firstVerb is
not null` — the QuotedString branch no longer needs a sentinel because
it falls through with `firstVerb == null` and the loop short-circuits.

Cache the inner `HashSet<string>` from `FlagsWithValue` once into
`flagsForVerb` instead of re-hashing `firstVerb` on every flag-token
iteration. Inline the `=`-position scan via a single `IndexOf('=')` call
so the `--flag=value` short-circuit doesn't traverse the flag string
twice; this lets us delete the now-unused `StripEqualsValue` and
`HasInlineEqualsValue` helpers.

Trim the 20-line block comment at the top of `ParseClauseSegment` to
just the load-bearing invariants (FileVerb carveout + ordering with
flag-with-value consumption). Drop mid-loop comments that narrate the
control flow. Add a 4-element capacity hint to `verbTokens` to avoid
the first realloc on the typical case.

In `BashVerbs.cs`, revert the `FileVerbs` remarks paragraph that leaked
parser usage details and rewrite the `IsVerbLikeToken` doc to capture
the WHY of the strict allow-list (vs. negation-of-LooksLikePath)
without re-listing all the rejection categories.

All 394 tests still pass; no behavior change.

Author: Aaronontheweb

src/ShellSyntaxTree/Internal/Bash/Parsing/BashCommandParser.cs

@@ -769,58 +769,38 @@ private static ClauseResult ParseClauseSegment(
             return ClauseResult.Empty();
         }
 
-        // ---- Verb-chain extraction (Issue #27 greedy heuristic, SPEC §6.1) ----
-        //
-        // Walk consecutive verb-like tokens from the start of the clause,
-        // transparently consuming flag-with-value pairs owned by the first
-        // verb. Stop at:
-        //   - the first non-Word token (operator, quoted string, opaque, ...)
-        //   - a flag that is not in FlagsWithValue[firstVerb]
-        //   - a Word that does not match IsVerbLikeToken
-        //
-        // Two structural carveouts preserve existing per-verb semantics:
-        //   - A QuotedString at index 0 (e.g. `"git" push`) becomes a
-        //     1-token verb chain; the walk does not continue. Bash semantics
-        //     say the quoted command name is just a verb identity carrier;
-        //     downstream args are arg-list material.
-        //   - When firstVerb is a known FILE verb (cat, ls, bash, cd, chmod,
-        //     grep, find, …) we still run the flag-with-value consumption
-        //     so the value of a `-C /repo` style pair picks up IsPath via
-        //     FlagValueIsPath — but the verb chain stops at the first verb
-        //     token. This keeps per-verb path-arg classification firing for
-        //     bare-name targets (`cat README`, `bash myscript`, `ln src dst`).
+        // Verb-chain extraction per SPEC §6.1. The FileVerb carveout is
+        // load-bearing: downstream per-verb positional-arg classification
+        // depends on the verb chain staying 1 token for FILE verbs so
+        // bare-name targets like `cat README` still surface as Args with
+        // IsPath=true. Flag-with-value consumption must run *before* the
+        // carveout gate so `tar -C /repo` still attributes IsPath to /repo.
         var consumedFlagValueIndices = new HashSet<int>();
-        var verbTokens = new List<string>();
+        var verbTokens = new List<string>(4);
         var verbPositions = new HashSet<int>();
 
         var firstToken = segment.Tokens[0];
         string? firstVerb = null;
-        var quotedFirstVerb = false;
         if (firstToken.Kind == BashTokenKind.Word && !IsFlagWord(firstToken))
         {
             firstVerb = firstToken.Value;
+            verbTokens.Add(firstVerb);
+            verbPositions.Add(0);
         }
         else if (firstToken.Kind == BashTokenKind.QuotedString)
         {
-            firstVerb = firstToken.Value;
-            quotedFirstVerb = true;
-        }
-
-        if (firstVerb is not null)
-        {
-            verbTokens.Add(firstVerb);
+            // Quoted command (`"git" push`): emit a 1-token chain and skip
+            // the walk. Bash semantics treat the quoted form as a verb
+            // identity carrier; remaining tokens are arg-list material.
+            verbTokens.Add(firstToken.Value);
             verbPositions.Add(0);
         }
 
+        BashVerbs.FlagsWithValue.TryGetValue(firstVerb ?? string.Empty, out var flagsForVerb);
         var fileVerbCarveout = firstVerb is not null
-            && !quotedFirstVerb
             && BashVerbs.FileVerbs.Contains(firstVerb);
 
-        var hasFlagsTable = firstVerb is not null
-            && !quotedFirstVerb
-            && BashVerbs.FlagsWithValue.TryGetValue(firstVerb, out _);
-
-        if (firstVerb is not null && !quotedFirstVerb)
+        if (firstVerb is not null)
         {
             for (var i = 1; i < segment.Tokens.Count; i++)
             {
@@ -832,42 +812,39 @@ private static ClauseResult ParseClauseSegment(
 
                 if (IsFlagWord(t))
                 {
-                    // Flag-with-value consumption runs whether or not the
-                    // FileVerb carveout is active: tar / curl / wget / git
-                    // all use this path to push the value-token into
-                    // FlagValueIsPath territory.
-                    if (hasFlagsTable
-                        && BashVerbs.FlagsWithValue[firstVerb].Contains(StripEqualsValue(t.Value))
-                        && i + 1 < segment.Tokens.Count
-                        && (segment.Tokens[i + 1].Kind == BashTokenKind.Word
-                            || segment.Tokens[i + 1].Kind == BashTokenKind.QuotedString))
+                    if (flagsForVerb is null)
                     {
-                        if (HasInlineEqualsValue(t.Value))
-                        {
-                            // `--flag=value` is a single token; let
-                            // arg-extraction split on `=`. Stop the walk.
-                            break;
-                        }
+                        break;
+                    }
 
-                        consumedFlagValueIndices.Add(i);
-                        consumedFlagValueIndices.Add(i + 1);
-                        i++; // skip the value too on the next iteration
-                        continue;
+                    var eq = t.Value.IndexOf('=');
+                    var flagKey = eq > 0 ? t.Value.Substring(0, eq) : t.Value;
+                    if (!flagsForVerb.Contains(flagKey))
+                    {
+                        break;
                     }
 
-                    // Plain flag (no value consumption) → stops the walk.
-                    break;
-                }
+                    if (eq > 0)
+                    {
+                        // `--flag=value` is a single token; arg-extraction
+                        // splits on `=`. Stop the walk here.
+                        break;
+                    }
 
-                // Non-flag Word past index 0:
-                if (fileVerbCarveout)
-                {
-                    // FileVerb 1-token carveout: don't extend the chain,
-                    // but the preceding flag-with-value consumption stays.
-                    break;
+                    if (i + 1 >= segment.Tokens.Count
+                        || (segment.Tokens[i + 1].Kind != BashTokenKind.Word
+                            && segment.Tokens[i + 1].Kind != BashTokenKind.QuotedString))
+                    {
+                        break;
+                    }
+
+                    consumedFlagValueIndices.Add(i);
+                    consumedFlagValueIndices.Add(i + 1);
+                    i++;
+                    continue;
                 }
 
-                if (!BashVerbs.IsVerbLikeToken(t))
+                if (fileVerbCarveout || !BashVerbs.IsVerbLikeToken(t))
                 {
                     break;
                 }
@@ -958,20 +935,6 @@ private static bool IsFlagWord(BashToken token)
         return token.Value.Length > 0 && token.Value[0] == '-';
     }
 
-    /// <summary>
-    /// For an equals-form flag like <c>--output=file.txt</c>, return the
-    /// flag portion (<c>--output</c>) so the FlagsWithValue table lookup
-    /// matches. For plain flags returns the input unchanged.
-    /// </summary>
-    private static string StripEqualsValue(string flag)
-    {
-        var eq = flag.IndexOf('=');
-        return eq > 0 ? flag.Substring(0, eq) : flag;
-    }
-
-    private static bool HasInlineEqualsValue(string flag) =>
-        flag.IndexOf('=') > 0;
-
     // ---------------------------------------------------------------- args + redirects
 
     /// <summary>

src/ShellSyntaxTree/Internal/Bash/Verbs/BashVerbs.cs

@@ -43,18 +43,8 @@ internal static class BashVerbs
     /// modulo per-verb overrides in SPEC §7. SPEC §6.3.
     /// </summary>
     /// <remarks>
-    /// <para>
     /// CWD verbs are also FILE verbs (their target is a path), included
     /// here for closure so a single membership check suffices.
-    /// </para>
-    /// <para>
-    /// Issue #27: this set ALSO acts as the "stop at 1-token verb chain"
-    /// carveout in <c>BashCommandParser.ParseClauseSegment</c>. The
-    /// greedy verb-chain heuristic would otherwise over-extract bare-name
-    /// targets (<c>cat hello</c>, <c>bash myscript</c>, <c>ln src dst</c>)
-    /// into the verb chain and lose the per-verb path-arg classification
-    /// downstream consumers depend on for zone-gate evaluation.
-    /// </para>
     /// </remarks>
     internal static readonly HashSet<string> FileVerbs =
         new(StringComparer.OrdinalIgnoreCase)
@@ -130,29 +120,22 @@ internal static readonly IReadOnlyDictionary<string, HashSet<string>>
         };
 
     /// <summary>
-    /// Issue #27 / SPEC §6.1: returns <c>true</c> when <paramref name="token"/>
-    /// has the shape of a CLI subcommand verb — a bare lowercase identifier
+    /// SPEC §6.1: returns <c>true</c> when <paramref name="token"/> has the
+    /// shape of a CLI subcommand verb — a bare lowercase identifier
     /// containing only ASCII letters, digits, hyphens, dots, and underscores.
     /// Used to terminate the greedy verb-chain walk at the first token that
     /// looks like a value rather than another subcommand.
     /// </summary>
     /// <remarks>
-    /// <para>
-    /// The shape predicate is intentionally strict: leading ASCII lowercase
-    /// letter, then only <c>[a-z0-9._-]</c>. This rejects flags (start with
-    /// <c>-</c>), env-var refs (<c>$</c>), path-shapes (<c>/</c>, <c>\</c>,
-    /// <c>~</c>), URLs (<c>:</c>), glob metachars (<c>*</c>, <c>?</c>,
-    /// <c>[</c>), uppercase-starting tokens (user-named identifiers like
-    /// migration names), and tokens that begin with a digit (numeric
-    /// modes / version literals). It tolerates real subcommand shapes
-    /// (<c>my-pod</c>, <c>s3</c>, <c>apt-get</c>, <c>python3.11</c>).
-    /// </para>
-    /// <para>
-    /// Quoted strings are not verb-like even when their inner value would
-    /// pass — quoting signals the user wanted the bytes as a literal
-    /// value. The walk also rejects empty tokens and tokens longer than
-    /// 64 characters as a defensive bound against pathological inputs.
-    /// </para>
+    /// Strict allow-list (leading <c>[a-z]</c>, body <c>[a-z0-9._-]</c>)
+    /// over the more obvious negation-of-LooksLikePath because it stays
+    /// conservative for unknown shapes: a token like <c>readme.md</c>
+    /// satisfies the allow-list and would extend an unknown CLI's verb
+    /// chain, but the FileVerb carveout in <c>BashCommandParser</c>
+    /// short-circuits the common case (<c>cat readme.md</c>) before the
+    /// allow-list ever runs. Quoted strings are excluded so the user's
+    /// intent to treat bytes literally is preserved. The 64-char bound
+    /// is a defensive cap against pathological inputs.
     /// </remarks>
     internal static bool IsVerbLikeToken(in BashToken token)
     {