From 0f35b2e9beeaf4ba1772370942d7488af328a830 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 16:48:14 +0000
Subject: [PATCH 01/11] feat(spec,parse): add sigil-classified positional
 arguments

---
 argv/src/lib.rs                    |  47 +++++++++++-
 argv/src/spec.rs                   |  36 ++++++++-
 cli/src/cli/diff.rs                |  12 +++
 cli/src/cli/explain.rs             |   4 +
 cli/src/cli/mod.rs                 |   2 +-
 cli/usage.usage.kdl                |   2 +-
 conformance/src/tables.rs          |   1 +
 conformance/tests/canonical_kdl.rs |   4 +
 conformance/tests/sigil.rs         |  71 +++++++++++++++++
 corpus/14-sigil.json               |  90 ++++++++++++++++++++++
 derive/src/codegen.rs              |   7 +-
 derive/src/model.rs                |  56 +++++++++++++-
 docs/spec/reference/arg.md         |   4 +
 go/argv/argv.go                    |   2 +
 go/argv/parser.go                  |  35 ++++++++-
 go/internal/spec/spec.go           |   2 +
 lib/src/docs/models.rs             |   2 +
 lib/src/go/mod.rs                  |   3 +
 lib/src/parse.rs                   | 117 ++++++++++++++++++++++++++++-
 lib/src/sdk/python/mod.rs          |  13 +++-
 lib/src/sdk/typescript/wrappers.rs |  13 +++-
 lib/src/spec/arg.rs                |  47 +++++++++++-
 lib/src/spec/builder.rs            |   6 ++
 lib/src/spec/cmd.rs                |  12 +++
 24 files changed, 570 insertions(+), 18 deletions(-)
 create mode 100644 conformance/tests/sigil.rs
 create mode 100644 corpus/14-sigil.json

diff --git a/argv/src/lib.rs b/argv/src/lib.rs
index d652470d6..105720c45 100644
--- a/argv/src/lib.rs
+++ b/argv/src/lib.rs
@@ -515,6 +515,9 @@ pub struct Arg<'a> {
     /// Caller-assigned identifier, echoed back in [`Event::Arg`]. See
     /// [`Command::key`] on why it is this wide.
     pub key: u64,
+    /// Prefix that classifies this positional independently of declaration order.
+    /// The prefix is removed from the value emitted in [`Event::Arg`].
+    pub sigil: ::core::option::Option<&'a [u8]>,
     /// Whether post-binding requires this positional to have a value. Kept in the hot
     /// table because `allow_missing_positional` must reserve words for later required args.
     pub required: bool,
@@ -549,6 +552,7 @@ impl Arg<'_> {
     /// A single-value argument, for use with struct update syntax.
     pub const REQUIRED: Arg<'static> = Arg {
         key: 0,
+        sigil: ::core::option::Option::None,
         required: true,
         var: false,
         var_max: ::core::option::Option::None,
@@ -2229,6 +2233,16 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
                 }
             }
 
+            // Known subcommands and the default route keep precedence. A sigil positional
+            // then claims its classified word before an external-subcommand catch-all can.
+            if let Some((arg, sigil)) = self.match_sigil_arg(token) {
+                return Ok(Event::Arg {
+                    arg,
+                    value: &token[sigil.len()..],
+                    delimit: true,
+                });
+            }
+
             // An unmatched word that names no subcommand is forwarded as an external
             // command: this word, then every token after it, including flags. Known
             // subcommands already won above, and a default_subcommand already caught.
@@ -2245,6 +2259,7 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
             }
         }
 
+        self.skip_sigil_args();
         self.reserve_for_required_positionals();
         let Some(arg) = self.next_arg() else {
             return Err(Error::UnexpectedArg { token });
@@ -2315,8 +2330,10 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
 
     /// Move to the next positional, forgetting what the last one took.
     fn advance_arg(&mut self) {
+        self.skip_sigil_args();
         self.arg_pos += 1;
         self.arg_taken = 0;
+        self.skip_sigil_args();
     }
 
     /// A variadic flag occurrence begins, counting from zero.
@@ -2342,7 +2359,35 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
     }
 
     fn next_arg(&self) -> Option<&'t Arg<'t>> {
-        self.cmd.args.get(self.arg_pos).copied()
+        self.cmd.args[self.arg_pos..]
+            .iter()
+            .find(|arg| arg.sigil.is_none())
+            .copied()
+    }
+
+    fn skip_sigil_args(&mut self) {
+        while self
+            .cmd
+            .args
+            .get(self.arg_pos)
+            .is_some_and(|arg| arg.sigil.is_some())
+        {
+            self.arg_pos += 1;
+        }
+    }
+
+    fn match_sigil_arg(&self, token: &[u8]) -> Option<(&'t Arg<'t>, &'t [u8])> {
+        if self.flags_stopped {
+            return None;
+        }
+        self.cmd
+            .args
+            .iter()
+            .filter_map(|arg| {
+                let sigil = arg.sigil?;
+                (token.len() > sigil.len() && token.starts_with(sigil)).then_some((*arg, sigil))
+            })
+            .max_by_key(|(_, sigil)| sigil.len())
     }
 
     /// Skip empty optional positionals when every remaining value is needed by a later
diff --git a/argv/src/spec.rs b/argv/src/spec.rs
index 3fefe98e9..f8cf423a9 100644
--- a/argv/src/spec.rs
+++ b/argv/src/spec.rs
@@ -129,6 +129,9 @@ fn duplicate_group_name(meta: &CommandMeta<'_>) -> Option<std::string::String> {
 fn unfillable_arg<'a>(cmd: &Command<'a>) -> Option<&'a str> {
     let mut variadic: Option<&Arg<'_>> = None;
     for arg in cmd.args {
+        if arg.sigil.is_some() {
+            continue;
+        }
         // A `--` stops the collecting, so an argument behind one is still reachable — but only
         // one separator exists, so nothing can follow *that*.
         let stopped_by_separator = arg.double_dash == DoubleDash::Required;
@@ -2778,10 +2781,25 @@ fn write_arg(out: &mut String, meta: &ArgMeta<'_>, depth: usize) -> core::fmt::R
         meta.arg.name
     };
     write!(out, "arg {}", quoted(&arg_placeholder(name, meta)))?;
+    if let Some(sigil) = meta.arg.sigil {
+        write!(
+            out,
+            " sigil={}",
+            quoted(::core::str::from_utf8(sigil).unwrap_or_default())
+        )?;
+    }
 
     if let Some(help) = meta.help {
         write!(out, " help={}", quoted(help))?;
     }
+    if meta.arg.sigil.is_some() {
+        if !meta.required {
+            out.push_str(" required=#false");
+        }
+        if meta.arg.var {
+            out.push_str(" var=#true");
+        }
+    }
     if meta.hide {
         out.push_str(" hide=#true");
     }
@@ -3191,11 +3209,17 @@ fn exact_arity(min: Option<usize>, max: Option<usize>) -> Option<usize> {
 
 /// A positional's placeholder: angle brackets when required, square when not.
 fn arg_placeholder(name: &str, meta: &ArgMeta<'_>) -> String {
+    let sigil = meta
+        .arg
+        .sigil
+        .and_then(|value| ::core::str::from_utf8(value).ok())
+        .unwrap_or_default();
+    let name = format!("{sigil}{name}");
     if let Some(arity) =
         exact_arity(meta.var_min, meta.var_max).filter(|n| *n > 1 && meta.value_names.len() <= 1)
     {
         let values = (0..arity)
-            .map(|_| placeholder(name, false, !meta.required))
+            .map(|_| placeholder(&name, false, !meta.required))
             .collect::<Vec<_>>()
             .join(" ");
         return values;
@@ -3209,7 +3233,7 @@ fn arg_placeholder(name: &str, meta: &ArgMeta<'_>) -> String {
         let values = meta
             .value_names
             .iter()
-            .map(|name| format!("{open}{name}{close}"))
+            .map(|value_name| format!("{open}{sigil}{value_name}{close}"))
             .collect::<Vec<_>>()
             .join(" ");
         return if meta.arg.double_dash == DoubleDash::Required {
@@ -3218,7 +3242,13 @@ fn arg_placeholder(name: &str, meta: &ArgMeta<'_>) -> String {
             values
         };
     }
-    let ellipsis = if meta.arg.var { "..." } else { "" };
+    let ellipsis = if meta.arg.var && meta.arg.sigil.is_some() {
+        "…"
+    } else if meta.arg.var {
+        "..."
+    } else {
+        ""
+    };
     if meta.required {
         format!("<{name}>{ellipsis}")
     } else {
diff --git a/cli/src/cli/diff.rs b/cli/src/cli/diff.rs
index 4003784ee..ba8594937 100644
--- a/cli/src/cli/diff.rs
+++ b/cli/src/cli/diff.rs
@@ -1164,6 +1164,18 @@ fn diff_arg(old: &SpecArg, new: &SpecArg, path: &str, subject: &str, c: &mut Cha
         );
     }
 
+    if old.sigil != new.sigil {
+        c.breaking(
+            "sigil-changed",
+            path,
+            format!(
+                "{subject} sigil changed from {} to {}",
+                option(&old.sigil),
+                option(&new.sigil)
+            ),
+        );
+    }
+
     if old.allow_negative_numbers && !new.allow_negative_numbers {
         c.breaking(
             "allow-negative-numbers-removed",
diff --git a/cli/src/cli/explain.rs b/cli/src/cli/explain.rs
index 91e1da593..415853c36 100644
--- a/cli/src/cli/explain.rs
+++ b/cli/src/cli/explain.rs
@@ -535,6 +535,10 @@ impl RoleRow {
                 name: arg.name.clone(),
                 values: values.clone(),
             },
+            TokenRole::Sigil { arg, values, .. } => Self::Arg {
+                name: arg.name.clone(),
+                values: values.clone(),
+            },
             TokenRole::Separator => Self::Separator,
             TokenRole::ValueTerminator { ends } => Self::ValueTerminator { ends: ends.clone() },
             TokenRole::Restart => Self::Restart,
diff --git a/cli/src/cli/mod.rs b/cli/src/cli/mod.rs
index bfb019813..35ee4cb39 100644
--- a/cli/src/cli/mod.rs
+++ b/cli/src/cli/mod.rs
@@ -32,7 +32,7 @@ mod sponsors;
 #[usage(
     bin = "usage",
     version,
-    min_usage_version = "4.0",
+    min_usage_version = "6.5",
     repository = "https://github.com/jdx/usage",
     // The command path is not the file path: command names are hyphenated where the files
     // that implement them are snake_case, a command with subcommands lives in its directory's
diff --git a/cli/usage.usage.kdl b/cli/usage.usage.kdl
index 51370b628..a7a20fa3f 100644
--- a/cli/usage.usage.kdl
+++ b/cli/usage.usage.kdl
@@ -1,5 +1,5 @@
 // @generated by usage-cli from its own parse tables
-min_usage_version "4.0"
+min_usage_version "6.5"
 name usage
 bin usage
 version "6.4.1"
diff --git a/conformance/src/tables.rs b/conformance/src/tables.rs
index 4850e67d2..7aa24fad8 100644
--- a/conformance/src/tables.rs
+++ b/conformance/src/tables.rs
@@ -351,6 +351,7 @@ fn build_flag(f: &SpecFlag) -> &'static Flag<'static> {
 fn build_arg(a: &SpecArg) -> &'static Arg<'static> {
     Box::leak(Box::new(Arg {
         key: 0,
+        sigil: a.sigil.as_deref().map(|value| leak(value).as_bytes()),
         required: a.required,
         name: leak(&a.name),
         var: a.var,
diff --git a/conformance/tests/canonical_kdl.rs b/conformance/tests/canonical_kdl.rs
index b507d0ef2..776471eed 100644
--- a/conformance/tests/canonical_kdl.rs
+++ b/conformance/tests/canonical_kdl.rs
@@ -136,6 +136,10 @@ struct MaximalRun {
     #[usage(long, help_heading = "Task Options")]
     config: Option<String>,
 
+    /// Temporary tool selections.
+    #[usage(sigil = "+")]
+    tools: Vec<String>,
+
     /// Task name.
     task: String,
 }
diff --git a/conformance/tests/sigil.rs b/conformance/tests/sigil.rs
new file mode 100644
index 000000000..e0b4cc049
--- /dev/null
+++ b/conformance/tests/sigil.rs
@@ -0,0 +1,71 @@
+//! Sigil-classified positional arguments agree between the typed and interpreted parsers.
+
+use std::ffi::OsStr;
+
+use usage::parse::ParseValue;
+use usage::Spec as LibSpec;
+use usage_derive::Cli;
+
+#[derive(Debug, Cli)]
+#[usage(bin = "overlay")]
+struct Overlay {
+    /// Temporary tool selections.
+    #[usage(sigil = "+")]
+    tools: Vec<String>,
+    /// Command to execute.
+    command: String,
+    /// Arguments passed to the command.
+    args: Vec<String>,
+}
+
+fn interpreted_values(spec: &LibSpec, argv: &[&str], name: &str) -> Vec<String> {
+    let argv = std::iter::once("overlay")
+        .chain(argv.iter().copied())
+        .map(str::to_string)
+        .collect::<Vec<_>>();
+    let parsed = usage::Parser::new(spec).parse(&argv).expect("valid invocation");
+    parsed
+        .args
+        .iter()
+        .find(|(arg, _)| arg.name.eq_ignore_ascii_case(name))
+        .map(|(_, value)| match value {
+            ParseValue::String(value) => vec![value.clone()],
+            ParseValue::MultiString(values) => values.clone(),
+            other => panic!("unexpected value for {name}: {other:?}"),
+        })
+        .unwrap_or_default()
+}
+
+#[test]
+fn sigils_strip_and_do_not_advance_the_positional_cursor() {
+    let argv = [
+        OsStr::new("+node@27"),
+        OsStr::new("+python@3.14"),
+        OsStr::new("node"),
+        OsStr::new("-v"),
+    ];
+    let typed = Overlay::parse_from(&argv).expect("typed parser accepts overlays");
+    assert_eq!(typed.tools, ["node@27", "python@3.14"]);
+    assert_eq!(typed.command, "node");
+    assert_eq!(typed.args, ["-v"]);
+
+    let spec: LibSpec = Overlay::to_kdl().parse().expect("derived KDL is valid");
+    assert_eq!(spec.cmd.args[0].sigil.as_deref(), Some("+"));
+    assert_eq!(interpreted_values(&spec, &["+node@27", "node"], "tools"), ["node@27"]);
+    assert_eq!(interpreted_values(&spec, &["+node@27", "node"], "command"), ["node"]);
+}
+
+#[test]
+fn double_dash_protects_a_literal_sigil_word() {
+    let argv = [OsStr::new("node"), OsStr::new("--"), OsStr::new("+literal")];
+    let typed = Overlay::parse_from(&argv).expect("literal reaches ordinary args");
+    assert!(typed.tools.is_empty());
+    assert_eq!(typed.args, ["+literal"]);
+
+    let spec: LibSpec = Overlay::to_kdl().parse().expect("derived KDL is valid");
+    assert!(interpreted_values(&spec, &["node", "--", "+literal"], "tools").is_empty());
+    assert_eq!(
+        interpreted_values(&spec, &["node", "--", "+literal"], "args"),
+        ["+literal"]
+    );
+}
diff --git a/corpus/14-sigil.json b/corpus/14-sigil.json
new file mode 100644
index 000000000..9f6703381
--- /dev/null
+++ b/corpus/14-sigil.json
@@ -0,0 +1,90 @@
+{
+  "section": "sigil arguments",
+  "about": "A sigil classifies a leading-segment positional by prefix, strips that prefix from its value, and leaves the ordinary positional cursor untouched.",
+  "vectors": [
+    {
+      "id": "sigil-values-accumulate-without-advancing",
+      "doc": "Several classified values may surround flags before the first ordinary positional.",
+      "spec": "name \"ex\"\nbin \"ex\"\nflag \"--quiet\"\narg \"[tools]...\" sigil=\"+\"\narg \"<command>\"\narg \"[args]...\"\n",
+      "argv": ["+node@27", "--quiet", "+python@3.14", "node", "-v"],
+      "expect": {
+        "ok": {
+          "flags": { "quiet": true },
+          "args": {
+            "tools": ["node@27", "python@3.14"],
+            "command": "node",
+            "args": ["-v"]
+          }
+        }
+      }
+    },
+    {
+      "id": "longest-sigil-prefix-wins",
+      "doc": "Overlapping sigils select the longest matching declaration.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[short]...\" sigil=\"+\"\narg \"[long]...\" sigil=\"++\"\narg \"<command>\"\n",
+      "argv": ["++edge", "+stable", "run"],
+      "expect": {
+        "ok": {
+          "args": {
+            "short": ["stable"],
+            "long": ["edge"],
+            "command": "run"
+          }
+        }
+      }
+    },
+    {
+      "id": "double-dash-protects-sigil",
+      "doc": "After an explicit separator the same prefix is ordinary data.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\narg \"<command>\"\narg \"[args]...\"\n",
+      "argv": ["run", "--", "+literal"],
+      "expect": {
+        "ok": {
+          "args": { "command": "run", "args": ["+literal"] }
+        }
+      }
+    },
+    {
+      "id": "bare-sigil-falls-through",
+      "doc": "A prefix with no value is not a classified argument.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\narg \"<command>\"\n",
+      "argv": ["+"],
+      "expect": { "ok": { "args": { "command": "+" } } }
+    },
+    {
+      "id": "flag-awaiting-value-outranks-sigil",
+      "doc": "A detached flag value owns the next token before sigil classification runs.",
+      "spec": "name \"ex\"\nbin \"ex\"\nflag \"--label <label>\"\narg \"[tools]...\" sigil=\"+\"\narg \"<command>\"\n",
+      "argv": ["--label", "+raw", "run"],
+      "expect": {
+        "ok": {
+          "flags": { "label": "+raw" },
+          "args": { "command": "run" }
+        }
+      }
+    },
+    {
+      "id": "sigil-does-not-block-subcommand-routing",
+      "doc": "A classified positional before a known subcommand does not make the subcommand an ordinary value.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\ncmd \"build\" { arg \"<target>\" }\n",
+      "argv": ["+node@27", "build", "app"],
+      "expect": {
+        "ok": {
+          "cmd": ["build"],
+          "args": { "tools": ["node@27"], "target": "app" }
+        }
+      }
+    },
+    {
+      "id": "automatic-boundary-protects-later-sigil",
+      "doc": "Once an automatic trailing positional starts, later sigil-shaped words are data.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\narg \"<command>\" double_dash=\"automatic\"\narg \"[args]...\"\n",
+      "argv": ["run", "+literal"],
+      "expect": {
+        "ok": {
+          "args": { "command": "run", "args": ["+literal"] }
+        }
+      }
+    }
+  ]
+}
diff --git a/derive/src/codegen.rs b/derive/src/codegen.rs
index d2bb04250..68959a9f5 100644
--- a/derive/src/codegen.rs
+++ b/derive/src/codegen.rs
@@ -2498,9 +2498,13 @@ fn arg_table(i: usize, field: &Field) -> TokenStream {
     let var = field.shape == Shape::Many;
     let required =
         (field.shape == Shape::Required || field.required_collection) && !field.has_default();
-    let Kind::Arg { double_dash } = &field.kind else {
+    let Kind::Arg { double_dash, sigil } = &field.kind else {
         unreachable!("filtered by the caller");
     };
+    let sigil = match sigil.as_deref() {
+        Some(value) => quote!(::core::option::Option::Some(#value.as_bytes())),
+        None => quote!(::core::option::Option::None),
+    };
     let double_dash = match double_dash {
         DoubleDash::Optional => quote!(usage_argv::DoubleDash::Optional),
         DoubleDash::Required => quote!(usage_argv::DoubleDash::Required),
@@ -2526,6 +2530,7 @@ fn arg_table(i: usize, field: &Field) -> TokenStream {
     quote! {
         pub static #name: usage_argv::Arg = usage_argv::Arg {
             key: #key,
+            sigil: #sigil,
             required: #required,
             name: #field_name,
             var: #var,
diff --git a/derive/src/model.rs b/derive/src/model.rs
index 7e393c67b..f96e569b8 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -659,6 +659,8 @@ pub enum Kind {
     Arg {
         /// How this argument relates to the `--` separator.
         double_dash: DoubleDash,
+        /// Prefix that classifies this positional independently of declaration order.
+        sigil: Option<String>,
     },
     /// Holds the enum whose variants are this command's subcommands.
     ///
@@ -1628,6 +1630,7 @@ impl Cli {
     fn check(&self) -> syn::Result<()> {
         let mut seen_long: Vec<(&str, Span)> = Vec::new();
         let mut seen_short: Vec<(char, Span)> = Vec::new();
+        let mut seen_sigils: Vec<(&str, Span)> = Vec::new();
         let mut variadic_arg: Option<Span> = None;
         // A variadic that only takes what follows a `--`, which is the end of the line in
         // both senses: it holds the remaining words and the separator cannot come twice.
@@ -1679,7 +1682,22 @@ impl Cli {
                 // duplicate-form check is where the whole tree is visible.
                 Kind::ArgGroup { .. } => {}
                 Kind::Skip => {}
-                Kind::Arg { double_dash } => {
+                Kind::Arg { double_dash, sigil } => {
+                    if let Some(sigil) = sigil {
+                        if let Some((_, first)) =
+                            seen_sigils.iter().find(|(seen, _)| *seen == sigil)
+                        {
+                            return Err(dup(
+                                field.span,
+                                *first,
+                                &format!("sigil {sigil:?} is declared twice"),
+                            ));
+                        }
+                        seen_sigils.push((sigil, field.span));
+                        // A sigil-classified positional never occupies the ordinary cursor, so
+                        // its collection shape says nothing about whether later args are reachable.
+                        continue;
+                    }
                     // A variadic takes every remaining word, so anything after it can
                     // never be filled — with two exceptions, both of which are something
                     // that stops the variadic. An argument only fillable after a `--`,
@@ -2677,6 +2695,7 @@ impl Field {
         let mut allow_hyphen_values = false;
         let mut allow_negative_numbers = false;
         let mut value_terminator = None;
+        let mut sigil = None;
         let mut require_equals = false;
         let mut bool_value = false;
         let mut default_missing = None;
@@ -2868,6 +2887,7 @@ impl Field {
                     "allow_hyphen_values" => allow_hyphen_values = flag_value(&meta)?,
                     "allow_negative_numbers" => allow_negative_numbers = flag_value(&meta)?,
                     "value_terminator" => value_terminator = Some(string_value(&meta)?),
+                    "sigil" => sigil = Some(string_value(&meta)?),
                     "require_equals" => require_equals = flag_value(&meta)?,
                     "bool_value" => bool_value = flag_value(&meta)?,
                     "default_missing" => default_missing = Some(string_value(&meta)?),
@@ -3003,7 +3023,7 @@ impl Field {
                                  `var_min`, `var_max`, `value_enum`, `value_hint`, `overrides`, \
                                  `conflicts`, `requires`, `group`, `exclusive`, \
                                  `delimiter`, `allow_hyphen_values`, `allow_negative_numbers`, \
-                                 `value_terminator`, `require_equals`, `bool_value`, \
+                                 `value_terminator`, `sigil`, `require_equals`, `bool_value`, \
                                  `default_missing`, `default_if`, \
                                  `required_if`, \
                                  `required_unless`, `required_unless_all`, `help_heading`, `surface`, `available_if`, `select`, `display_order`, `value_name`, `value_names`, `num_args`, \
@@ -3659,7 +3679,7 @@ impl Field {
                      use `String`",
                 ));
             }
-            Kind::Arg { double_dash }
+            Kind::Arg { double_dash, sigil }
         };
 
         if complete_type.as_deref() == Some("command_args")
@@ -3795,6 +3815,36 @@ impl Field {
                 ));
             }
         }
+        if let Kind::Arg {
+            double_dash,
+            sigil: Some(sigil),
+        } = &kind
+        {
+            if sigil.is_empty() {
+                return Err(syn::Error::new(span, "`sigil` cannot be empty"));
+            }
+            if sigil.starts_with('-') {
+                return Err(syn::Error::new(
+                    span,
+                    "`sigil` cannot start with `-`; that namespace belongs to flags",
+                ));
+            }
+            if sigil.chars().any(char::is_whitespace) {
+                return Err(syn::Error::new(span, "`sigil` cannot contain whitespace"));
+            }
+            if *double_dash != DoubleDash::Optional {
+                return Err(syn::Error::new(
+                    span,
+                    "a sigil argument cannot declare non-optional `double_dash` behavior",
+                ));
+            }
+            if value_terminator.is_some() {
+                return Err(syn::Error::new(
+                    span,
+                    "a sigil argument cannot declare `value_terminator`",
+                ));
+            }
+        }
 
         if require_equals {
             if !matches!(kind, Kind::Flag { .. }) {
diff --git a/docs/spec/reference/arg.md b/docs/spec/reference/arg.md
index fdd014d97..7894c88ed 100644
--- a/docs/spec/reference/arg.md
+++ b/docs/spec/reference/arg.md
@@ -1,5 +1,8 @@
 # `arg`
 
+Arguments may also be classified by a prefix instead of position. See
+[sigil arguments](./sigils.md) for matching, boundary, completion, and derive rules.
+
 Positionals accept `hide`, `hide_default_value`, `hide_env`, `hide_env_values`,
 `hide_possible_values`, `hide_short_help`, and `hide_long_help`. These affect
 help presentation only; defaults, environment fallback, and validation remain
@@ -14,6 +17,7 @@ arg "<file>" env="MY_FILE"               // arg can be backed by an env var
 arg "<file>" display_order=10             // explicit order in help; parse order is unchanged
 arg "<port>" validate="int(value) >= 1 && int(value) <= 65535" validate_error="must be a valid port"
 arg "<output>" effect="write"             // raises the command effect when supplied
+arg "[tool]..." sigil="+"                  // +node@24 stores node@24 without advancing
 
 arg "[file]" var=#true // multiple args can be passed (e.g. mycli file1 file2 file3) (0 or more)
 arg "<file>" var=#true // multiple args can be passed (e.g. mycli file1 file2 file3) (1 or more)
diff --git a/go/argv/argv.go b/go/argv/argv.go
index 84fbbe5e0..e7fa12df3 100644
--- a/go/argv/argv.go
+++ b/go/argv/argv.go
@@ -210,6 +210,8 @@ const (
 type Arg struct {
 	// Key is a caller-assigned identifier, echoed back in the event.
 	Key uint64
+	// Sigil classifies this positional by prefix. It is stripped from emitted values.
+	Sigil string
 	// Required is used while binding when AllowMissingPositional reserves words
 	// for later required positionals.
 	Required bool
diff --git a/go/argv/parser.go b/go/argv/parser.go
index 715188b5f..7fbe22b68 100644
--- a/go/argv/parser.go
+++ b/go/argv/parser.go
@@ -606,6 +606,12 @@ func (p *Parser) word(token string) bool {
 			return p.emit(Event{Kind: KindCommand, Command: d})
 		}
 
+		if arg, sigil := p.matchSigilArg(token); arg != nil {
+			return p.emit(Event{
+				Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
+			})
+		}
+
 		// An unmatched word that names no subcommand is forwarded as an external
 		// command: this word, then every token after it, including flags. Known
 		// subcommands already won above, and a default subcommand already caught.
@@ -617,6 +623,7 @@ func (p *Parser) word(token string) bool {
 		}
 	}
 
+	p.skipSigilArgs()
 	p.reserveForRequiredPositionals()
 	arg := p.nextArg()
 	if arg == nil {
@@ -677,8 +684,10 @@ func (p *Parser) descend(sub *Command) bool {
 
 // advanceArg moves to the next positional, forgetting what the last one took.
 func (p *Parser) advanceArg() {
+	p.skipSigilArgs()
 	p.argPos++
 	p.argTaken = 0
+	p.skipSigilArgs()
 }
 
 // startCollecting begins a variadic flag occurrence.
@@ -708,12 +717,34 @@ func valuesIn(value string, delimiter byte) uint32 {
 }
 
 func (p *Parser) nextArg() *Arg {
-	if p.argPos < len(p.cmd.Args) {
-		return p.cmd.Args[p.argPos]
+	for i := p.argPos; i < len(p.cmd.Args); i++ {
+		if p.cmd.Args[i].Sigil == "" {
+			return p.cmd.Args[i]
+		}
 	}
 	return nil
 }
 
+func (p *Parser) skipSigilArgs() {
+	for p.argPos < len(p.cmd.Args) && p.cmd.Args[p.argPos].Sigil != "" {
+		p.argPos++
+	}
+}
+
+func (p *Parser) matchSigilArg(token string) (*Arg, string) {
+	if p.flagsStopped {
+		return nil, ""
+	}
+	var best *Arg
+	bestSigil := ""
+	for _, arg := range p.cmd.Args {
+		if arg.Sigil != "" && len(token) > len(arg.Sigil) && len(arg.Sigil) > len(bestSigil) && token[:len(arg.Sigil)] == arg.Sigil {
+			best, bestSigil = arg, arg.Sigil
+		}
+	}
+	return best, bestSigil
+}
+
 // reserveForRequiredPositionals implements the opt-in clap policy that lets a
 // later required positional claim the last available word while an earlier
 // optional positional remains empty.
diff --git a/go/internal/spec/spec.go b/go/internal/spec/spec.go
index 48acc893d..9527f7fff 100644
--- a/go/internal/spec/spec.go
+++ b/go/internal/spec/spec.go
@@ -355,6 +355,7 @@ func (f *Flag) defaults() []string {
 // Arg is one positional argument, or a flag's value, in the lowered spec.
 type Arg struct {
 	Name                 string         `json:"name"`
+	Sigil                string         `json:"sigil"`
 	ValueNames           []string       `json:"value_names"`
 	Required             bool           `json:"required"`
 	Var                  bool           `json:"var"`
@@ -1063,6 +1064,7 @@ func (b *builder) arg(a *Arg) *argv.Arg {
 	out := &argv.Arg{
 		Key:                  b.next(),
 		Name:                 a.Name,
+		Sigil:                a.Sigil,
 		Required:             a.Required,
 		Var:                  a.Var,
 		DoubleDash:           doubleDash(a.DoubleDash),
diff --git a/lib/src/docs/models.rs b/lib/src/docs/models.rs
index d39b758d9..5f26f9a70 100644
--- a/lib/src/docs/models.rs
+++ b/lib/src/docs/models.rs
@@ -530,6 +530,7 @@ pub struct SpecExample {
 #[derive(Debug, Default, Clone, Serialize)]
 pub struct SpecArg {
     pub name: String,
+    pub sigil: Option<String>,
     pub usage: String,
     pub help: Option<String>,
     pub help_long: Option<String>,
@@ -1080,6 +1081,7 @@ impl From<&crate::SpecArg> for SpecArg {
     fn from(arg: &crate::SpecArg) -> Self {
         Self {
             name: arg.name.clone(),
+            sigil: arg.sigil.clone(),
             usage: arg.usage.clone(),
             help: said(&arg.help),
             help_long: arg.help_long.clone(),
diff --git a/lib/src/go/mod.rs b/lib/src/go/mod.rs
index 5372a1170..efd868207 100644
--- a/lib/src/go/mod.rs
+++ b/lib/src/go/mod.rs
@@ -1495,6 +1495,9 @@ fn arg_literal(arg: &SpecArg, named: &Named) -> String {
         format!("Key: {}", named.key),
         format!("Name: {}", go_string(&arg.name)),
     ];
+    if let Some(sigil) = &arg.sigil {
+        fields.push(format!("Sigil: {}", go_string(sigil)));
+    }
     if arg.required {
         fields.push("Required: true".to_string());
     }
diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index e4cf4a7cd..14081f9be 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -330,6 +330,12 @@ pub enum TokenRole {
         arg: Arc<SpecArg>,
         values: Vec<String>,
     },
+    /// Filled a sigil-classified positional after removing its declared prefix.
+    Sigil {
+        arg: Arc<SpecArg>,
+        sigil: String,
+        values: Vec<String>,
+    },
     /// An explicit `--`, consumed as a separator.
     Separator,
     /// A word the parser answers itself rather than binding: `--help`, `-h`, `--version`,
@@ -1464,6 +1470,12 @@ fn parse_partial_traced(
                 idx += 1;
                 continue;
             }
+            // Sigil-classified positionals do not occupy the ordinary positional cursor and
+            // therefore do not close subcommand routing. Phase 2 binds and strips them.
+            if match_sigil_arg(&out.cmd, &input[idx].word).is_some() {
+                idx += 1;
+                continue;
+            }
             // Found a word that's not a flag or subcommand
             // Check if we should use the default_subcommand (only once, and only at the
             // root, which is the only place a spec can declare one — `out.cmds` holds just
@@ -1538,13 +1550,16 @@ fn parse_partial_traced(
     // explicit `--` may jump it *past* arguments that stay empty (see the `w == "--"` arm).
     // With such a gap `out.args.len()` no longer equals the cursor, so anything asking "is this
     // argument filled?" has to consult `out.args` by key instead of counting.
-    let mut next_arg_idx: usize = 0;
+    let mut next_arg_idx = cursor_skip_sigils(&out.cmd, 0);
     let mut enable_flags = true;
     let mut grouped_flag = false;
     // Whether an explicit `--` has been consumed *as a separator* (as opposed to being kept as a
     // value by `double_dash="preserve"`). Args declared `double_dash="required"` only accept
     // words that come after it — see `report_double_dash_violation`.
     let mut seen_double_dash = false;
+    // Sigils are a leading-segment grammar. A restart begins a later segment but does not
+    // reopen sigil classification for this invocation.
+    let mut restart_seen = false;
     // Args already reported as having been offered a word before the `--` they require, so a
     // variadic one does not report the same violation for every word it is offered.
     let mut double_dash_violations: HashSet<String> = HashSet::new();
@@ -1581,7 +1596,8 @@ fn parse_partial_traced(
                 // dropped them would show a command line with a hole in it.
                 out.arg_origins.clear();
                 trace.record(argv, TokenRole::Restart);
-                next_arg_idx = 0;
+                next_arg_idx = cursor_skip_sigils(&out.cmd, 0);
+                restart_seen = true;
                 out.flag_awaiting_value.clear(); // Clear any pending flag values
                 enable_flags = true; // Reset -- separator effect
                 seen_double_dash = false; // The next invocation needs its own `--`
@@ -2100,6 +2116,66 @@ fn parse_partial_traced(
             continue;
         }
 
+        if let Some((arg, sigil, value)) = (enable_flags && !restart_seen)
+            .then(|| match_sigil_arg_chain(&out.cmds, &w))
+            .flatten()
+        {
+            let trailing_value = arg.double_dash == SpecDoubleDashChoices::Automatic;
+            let suppress_trailing_delimiter = out
+                .cmds
+                .iter()
+                .any(|cmd| cmd.dont_delimit_trailing_values);
+            let delimiter = if suppress_trailing_delimiter && trailing_value {
+                None
+            } else {
+                arg.delimiter
+            };
+            let parts = match delimiter {
+                Some(delimiter) => value.split(delimiter).map(str::to_string).collect::<Vec<_>>(),
+                None => vec![value.to_string()],
+            };
+            let mut refused = false;
+            for part in &parts {
+                if validate_choices(
+                    spec,
+                    &out.cmd,
+                    &mut out.errors,
+                    ChoiceTarget::arg(arg),
+                    part,
+                    arg.choices.as_ref(),
+                    custom_env,
+                )? {
+                    refused = true;
+                    break;
+                }
+            }
+            if refused {
+                record_stop(&mut out, next_arg_idx, seen_double_dash, trace, &input);
+                return Ok((out, overridden_flags));
+            }
+            trace.record(
+                argv,
+                TokenRole::Sigil {
+                    arg: Arc::new(arg.clone()),
+                    sigil: sigil.to_string(),
+                    values: parts.clone(),
+                },
+            );
+            let key = Arc::new(arg.clone());
+            if arg.var {
+                let arr = out
+                    .args
+                    .entry(key)
+                    .or_insert_with(|| ParseValue::MultiString(vec![]))
+                    .try_as_multi_string_mut()
+                    .unwrap();
+                arr.extend(parts);
+            } else {
+                out.args.insert(key, ParseValue::String(value.to_string()));
+            }
+            continue;
+        }
+
         if out.cmd.allow_missing_positional {
             while let Some(current) = out.cmd.args.get(next_arg_idx) {
                 if current.required || out.args.contains_key(current) {
@@ -4043,12 +4119,44 @@ fn record_stop(
     trace: &mut Trace,
     unread: &VecDeque<Token>,
 ) {
-    out.next_arg = out.cmd.args.get(next_arg_idx).cloned().map(Arc::new);
+    out.next_arg = out
+        .cmd
+        .args
+        .get(cursor_skip_sigils(&out.cmd, next_arg_idx))
+        .cloned()
+        .map(Arc::new);
     out.double_dash_seen = seen_double_dash;
     trace.close(unread);
     out.tokens = std::mem::take(&mut trace.tokens);
 }
 
+fn cursor_skip_sigils(cmd: &SpecCommand, mut idx: usize) -> usize {
+    while cmd.args.get(idx).is_some_and(|arg| arg.sigil.is_some()) {
+        idx += 1;
+    }
+    idx
+}
+
+fn match_sigil_arg<'a>(cmd: &'a SpecCommand, word: &'a str) -> Option<(&'a SpecArg, &'a str, &'a str)> {
+    cmd.args
+        .iter()
+        .filter_map(|arg| {
+            let sigil = arg.sigil.as_deref()?;
+            let value = word.strip_prefix(sigil)?;
+            (!value.is_empty()).then_some((arg, sigil, value))
+        })
+        .max_by_key(|(_, sigil, _)| sigil.len())
+}
+
+fn match_sigil_arg_chain<'a>(
+    cmds: &'a [SpecCommand],
+    word: &'a str,
+) -> Option<(&'a SpecArg, &'a str, &'a str)> {
+    cmds.iter()
+        .filter_map(|cmd| match_sigil_arg(cmd, word))
+        .max_by_key(|(_, sigil, _)| sigil.len())
+}
+
 /// Record that `arg` was handed a word before the `--` it requires.
 ///
 /// A variadic arg would otherwise report the same mistake once per word it was offered, so the
@@ -4152,6 +4260,9 @@ fn render_role(role: &TokenRole) -> String {
             format!("value of {} = {values:?}{attached}", flag.name)
         }
         TokenRole::Arg { arg, values } => format!("arg {} = {values:?}", arg.name),
+        TokenRole::Sigil { arg, sigil, values } => {
+            format!("sigil arg {} ({sigil}) = {values:?}", arg.name)
+        }
         TokenRole::Separator => "separator".to_string(),
         TokenRole::Builtin { spelling } => format!("built-in {spelling}"),
         TokenRole::ValueTerminator { ends } => format!("value terminator, ends {ends}"),
diff --git a/lib/src/sdk/python/mod.rs b/lib/src/sdk/python/mod.rs
index 092330232..e0392ee51 100644
--- a/lib/src/sdk/python/mod.rs
+++ b/lib/src/sdk/python/mod.rs
@@ -768,7 +768,18 @@ fn render_class(
                 continue;
             }
             let ident = sanitize_py_ident(&arg.name);
-            if arg.var {
+            if let Some(sigil) = &arg.sigil {
+                let sigil = escape_py_string(sigil);
+                if arg.var {
+                    w.line(&format!(
+                        "if args.{ident} is not None: cmd_args.extend(\"{sigil}\" + str(value) for value in args.{ident})"
+                    ));
+                } else {
+                    w.line(&format!(
+                        "if args.{ident} is not None: cmd_args.append(\"{sigil}\" + str(args.{ident}))"
+                    ));
+                }
+            } else if arg.var {
                 w.line(&format!(
                     "if args.{ident} is not None: cmd_args.extend(args.{ident})"
                 ));
diff --git a/lib/src/sdk/typescript/wrappers.rs b/lib/src/sdk/typescript/wrappers.rs
index a6d64160e..92aacc6f5 100644
--- a/lib/src/sdk/typescript/wrappers.rs
+++ b/lib/src/sdk/typescript/wrappers.rs
@@ -266,7 +266,18 @@ fn render_class(
                     continue;
                 }
                 let ident = sanitize_ident(&arg.name);
-                if arg.var {
+                if let Some(sigil) = &arg.sigil {
+                    let sigil = escape_ts_string(sigil);
+                    if arg.var {
+                        w.line(&format!(
+                            "if (args.{ident} !== undefined) {{ cmdArgs.push(...args.{ident}.map(value => \"{sigil}\" + String(value))); }}"
+                        ));
+                    } else {
+                        w.line(&format!(
+                            "if (args.{ident} !== undefined) {{ cmdArgs.push(\"{sigil}\" + String(args.{ident})); }}"
+                        ));
+                    }
+                } else if arg.var {
                     w.line(&format!(
                         "if (args.{ident} !== undefined) {{ cmdArgs.push(...args.{ident}); }}"
                     ));
diff --git a/lib/src/spec/arg.rs b/lib/src/spec/arg.rs
index a95cd2068..56ef46d15 100644
--- a/lib/src/spec/arg.rs
+++ b/lib/src/spec/arg.rs
@@ -63,6 +63,9 @@ impl_string_enum!(SpecDoubleDashChoices {
 pub struct SpecArg {
     /// Name of the argument (used in help text)
     pub name: String,
+    /// Prefix that classifies this positional independently of declaration order.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sigil: Option<String>,
     /// Ordered placeholders for a fixed-arity value, such as `START` and `END`.
     /// Empty means the argument's `name` is the sole placeholder.
     #[serde(skip_serializing_if = "Vec::is_empty")]
@@ -219,6 +222,7 @@ impl SpecArg {
         for (k, v) in node.props() {
             match k {
                 "help" => arg.help = Some(v.ensure_string()?),
+                "sigil" => arg.sigil = v.ensure_string().map(Some)?,
                 "long_help" => arg.help_long = Some(v.ensure_string()?),
                 "help_long" => arg.help_long = Some(v.ensure_string()?),
                 "help_md" => arg.help_md = Some(v.ensure_string()?),
@@ -336,6 +340,7 @@ impl SpecArg {
                     }
                 }
                 "help" => arg.help = Some(child.arg(0)?.ensure_string()?),
+                "sigil" => arg.sigil = child.arg(0)?.ensure_string().map(Some)?,
                 "long_help" => arg.help_long = Some(child.arg(0)?.ensure_string()?),
                 "help_long" => arg.help_long = Some(child.arg(0)?.ensure_string()?),
                 "help_md" => arg.help_md = Some(child.arg(0)?.ensure_string()?),
@@ -396,6 +401,11 @@ impl SpecArg {
                 k => bail_parse!(ctx, child.node.name().span(), "unsupported arg child {k}"),
             }
         }
+        if let Some(sigil) = &arg.sigil {
+            if let Some(name) = arg.name.strip_prefix(sigil) {
+                arg.name = name.to_string();
+            }
+        }
         if let Some(first) = arg.value_names.first() {
             arg.name.clone_from(first);
         }
@@ -436,6 +446,35 @@ impl SpecArg {
                 "value_terminator requires a variadic argument"
             );
         }
+        if let Some(sigil) = &arg.sigil {
+            if sigil.is_empty() {
+                bail_parse!(ctx, node.node.name().span(), "sigil cannot be empty");
+            }
+            if sigil.starts_with('-') {
+                bail_parse!(
+                    ctx,
+                    node.node.name().span(),
+                    "sigil cannot start with `-`; that namespace belongs to flags"
+                );
+            }
+            if sigil.chars().any(char::is_whitespace) {
+                bail_parse!(ctx, node.node.name().span(), "sigil cannot contain whitespace");
+            }
+            if arg.double_dash != SpecDoubleDashChoices::Optional {
+                bail_parse!(
+                    ctx,
+                    node.node.name().span(),
+                    "sigil arguments cannot declare non-optional double_dash behavior"
+                );
+            }
+            if arg.value_terminator.is_some() {
+                bail_parse!(
+                    ctx,
+                    node.node.name().span(),
+                    "sigil arguments cannot declare value_terminator"
+                );
+            }
+        }
         #[cfg(feature = "validation")]
         if let Some(expression) = &arg.validate {
             if let Err(error) = usage_validation::check(expression) {
@@ -491,7 +530,9 @@ impl SpecArg {
                 placeholders
             };
         }
-        let name = if self.double_dash == SpecDoubleDashChoices::Required {
+        let name = if let Some(sigil) = &self.sigil {
+            format!("{sigil}{}", self.name)
+        } else if self.double_dash == SpecDoubleDashChoices::Required {
             format!("-- {}", self.name)
         } else {
             self.name.clone()
@@ -512,6 +553,9 @@ impl From<&SpecArg> for KdlNode {
     fn from(arg: &SpecArg) -> Self {
         let mut node = KdlNode::new("arg");
         node.push(KdlEntry::new(arg.usage()));
+        if let Some(sigil) = &arg.sigil {
+            node.push(string_entry(Some("sigil"), sigil));
+        }
         if let Some(desc) = &arg.help {
             node.push(string_entry(Some("help"), desc));
         }
@@ -1011,6 +1055,7 @@ impl From<&clap::Arg> for SpecArg {
                 .first()
                 .cloned()
                 .unwrap_or_else(|| source.get_id().to_string()),
+            sigil: None,
             value_names,
             usage: "".into(),
             required,
diff --git a/lib/src/spec/builder.rs b/lib/src/spec/builder.rs
index 6647f6af9..c31ee538e 100644
--- a/lib/src/spec/builder.rs
+++ b/lib/src/spec/builder.rs
@@ -543,6 +543,12 @@ impl SpecArgBuilder {
         self
     }
 
+    /// Classify this positional by a leading token prefix and strip it on binding.
+    pub fn sigil(mut self, sigil: impl Into<String>) -> Self {
+        self.inner.sigil = Some(sigil.into());
+        self
+    }
+
     /// Set the ordered placeholders for a fixed-arity value.
     pub fn value_names<I, S>(mut self, names: I) -> Self
     where
diff --git a/lib/src/spec/cmd.rs b/lib/src/spec/cmd.rs
index 977e2e3bc..918507828 100644
--- a/lib/src/spec/cmd.rs
+++ b/lib/src/spec/cmd.rs
@@ -705,6 +705,18 @@ impl SpecCommand {
                 k => bail_parse!(ctx, child.node.name().span(), "unsupported cmd key {k}"),
             }
         }
+        let mut sigils = std::collections::HashSet::new();
+        for arg in &cmd.args {
+            if let Some(sigil) = &arg.sigil {
+                if !sigils.insert(sigil) {
+                    bail_parse!(
+                        ctx,
+                        node.node.name().span(),
+                        "duplicate argument sigil {sigil:?}"
+                    );
+                }
+            }
+        }
         Ok(cmd)
     }
     pub(crate) fn is_empty(&self) -> bool {

From 22a12aa111c88b9f588e4b82a7703e0eed41917b Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 17:40:44 +0000
Subject: [PATCH 02/11] style: format sigil implementation

---
 conformance/tests/sigil.rs | 14 +++++++++++---
 lib/src/parse.rs           | 16 ++++++++++------
 lib/src/spec/arg.rs        |  6 +++++-
 3 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/conformance/tests/sigil.rs b/conformance/tests/sigil.rs
index e0b4cc049..f801fb8a3 100644
--- a/conformance/tests/sigil.rs
+++ b/conformance/tests/sigil.rs
@@ -23,7 +23,9 @@ fn interpreted_values(spec: &LibSpec, argv: &[&str], name: &str) -> Vec<String>
         .chain(argv.iter().copied())
         .map(str::to_string)
         .collect::<Vec<_>>();
-    let parsed = usage::Parser::new(spec).parse(&argv).expect("valid invocation");
+    let parsed = usage::Parser::new(spec)
+        .parse(&argv)
+        .expect("valid invocation");
     parsed
         .args
         .iter()
@@ -51,8 +53,14 @@ fn sigils_strip_and_do_not_advance_the_positional_cursor() {
 
     let spec: LibSpec = Overlay::to_kdl().parse().expect("derived KDL is valid");
     assert_eq!(spec.cmd.args[0].sigil.as_deref(), Some("+"));
-    assert_eq!(interpreted_values(&spec, &["+node@27", "node"], "tools"), ["node@27"]);
-    assert_eq!(interpreted_values(&spec, &["+node@27", "node"], "command"), ["node"]);
+    assert_eq!(
+        interpreted_values(&spec, &["+node@27", "node"], "tools"),
+        ["node@27"]
+    );
+    assert_eq!(
+        interpreted_values(&spec, &["+node@27", "node"], "command"),
+        ["node"]
+    );
 }
 
 #[test]
diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index 14081f9be..c94269d57 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -2121,17 +2121,18 @@ fn parse_partial_traced(
             .flatten()
         {
             let trailing_value = arg.double_dash == SpecDoubleDashChoices::Automatic;
-            let suppress_trailing_delimiter = out
-                .cmds
-                .iter()
-                .any(|cmd| cmd.dont_delimit_trailing_values);
+            let suppress_trailing_delimiter =
+                out.cmds.iter().any(|cmd| cmd.dont_delimit_trailing_values);
             let delimiter = if suppress_trailing_delimiter && trailing_value {
                 None
             } else {
                 arg.delimiter
             };
             let parts = match delimiter {
-                Some(delimiter) => value.split(delimiter).map(str::to_string).collect::<Vec<_>>(),
+                Some(delimiter) => value
+                    .split(delimiter)
+                    .map(str::to_string)
+                    .collect::<Vec<_>>(),
                 None => vec![value.to_string()],
             };
             let mut refused = false;
@@ -4137,7 +4138,10 @@ fn cursor_skip_sigils(cmd: &SpecCommand, mut idx: usize) -> usize {
     idx
 }
 
-fn match_sigil_arg<'a>(cmd: &'a SpecCommand, word: &'a str) -> Option<(&'a SpecArg, &'a str, &'a str)> {
+fn match_sigil_arg<'a>(
+    cmd: &'a SpecCommand,
+    word: &'a str,
+) -> Option<(&'a SpecArg, &'a str, &'a str)> {
     cmd.args
         .iter()
         .filter_map(|arg| {
diff --git a/lib/src/spec/arg.rs b/lib/src/spec/arg.rs
index 56ef46d15..2b87d847b 100644
--- a/lib/src/spec/arg.rs
+++ b/lib/src/spec/arg.rs
@@ -458,7 +458,11 @@ impl SpecArg {
                 );
             }
             if sigil.chars().any(char::is_whitespace) {
-                bail_parse!(ctx, node.node.name().span(), "sigil cannot contain whitespace");
+                bail_parse!(
+                    ctx,
+                    node.node.name().span(),
+                    "sigil cannot contain whitespace"
+                );
             }
             if arg.double_dash != SpecDoubleDashChoices::Optional {
                 bail_parse!(

From 281b23771858f505c6dfc9cf7be0565211ee8f3d Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 17:53:26 +0000
Subject: [PATCH 03/11] fix(spec): preserve sigil compatibility

---
 derive/src/model.rs |  9 ++++++---
 lib/src/parse.rs    | 12 ++++++------
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/derive/src/model.rs b/derive/src/model.rs
index f96e569b8..d0bfe02d6 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -7124,7 +7124,8 @@ mod tests {
         assert!(matches!(
             native.fields[4].kind,
             Kind::Arg {
-                double_dash: DoubleDash::Required
+                double_dash: DoubleDash::Required,
+                ..
             }
         ));
 
@@ -7201,7 +7202,8 @@ mod tests {
         assert!(matches!(
             trailing.fields[0].kind,
             Kind::Arg {
-                double_dash: DoubleDash::Automatic
+                double_dash: DoubleDash::Automatic,
+                ..
             }
         ));
         let required_boundary = cli(r#"
@@ -7214,7 +7216,8 @@ mod tests {
         assert!(matches!(
             required_boundary.fields[0].kind,
             Kind::Arg {
-                double_dash: DoubleDash::Required
+                double_dash: DoubleDash::Required,
+                ..
             }
         ));
     }
diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index c94269d57..9ff137cec 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -330,12 +330,6 @@ pub enum TokenRole {
         arg: Arc<SpecArg>,
         values: Vec<String>,
     },
-    /// Filled a sigil-classified positional after removing its declared prefix.
-    Sigil {
-        arg: Arc<SpecArg>,
-        sigil: String,
-        values: Vec<String>,
-    },
     /// An explicit `--`, consumed as a separator.
     Separator,
     /// A word the parser answers itself rather than binding: `--help`, `-h`, `--version`,
@@ -361,6 +355,12 @@ pub enum TokenRole {
     External,
     /// The parser stopped before this word — a help request, a refused value.
     Unread,
+    /// Filled a sigil-classified positional after removing its declared prefix.
+    Sigil {
+        arg: Arc<SpecArg>,
+        sigil: String,
+        values: Vec<String>,
+    },
 }
 
 /// One word of the command line, and what it became.

From 8f4c7c86d5b3fb4f522c37e5e77c1cb77edfa00e Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 17:58:07 +0000
Subject: [PATCH 04/11] fix(parse): handle sigil argument edge cases

---
 cli/src/cli/explain.rs |  6 +++++-
 go/argv/parser.go      | 12 ++++++------
 go/argv/parser_test.go |  9 +++++++++
 lib/src/parse.rs       | 23 ++++++++++++++++++++++-
 4 files changed, 42 insertions(+), 8 deletions(-)

diff --git a/cli/src/cli/explain.rs b/cli/src/cli/explain.rs
index 415853c36..00ed5dacc 100644
--- a/cli/src/cli/explain.rs
+++ b/cli/src/cli/explain.rs
@@ -667,7 +667,11 @@ fn arg_origins(out: &ParseOutput, arg: &SpecArg) -> Vec<OriginRow> {
     for token in &out.tokens {
         for role in &token.roles {
             match role {
-                TokenRole::Arg { arg: a, .. } if a.name == arg.name => tokens.push(token.index),
+                TokenRole::Arg { arg: a, .. } | TokenRole::Sigil { arg: a, .. }
+                    if a.name == arg.name =>
+                {
+                    tokens.push(token.index)
+                }
                 TokenRole::UnknownFlag { bound_as: Some(a) } if a.name == arg.name => {
                     tokens.push(token.index)
                 }
diff --git a/go/argv/parser.go b/go/argv/parser.go
index 7fbe22b68..108e192ca 100644
--- a/go/argv/parser.go
+++ b/go/argv/parser.go
@@ -606,12 +606,6 @@ func (p *Parser) word(token string) bool {
 			return p.emit(Event{Kind: KindCommand, Command: d})
 		}
 
-		if arg, sigil := p.matchSigilArg(token); arg != nil {
-			return p.emit(Event{
-				Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
-			})
-		}
-
 		// An unmatched word that names no subcommand is forwarded as an external
 		// command: this word, then every token after it, including flags. Known
 		// subcommands already won above, and a default subcommand already caught.
@@ -623,6 +617,12 @@ func (p *Parser) word(token string) bool {
 		}
 	}
 
+	if arg, sigil := p.matchSigilArg(token); arg != nil {
+		return p.emit(Event{
+			Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
+		})
+	}
+
 	p.skipSigilArgs()
 	p.reserveForRequiredPositionals()
 	arg := p.nextArg()
diff --git a/go/argv/parser_test.go b/go/argv/parser_test.go
index 1aaf5b322..96846fa07 100644
--- a/go/argv/parser_test.go
+++ b/go/argv/parser_test.go
@@ -102,6 +102,15 @@ func TestAllowMissingPositionalReservesLastWord(t *testing.T) {
 	}
 }
 
+func TestSigilArgumentMatchesAfterOrdinaryPositional(t *testing.T) {
+	ordinary := &Arg{Key: 90, Name: "ordinary"}
+	tool := &Arg{Key: 91, Name: "tool", Sigil: "@"}
+	cmd := &Command{Name: "ex", Args: []*Arg{ordinary, tool}}
+	if got := collect(cmd, "file", "@node"); got != "arg:ordinary=file arg:tool=node" {
+		t.Fatalf("got %q", got)
+	}
+}
+
 func TestBinding(t *testing.T) {
 	cases := []struct {
 		name string
diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index 9ff137cec..d8968b5ae 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -2178,6 +2178,7 @@ fn parse_partial_traced(
         }
 
         if out.cmd.allow_missing_positional {
+            next_arg_idx = cursor_skip_sigils(&out.cmd, next_arg_idx);
             while let Some(current) = out.cmd.args.get(next_arg_idx) {
                 if current.required || out.args.contains_key(current) {
                     break;
@@ -2196,7 +2197,7 @@ fn parse_partial_traced(
                 if remaining_values > required_after {
                     break;
                 }
-                next_arg_idx += 1;
+                next_arg_idx = cursor_skip_sigils(&out.cmd, next_arg_idx + 1);
             }
         }
 
@@ -6600,6 +6601,26 @@ arg "<required>"
         assert!(matches!(value, ParseValue::String(value) if value == "value"));
     }
 
+    #[test]
+    fn sigil_args_do_not_block_optional_positional_skipping() {
+        let spec: Spec = r#"name "ex"
+bin "ex"
+allow_missing_positional #true
+arg "[optional]"
+arg "[tool]" sigil="@"
+arg "<required>"
+"#
+        .parse()
+        .unwrap();
+
+        let out = parse(&spec, &input(&["ex", "@node", "value"])).unwrap();
+        assert!(!out.args.keys().any(|arg| arg.name == "optional"));
+        let tool = out.args.keys().find(|arg| arg.name == "tool").unwrap();
+        let required = out.args.keys().find(|arg| arg.name == "required").unwrap();
+        assert_eq!(out.args[tool].to_string(), "node");
+        assert_eq!(out.args[required].to_string(), "value");
+    }
+
     #[test]
     fn unknown_flags_can_be_rejected_for_the_whole_cli() {
         let spec: Spec =

From ea080785e00b5432e7096b8e574bdc47aaad93ff Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:11:06 +0000
Subject: [PATCH 05/11] fix(argv): prioritize sigils over external commands

---
 go/argv/parser.go      | 16 ++++++++++++----
 go/argv/parser_test.go |  4 ++++
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/go/argv/parser.go b/go/argv/parser.go
index 108e192ca..0f03c2f17 100644
--- a/go/argv/parser.go
+++ b/go/argv/parser.go
@@ -606,6 +606,12 @@ func (p *Parser) word(token string) bool {
 			return p.emit(Event{Kind: KindCommand, Command: d})
 		}
 
+		if arg, sigil := p.matchSigilArg(token); arg != nil {
+			return p.emit(Event{
+				Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
+			})
+		}
+
 		// An unmatched word that names no subcommand is forwarded as an external
 		// command: this word, then every token after it, including flags. Known
 		// subcommands already won above, and a default subcommand already caught.
@@ -617,10 +623,12 @@ func (p *Parser) word(token string) bool {
 		}
 	}
 
-	if arg, sigil := p.matchSigilArg(token); arg != nil {
-		return p.emit(Event{
-			Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
-		})
+	if p.argFilled {
+		if arg, sigil := p.matchSigilArg(token); arg != nil {
+			return p.emit(Event{
+				Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
+			})
+		}
 	}
 
 	p.skipSigilArgs()
diff --git a/go/argv/parser_test.go b/go/argv/parser_test.go
index 96846fa07..1f954ddaf 100644
--- a/go/argv/parser_test.go
+++ b/go/argv/parser_test.go
@@ -105,6 +105,10 @@ func TestAllowMissingPositionalReservesLastWord(t *testing.T) {
 func TestSigilArgumentMatchesAfterOrdinaryPositional(t *testing.T) {
 	ordinary := &Arg{Key: 90, Name: "ordinary"}
 	tool := &Arg{Key: 91, Name: "tool", Sigil: "@"}
+	external := &Command{Name: "ex", Args: []*Arg{ordinary, tool}, ExternalSubcommand: true}
+	if got := collect(external, "@node"); got != "arg:tool=node" {
+		t.Fatalf("leading sigil: got %q", got)
+	}
 	cmd := &Command{Name: "ex", Args: []*Arg{ordinary, tool}}
 	if got := collect(cmd, "file", "@node"); got != "arg:ordinary=file arg:tool=node" {
 		t.Fatalf("got %q", got)

From 9403fbd9a74872957c0f5a20f5beeaa1bea329c8 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 18:32:23 +0000
Subject: [PATCH 06/11] docs(cli): refresh generated minimum version

---
 docs/cli/reference/commands.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cli/reference/commands.json b/docs/cli/reference/commands.json
index f667de4fd..1d79dd539 100644
--- a/docs/cli/reference/commands.json
+++ b/docs/cli/reference/commands.json
@@ -2020,6 +2020,6 @@
   "source_code_link_template": "{%- set path = path | replace(from='-', to='_') -%}\n{%- if cmd.subcommands | length > 0 -%}\n{%- set path = path ~ \"/mod.rs\" -%}\n{%- elif path in [\"bash\", \"fish\", \"powershell\", \"zsh\"] -%}\n{%- set path = \"shell.rs\" -%}\n{%- else -%}\n{%- set path = path ~ \".rs\" -%}\n{%- endif -%}\nhttps://github.com/jdx/usage/blob/main/cli/src/cli/{{path}}",
   "repository": "https://github.com/jdx/usage",
   "about": "CLI for working with usage-based CLIs",
-  "min_usage_version": "4.0",
+  "min_usage_version": "6.5",
   "unknown_flags": "error"
 }

From ad3d887ff62e9d5d6d4f49fdeb3340cddcfa38d6 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 20:09:07 +0000
Subject: [PATCH 07/11] fix(parse): tighten sigil argument semantics

---
 argv/src/lib.rs              | 40 +++++++++++++++++++--
 conformance/src/argv.rs      |  1 +
 conformance/src/lib.rs       |  2 ++
 conformance/src/reference.rs |  2 ++
 corpus/14-sigil.json         | 68 ++++++++++++++++++++++++++----------
 derive/src/model.rs          | 27 ++++++++++++--
 go/argv/parser.go            | 22 ++++++++++--
 lib/src/parse.rs             | 11 +++++-
 lib/src/spec/cmd.rs          | 52 +++++++++++++++++++++++++--
 lib/src/spec/mod.rs          |  4 +++
 10 files changed, 198 insertions(+), 31 deletions(-)

diff --git a/argv/src/lib.rs b/argv/src/lib.rs
index 105720c45..aee5dff6e 100644
--- a/argv/src/lib.rs
+++ b/argv/src/lib.rs
@@ -2236,6 +2236,16 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
             // Known subcommands and the default route keep precedence. A sigil positional
             // then claims its classified word before an external-subcommand catch-all can.
             if let Some((arg, sigil)) = self.match_sigil_arg(token) {
+                if token.len() == sigil.len() {
+                    return Err(invalid_value_error(
+                        arg.name,
+                        as_str(token).unwrap_or_default().to_string(),
+                        format!(
+                            "expected a value after sigil {:?}",
+                            as_str(sigil).unwrap_or_default()
+                        ),
+                    ));
+                }
                 return Ok(Event::Arg {
                     arg,
                     value: &token[sigil.len()..],
@@ -2259,6 +2269,26 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
             }
         }
 
+        if self.arg_filled && !self.flags_stopped {
+            if let Some((arg, sigil)) = self.match_sigil_arg(token) {
+                if token.len() == sigil.len() {
+                    return Err(invalid_value_error(
+                        arg.name,
+                        as_str(token).unwrap_or_default().to_string(),
+                        format!(
+                            "expected a value after sigil {:?}",
+                            as_str(sigil).unwrap_or_default()
+                        ),
+                    ));
+                }
+                return Ok(Event::Arg {
+                    arg,
+                    value: &token[sigil.len()..],
+                    delimit: true,
+                });
+            }
+        }
+
         self.skip_sigil_args();
         self.reserve_for_required_positionals();
         let Some(arg) = self.next_arg() else {
@@ -2380,12 +2410,16 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
         if self.flags_stopped {
             return None;
         }
-        self.cmd
-            .args
+        let own = self.cmd.args.iter().copied();
+        let inherited = self.ancestors[..self.depth]
             .iter()
+            .rev()
+            .filter_map(|cmd| *cmd)
+            .flat_map(|cmd| cmd.args.iter().copied());
+        own.chain(inherited)
             .filter_map(|arg| {
                 let sigil = arg.sigil?;
-                (token.len() > sigil.len() && token.starts_with(sigil)).then_some((*arg, sigil))
+                (token.len() >= sigil.len() && token.starts_with(sigil)).then_some((arg, sigil))
             })
             .max_by_key(|(_, sigil)| sigil.len())
     }
diff --git a/conformance/src/argv.rs b/conformance/src/argv.rs
index ca8e67d53..da6e99e97 100644
--- a/conformance/src/argv.rs
+++ b/conformance/src/argv.rs
@@ -208,6 +208,7 @@ fn code(err: Error<'_, '_>) -> ErrorCode {
         Error::MissingFlagValue { .. } => ErrorCode::MissingFlagValue,
         Error::UnexpectedArg { .. } => ErrorCode::UnexpectedArg,
         Error::ArgRequiresDoubleDash { .. } => ErrorCode::ArgRequiresDoubleDash,
+        Error::InvalidValue(_) => ErrorCode::InvalidValue,
         // Binding does raise this one, and only this one of the bounds: a `var_max` stops a
         // collection rather than judging it, so it can only be *exceeded* when a delimiter
         // makes one word several values — which is a question about where a word lands, and
diff --git a/conformance/src/lib.rs b/conformance/src/lib.rs
index 1015b6088..e465bdffc 100644
--- a/conformance/src/lib.rs
+++ b/conformance/src/lib.rs
@@ -170,6 +170,8 @@ pub enum ErrorCode {
     UnexpectedArg,
     /// A value was given that is not among the declared choices.
     InvalidChoice,
+    /// A value was rejected before typed conversion.
+    InvalidValue,
     /// A positional declared `double_dash="required"` was given before `--`.
     ArgRequiresDoubleDash,
     /// A variadic got fewer values than `var_min`.
diff --git a/conformance/src/reference.rs b/conformance/src/reference.rs
index 86bba2643..c16904672 100644
--- a/conformance/src/reference.rs
+++ b/conformance/src/reference.rs
@@ -141,6 +141,8 @@ fn classify(msg: &str) -> Observed {
         }
     } else if msg.contains("Invalid choice") || msg.contains("expected one of") {
         ErrorCode::InvalidChoice
+    } else if msg.contains("Invalid value") {
+        ErrorCode::InvalidValue
     } else if msg.contains("Unexpected argument") || msg.contains("unexpected") {
         ErrorCode::UnexpectedArg
     } else {
diff --git a/corpus/14-sigil.json b/corpus/14-sigil.json
index 9f6703381..a2db1c67d 100644
--- a/corpus/14-sigil.json
+++ b/corpus/14-sigil.json
@@ -18,21 +18,6 @@
         }
       }
     },
-    {
-      "id": "longest-sigil-prefix-wins",
-      "doc": "Overlapping sigils select the longest matching declaration.",
-      "spec": "name \"ex\"\nbin \"ex\"\narg \"[short]...\" sigil=\"+\"\narg \"[long]...\" sigil=\"++\"\narg \"<command>\"\n",
-      "argv": ["++edge", "+stable", "run"],
-      "expect": {
-        "ok": {
-          "args": {
-            "short": ["stable"],
-            "long": ["edge"],
-            "command": "run"
-          }
-        }
-      }
-    },
     {
       "id": "double-dash-protects-sigil",
       "doc": "After an explicit separator the same prefix is ordinary data.",
@@ -45,11 +30,11 @@
       }
     },
     {
-      "id": "bare-sigil-falls-through",
-      "doc": "A prefix with no value is not a classified argument.",
+      "id": "bare-sigil-is-invalid",
+      "doc": "A bare classifier is an empty sigil value, not ordinary positional data.",
       "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\narg \"<command>\"\n",
       "argv": ["+"],
-      "expect": { "ok": { "args": { "command": "+" } } }
+      "expect": { "error": "invalid_value" }
     },
     {
       "id": "flag-awaiting-value-outranks-sigil",
@@ -75,6 +60,53 @@
         }
       }
     },
+    {
+      "id": "sigil-after-ordinary-positional",
+      "doc": "A classified value may follow an ordinary positional while flag parsing remains active.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\narg \"<command>\"\narg \"[args]...\"\n",
+      "argv": ["run", "+node@27", "file"],
+      "expect": {
+        "ok": {
+          "args": { "tools": ["node@27"], "command": "run", "args": ["file"] }
+        }
+      }
+    },
+    {
+      "id": "ancestor-sigil-after-subcommand",
+      "doc": "A sigil declared by an ancestor remains in scope after an explicit subcommand or alias.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\ncmd \"build\" { alias \"b\"; arg \"<target>\" }\n",
+      "argv": ["b", "+node@27", "app"],
+      "expect": {
+        "ok": {
+          "cmd": ["build"],
+          "args": { "tools": ["node@27"], "target": "app" }
+        }
+      }
+    },
+    {
+      "id": "sigil-before-default-subcommand",
+      "doc": "A sigil does not prevent a later ordinary word from selecting the default subcommand.",
+      "spec": "name \"ex\"\nbin \"ex\"\ndefault_subcommand \"run\"\narg \"[tools]...\" sigil=\"+\"\ncmd \"run\" { arg \"<command>\" }\n",
+      "argv": ["+node@27", "node"],
+      "expect": {
+        "ok": {
+          "cmd": ["run"],
+          "args": { "tools": ["node@27"], "command": "node" }
+        }
+      }
+    },
+    {
+      "id": "sigil-outranks-external-command",
+      "doc": "A declared sigil binds before an external-command catch-all forwards the remaining argv.",
+      "spec": "name \"ex\"\nbin \"ex\"\nexternal_subcommand #true\narg \"[tools]...\" sigil=\"+\"\n",
+      "argv": ["+node@27", "node", "-v"],
+      "expect": {
+        "ok": {
+          "args": { "tools": ["node@27"] },
+          "external": ["node", "-v"]
+        }
+      }
+    },
     {
       "id": "automatic-boundary-protects-later-sigil",
       "doc": "Once an automatic trailing positional starts, later sigil-shaped words are data.",
diff --git a/derive/src/model.rs b/derive/src/model.rs
index d0bfe02d6..bdc426563 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -1684,13 +1684,16 @@ impl Cli {
                 Kind::Skip => {}
                 Kind::Arg { double_dash, sigil } => {
                     if let Some(sigil) = sigil {
-                        if let Some((_, first)) =
-                            seen_sigils.iter().find(|(seen, _)| *seen == sigil)
+                        if let Some((seen, first)) = seen_sigils
+                            .iter()
+                            .find(|(seen, _)| seen.starts_with(sigil) || sigil.starts_with(*seen))
                         {
                             return Err(dup(
                                 field.span,
                                 *first,
-                                &format!("sigil {sigil:?} is declared twice"),
+                                &format!(
+                                    "argument sigils must not overlap: {seen:?} and {sigil:?}"
+                                ),
                             ));
                         }
                         seen_sigils.push((sigil, field.span));
@@ -6710,6 +6713,24 @@ mod tests {
         }
     }
 
+    #[test]
+    fn overlapping_sigil_fields_are_rejected() {
+        let error = rejection(
+            r#"
+            struct Args {
+                #[usage(sigil = "+")]
+                short: Vec<String>,
+                #[usage(sigil = "++")]
+                long: Vec<String>,
+            }
+            "#,
+        );
+        assert!(
+            error.contains("argument sigils must not overlap"),
+            "{error}"
+        );
+    }
+
     #[test]
     fn unit_structs_are_empty_commands() {
         let cli = cli("struct Empty;").expect("unit commands should compile");
diff --git a/go/argv/parser.go b/go/argv/parser.go
index 0f03c2f17..ef6153edb 100644
--- a/go/argv/parser.go
+++ b/go/argv/parser.go
@@ -607,6 +607,10 @@ func (p *Parser) word(token string) bool {
 		}
 
 		if arg, sigil := p.matchSigilArg(token); arg != nil {
+			if len(token) == len(sigil) {
+				return p.fail(Error{Code: CodeInvalidValue, Name: arg.Name, Value: token,
+					Reason: "expected a value after sigil " + sigil})
+			}
 			return p.emit(Event{
 				Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
 			})
@@ -625,6 +629,10 @@ func (p *Parser) word(token string) bool {
 
 	if p.argFilled {
 		if arg, sigil := p.matchSigilArg(token); arg != nil {
+			if len(token) == len(sigil) {
+				return p.fail(Error{Code: CodeInvalidValue, Name: arg.Name, Value: token,
+					Reason: "expected a value after sigil " + sigil})
+			}
 			return p.emit(Event{
 				Kind: KindArg, Arg: arg, Value: token[len(sigil):], HasValue: true, Delimit: true,
 			})
@@ -745,9 +753,17 @@ func (p *Parser) matchSigilArg(token string) (*Arg, string) {
 	}
 	var best *Arg
 	bestSigil := ""
-	for _, arg := range p.cmd.Args {
-		if arg.Sigil != "" && len(token) > len(arg.Sigil) && len(arg.Sigil) > len(bestSigil) && token[:len(arg.Sigil)] == arg.Sigil {
-			best, bestSigil = arg, arg.Sigil
+	match := func(cmd *Command) {
+		for _, arg := range cmd.Args {
+			if arg.Sigil != "" && len(token) >= len(arg.Sigil) && len(arg.Sigil) > len(bestSigil) && token[:len(arg.Sigil)] == arg.Sigil {
+				best, bestSigil = arg, arg.Sigil
+			}
+		}
+	}
+	match(p.cmd)
+	for i := p.depth - 1; i >= 0; i-- {
+		if p.ancestors[i] != nil {
+			match(p.ancestors[i])
 		}
 	}
 	return best, bestSigil
diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index d8968b5ae..386a47698 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -2120,6 +2120,15 @@ fn parse_partial_traced(
             .then(|| match_sigil_arg_chain(&out.cmds, &w))
             .flatten()
         {
+            if value.is_empty() {
+                out.errors.push(UsageErr::InvalidValue {
+                    name: arg.name.clone(),
+                    value: w.clone(),
+                    reason: format!("expected a value after sigil {sigil:?}"),
+                });
+                record_stop(&mut out, next_arg_idx, seen_double_dash, trace, &input);
+                return Ok((out, overridden_flags));
+            }
             let trailing_value = arg.double_dash == SpecDoubleDashChoices::Automatic;
             let suppress_trailing_delimiter =
                 out.cmds.iter().any(|cmd| cmd.dont_delimit_trailing_values);
@@ -4148,7 +4157,7 @@ fn match_sigil_arg<'a>(
         .filter_map(|arg| {
             let sigil = arg.sigil.as_deref()?;
             let value = word.strip_prefix(sigil)?;
-            (!value.is_empty()).then_some((arg, sigil, value))
+            Some((arg, sigil, value))
         })
         .max_by_key(|(_, sigil, _)| sigil.len())
 }
diff --git a/lib/src/spec/cmd.rs b/lib/src/spec/cmd.rs
index 918507828..20ce7bfd6 100644
--- a/lib/src/spec/cmd.rs
+++ b/lib/src/spec/cmd.rs
@@ -705,20 +705,46 @@ impl SpecCommand {
                 k => bail_parse!(ctx, child.node.name().span(), "unsupported cmd key {k}"),
             }
         }
-        let mut sigils = std::collections::HashSet::new();
+        let mut sigils: Vec<&str> = Vec::new();
         for arg in &cmd.args {
             if let Some(sigil) = &arg.sigil {
-                if !sigils.insert(sigil) {
+                if let Some(existing) = sigils
+                    .iter()
+                    .find(|existing| existing.starts_with(sigil) || sigil.starts_with(**existing))
+                {
                     bail_parse!(
                         ctx,
                         node.node.name().span(),
-                        "duplicate argument sigil {sigil:?}"
+                        "argument sigils must not overlap: {existing:?} and {sigil:?}"
                     );
                 }
+                sigils.push(sigil);
             }
         }
         Ok(cmd)
     }
+
+    pub(crate) fn validate_sigil_prefixes(&self) -> Result<(), String> {
+        fn validate(cmd: &SpecCommand, ancestors: &[String]) -> Result<(), String> {
+            let mut active = ancestors.to_vec();
+            for sigil in cmd.args.iter().filter_map(|arg| arg.sigil.as_ref()) {
+                if let Some(existing) = active.iter().find(|existing| {
+                    existing.starts_with(sigil.as_str()) || sigil.starts_with(existing.as_str())
+                }) {
+                    return Err(format!(
+                        "argument sigils must not overlap: {existing:?} and {sigil:?}"
+                    ));
+                }
+                active.push(sigil.clone());
+            }
+            for subcommand in cmd.subcommands.values() {
+                validate(subcommand, &active)?;
+            }
+            Ok(())
+        }
+
+        validate(self, &[])
+    }
     pub(crate) fn is_empty(&self) -> bool {
         self.args.is_empty()
             && self.flags.is_empty()
@@ -1623,6 +1649,26 @@ mod tests {
     use crate::Spec;
     use insta::assert_snapshot;
 
+    #[test]
+    fn overlapping_sigils_are_rejected_on_one_command_and_across_subcommands() {
+        for spec in [
+            r#"bin "ex"
+arg "[short]..." sigil="+"
+arg "[long]..." sigil="++"
+"#,
+            r#"bin "ex"
+arg "[short]..." sigil="+"
+cmd "run" { arg "[long]..." sigil="++" }
+"#,
+        ] {
+            let error = Spec::parse(&Default::default(), spec).unwrap_err();
+            assert!(
+                format!("{error:?}").contains("argument sigils must not overlap"),
+                "{error:?}"
+            );
+        }
+    }
+
     #[test]
     fn test_effect_prop_and_child_node() {
         let spec = Spec::parse(
diff --git a/lib/src/spec/mod.rs b/lib/src/spec/mod.rs
index 1438eba29..79c4c6fbd 100644
--- a/lib/src/spec/mod.rs
+++ b/lib/src/spec/mod.rs
@@ -779,6 +779,10 @@ impl Spec {
         if resolve_outputs {
             output::resolve_selectors(&mut schema)?;
         }
+        schema
+            .cmd
+            .validate_sigil_prefixes()
+            .map_err(|message| ctx.build_err(message, (0, ctx.spec.len()).into()))?;
         schema.sources.extend(ctx.sources());
         set_subcommand_ancestors(&mut schema.cmd, &[]);
         Ok(schema)

From 97f31e63bcd0c9942f582475c1fb59ee3b3a36f5 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 20:36:38 +0000
Subject: [PATCH 08/11] fix(parse): address sigil routing edge cases

---
 argv/src/lib.rs      |  7 +++++--
 corpus/14-sigil.json | 23 +++++++++++++++++++++++
 derive/src/model.rs  | 22 ++++++++++++++++++++++
 go/argv/parser.go    |  5 +++--
 lib/src/parse.rs     |  9 ++++++---
 lib/src/spec/arg.rs  | 24 ++++++++++++++++++++++++
 6 files changed, 83 insertions(+), 7 deletions(-)

diff --git a/argv/src/lib.rs b/argv/src/lib.rs
index aee5dff6e..e09f97b30 100644
--- a/argv/src/lib.rs
+++ b/argv/src/lib.rs
@@ -2439,14 +2439,17 @@ impl<'t: 'v, 'a, 'v> Parser<'t, 'a, 'v> {
             }
             let required_after = self.cmd.args[self.arg_pos + 1..]
                 .iter()
-                .filter(|arg| arg.required)
+                .filter(|arg| arg.required && arg.sigil.is_none())
                 .count();
             if required_after == 0 {
                 return;
             }
             let remaining_values = 1 + self.argv[self.pos..]
                 .iter()
-                .filter(|word| self.flags_stopped || !is_flag_like(bytes(word)))
+                .filter(|word| {
+                    (self.flags_stopped || !is_flag_like(bytes(word)))
+                        && self.match_sigil_arg(bytes(word)).is_none()
+                })
                 .count();
             if remaining_values > required_after {
                 return;
diff --git a/corpus/14-sigil.json b/corpus/14-sigil.json
index a2db1c67d..d7a295dd2 100644
--- a/corpus/14-sigil.json
+++ b/corpus/14-sigil.json
@@ -83,6 +83,29 @@
         }
       }
     },
+    {
+      "id": "ancestor-sigil-preserves-nested-subcommand-routing",
+      "doc": "An inherited sigil between two command names does not close nested subcommand routing.",
+      "spec": "name \"ex\"\nbin \"ex\"\narg \"[tools]...\" sigil=\"+\"\ncmd \"build\" { cmd \"deploy\" {} }\n",
+      "argv": ["build", "+node@27", "deploy"],
+      "expect": {
+        "ok": {
+          "cmd": ["build", "deploy"],
+          "args": { "tools": ["node@27"] }
+        }
+      }
+    },
+    {
+      "id": "missing-positional-ignores-filled-required-sigil",
+      "doc": "A required sigil already filled does not reserve an ordinary positional slot.",
+      "spec": "name \"ex\"\nbin \"ex\"\nallow_missing_positional #true\narg \"[optional]\"\narg \"<tools>...\" sigil=\"+\"\narg \"<required>\"\n",
+      "argv": ["+node@27", "first", "last"],
+      "expect": {
+        "ok": {
+          "args": { "optional": "first", "tools": ["node@27"], "required": "last" }
+        }
+      }
+    },
     {
       "id": "sigil-before-default-subcommand",
       "doc": "A sigil does not prevent a later ordinary word from selecting the default subcommand.",
diff --git a/derive/src/model.rs b/derive/src/model.rs
index bdc426563..2ee81865f 100644
--- a/derive/src/model.rs
+++ b/derive/src/model.rs
@@ -3847,6 +3847,12 @@ impl Field {
                     "a sigil argument cannot declare `value_terminator`",
                 ));
             }
+            if var_min.is_some() || var_max.is_some() {
+                return Err(syn::Error::new(
+                    span,
+                    "a sigil argument cannot declare `var_min` or `var_max`",
+                ));
+            }
         }
 
         if require_equals {
@@ -6731,6 +6737,22 @@ mod tests {
         );
     }
 
+    #[test]
+    fn bounded_sigil_fields_are_rejected() {
+        let error = rejection(
+            r#"
+            struct Args {
+                #[usage(sigil = "+", var_max = 2)]
+                tools: Vec<String>,
+            }
+            "#,
+        );
+        assert!(
+            error.contains("cannot declare `var_min` or `var_max`"),
+            "{error}"
+        );
+    }
+
     #[test]
     fn unit_structs_are_empty_commands() {
         let cli = cli("struct Empty;").expect("unit commands should compile");
diff --git a/go/argv/parser.go b/go/argv/parser.go
index ef6153edb..60dc184b2 100644
--- a/go/argv/parser.go
+++ b/go/argv/parser.go
@@ -779,7 +779,7 @@ func (p *Parser) reserveForRequiredPositionals() {
 	for p.argPos < len(p.cmd.Args) && !p.cmd.Args[p.argPos].Required {
 		requiredAfter := 0
 		for _, arg := range p.cmd.Args[p.argPos+1:] {
-			if arg.Required {
+			if arg.Required && arg.Sigil == "" {
 				requiredAfter++
 			}
 		}
@@ -788,7 +788,8 @@ func (p *Parser) reserveForRequiredPositionals() {
 		}
 		remainingValues := 1
 		for _, word := range p.argv[p.pos:] {
-			if p.flagsStopped || !isFlagLike(word) {
+			arg, _ := p.matchSigilArg(word)
+			if (p.flagsStopped || !isFlagLike(word)) && arg == nil {
 				remainingValues++
 			}
 		}
diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index 386a47698..ea8a67807 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -1472,7 +1472,7 @@ fn parse_partial_traced(
             }
             // Sigil-classified positionals do not occupy the ordinary positional cursor and
             // therefore do not close subcommand routing. Phase 2 binds and strips them.
-            if match_sigil_arg(&out.cmd, &input[idx].word).is_some() {
+            if match_sigil_arg_chain(&out.cmds, &input[idx].word).is_some() {
                 idx += 1;
                 continue;
             }
@@ -2194,14 +2194,17 @@ fn parse_partial_traced(
                 }
                 let required_after = out.cmd.args[next_arg_idx + 1..]
                     .iter()
-                    .filter(|arg| arg.required)
+                    .filter(|arg| arg.required && arg.sigil.is_none())
                     .count();
                 if required_after == 0 {
                     break;
                 }
                 let remaining_values = 1 + input
                     .iter()
-                    .filter(|token| !enable_flags || !is_flag_like(&token.word))
+                    .filter(|token| {
+                        (!enable_flags || !is_flag_like(&token.word))
+                            && match_sigil_arg_chain(&out.cmds, &token.word).is_none()
+                    })
                     .count();
                 if remaining_values > required_after {
                     break;
diff --git a/lib/src/spec/arg.rs b/lib/src/spec/arg.rs
index 2b87d847b..0b37c5e92 100644
--- a/lib/src/spec/arg.rs
+++ b/lib/src/spec/arg.rs
@@ -478,6 +478,13 @@ impl SpecArg {
                     "sigil arguments cannot declare value_terminator"
                 );
             }
+            if arg.var_min.is_some() || arg.var_max.is_some() {
+                bail_parse!(
+                    ctx,
+                    node.node.name().span(),
+                    "sigil arguments cannot declare var_min or var_max"
+                );
+            }
         }
         #[cfg(feature = "validation")]
         if let Some(expression) = &arg.validate {
@@ -1268,6 +1275,23 @@ flag "--trigger"
     }
 }
 
+#[cfg(test)]
+mod sigil_tests {
+    use crate::Spec;
+
+    #[test]
+    fn sigil_arguments_reject_value_bounds() {
+        for bound in ["var_min=1", "var_max=2"] {
+            let spec = format!("arg \"[tools]...\" sigil=\"+\" {bound}\n");
+            let error = spec.parse::<Spec>().unwrap_err();
+            assert!(
+                format!("{error:?}").contains("cannot declare var_min or var_max"),
+                "{error:?}"
+            );
+        }
+    }
+}
+
 #[cfg(test)]
 mod delimiter_tests {
     use crate::Spec;

From 850ec97eb5a509c1c8a611760b408f5482d764ac Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 20:43:55 +0000
Subject: [PATCH 09/11] fix(parse): count sigil shapes after boundaries

---
 corpus/14-sigil.json | 11 +++++++++++
 lib/src/parse.rs     |  4 +++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/corpus/14-sigil.json b/corpus/14-sigil.json
index d7a295dd2..c4dfc6100 100644
--- a/corpus/14-sigil.json
+++ b/corpus/14-sigil.json
@@ -106,6 +106,17 @@
         }
       }
     },
+    {
+      "id": "missing-positional-counts-sigil-shape-after-double-dash",
+      "doc": "After flag parsing stops, sigil-shaped words count as ordinary values during positional reservation.",
+      "spec": "name \"ex\"\nbin \"ex\"\nallow_missing_positional #true\narg \"[optional]\"\narg \"[tools]...\" sigil=\"+\"\narg \"<required>\"\n",
+      "argv": ["--", "first", "+literal"],
+      "expect": {
+        "ok": {
+          "args": { "optional": "first", "required": "+literal" }
+        }
+      }
+    },
     {
       "id": "sigil-before-default-subcommand",
       "doc": "A sigil does not prevent a later ordinary word from selecting the default subcommand.",
diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index ea8a67807..fb3ac5ad8 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -2203,7 +2203,9 @@ fn parse_partial_traced(
                     .iter()
                     .filter(|token| {
                         (!enable_flags || !is_flag_like(&token.word))
-                            && match_sigil_arg_chain(&out.cmds, &token.word).is_none()
+                            && (!enable_flags
+                                || restart_seen
+                                || match_sigil_arg_chain(&out.cmds, &token.word).is_none())
                     })
                     .count();
                 if remaining_values > required_after {

From 61e24eff169b3cb57e075f31bacdc93f7fb8019c Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 20:55:46 +0000
Subject: [PATCH 10/11] fix(parse): prioritize default subcommand over sigils

---
 lib/src/parse.rs | 40 ++++++++++++++++++++++++++++++++++------
 1 file changed, 34 insertions(+), 6 deletions(-)

diff --git a/lib/src/parse.rs b/lib/src/parse.rs
index fb3ac5ad8..3f1481b66 100644
--- a/lib/src/parse.rs
+++ b/lib/src/parse.rs
@@ -1470,12 +1470,6 @@ fn parse_partial_traced(
                 idx += 1;
                 continue;
             }
-            // Sigil-classified positionals do not occupy the ordinary positional cursor and
-            // therefore do not close subcommand routing. Phase 2 binds and strips them.
-            if match_sigil_arg_chain(&out.cmds, &input[idx].word).is_some() {
-                idx += 1;
-                continue;
-            }
             // Found a word that's not a flag or subcommand
             // Check if we should use the default_subcommand (only once, and only at the
             // root, which is the only place a spec can declare one — `out.cmds` holds just
@@ -1524,6 +1518,14 @@ fn parse_partial_traced(
                     }
                 }
             }
+            // Sigil-classified positionals do not occupy the ordinary positional cursor and
+            // therefore do not close subcommand routing. Phase 2 binds and strips them. A
+            // default subcommand gets first refusal so interpreted and compiled routing agree
+            // when the root sigil and the default command can both accept this word.
+            if match_sigil_arg_chain(&out.cmds, &input[idx].word).is_some() {
+                idx += 1;
+                continue;
+            }
             // An unmatched word that names no subcommand is forwarded as an external
             // command: this word, then every token after it, including flags. Known
             // subcommands already won above, and a default_subcommand already caught.
@@ -6762,6 +6764,32 @@ cmd "build" {
         assert_eq!(value.to_string(), "mytask");
     }
 
+    #[test]
+    fn default_subcommand_outranks_root_sigil_arg() {
+        let spec: Spec = r#"
+name "test"
+bin "test"
+default_subcommand "run"
+arg "[tools]..." sigil="+"
+cmd "run" { arg "<task>" }
+"#
+        .parse()
+        .unwrap();
+
+        let parsed = parse(&spec, &input(&["test", "+node", "node"])).unwrap();
+        assert_eq!(parsed.cmd.name, "run");
+        let value = |name| {
+            parsed
+                .args
+                .iter()
+                .find(|(arg, _)| arg.name == name)
+                .map(|(_, value)| value.to_string())
+                .unwrap()
+        };
+        assert_eq!(value("tools"), "node");
+        assert_eq!(value("task"), "node");
+    }
+
     #[test]
     fn test_default_subcommand_explicit_still_works() {
         // Test that explicit subcommand takes precedence

From 8787d6c582d9b4e16749de05738860336f5e45c2 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Tue, 25 Aug 2026 21:12:12 +0000
Subject: [PATCH 11/11] style(spec): format sigil corpus

---
 corpus/14-sigil.json | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/corpus/14-sigil.json b/corpus/14-sigil.json
index c4dfc6100..9c7f0d862 100644
--- a/corpus/14-sigil.json
+++ b/corpus/14-sigil.json
@@ -102,7 +102,11 @@
       "argv": ["+node@27", "first", "last"],
       "expect": {
         "ok": {
-          "args": { "optional": "first", "tools": ["node@27"], "required": "last" }
+          "args": {
+            "optional": "first",
+            "tools": ["node@27"],
+            "required": "last"
+          }
         }
       }
     },