docs: define strict and general approval matching

Author: Aaronontheweb

IMPLEMENTATION_PLAN.md

@@ -76,7 +76,10 @@ priorities.
       `Invoke-Expression` recursion work: static expansion clears unmappable
       outer spans, while dynamic payloads retain conservative source-aligned
       elements. Nested and dynamic `bash -c` cases pin the equivalent Bash
-      boundary.
+      boundary. Consumer guidance separates strict authored-stream matching
+      from general executable-aware normalization; Netclaw can use the latter
+      for reusable approvals without treating parser verb roles as semantic
+      command boundaries.
 - [x] **Issue #64 — path-shaped operands after native verb chains.**
       Stop the Bash and PowerShell native greedy passes before a token that
       matches the shared path-shape rules. Preserve that token as a resolved

PROJECT_CONTEXT.md

@@ -42,7 +42,9 @@ open-source autonomous operations agent. Netclaw's POSIX approval gate consumes
 ShellSyntaxTree's Bash parser to decompose approval units, identify candidate
 verbs and directories, propagate cwd context, inspect redirects, and fail
 closed when parsing is uncertain. Its PowerShell integration is the remaining
-v0.2.0 downstream acceptance item. See
+v0.2.0 downstream acceptance item. Netclaw is expected to use the consumer
+guide's general executable-aware matching path for supported commands, with
+strict authored-stream matching as the fallback for unrecognized shapes. See
 [`docs/CONSUMER_GUIDE.md`](./docs/CONSUMER_GUIDE.md) for the public consumer
 algorithm and immutable Netclaw examples.
 

SPEC.md

@@ -740,25 +740,31 @@ syntactic rule disambiguates `origin` (a branch name) from `worktree`
 (a subcommand verb) without per-CLI semantic knowledge — and we will
 not bake per-CLI knowledge into the parser.
 
-Consumers needing security-grade verb identification should pattern-prefix
-match against the source-ordered `Clause.Elements` view:
-
-> A command matches an approval pattern `P` if and only if the first
-> `len(P.verb_prefix)` verb elements of the command equal `P.verb_prefix`.
-
-This punts depth choice to the consumer (via the pattern they author)
-and accommodates the parser's over-extraction transparently:
-
-- Pattern `git push *` (verb-prefix length 2) matches `git push origin
-  main` because the first two command tokens are `[git, push]`.
-- Pattern `kubectl get pods *` (verb-prefix length 3) matches
-  `kubectl get pods my-pod` because the first three tokens are
-  `[kubectl, get, pods]`.
-- Auto-proposed patterns for unknown commands should default to
-  the **full** extracted verb chain (greedy match), which is the
-  security-correct default: a subsequent variation re-prompts rather
-  than silently auto-grants. Operators wanting broader grants opt in
-  explicitly.
+Consumers needing security-grade command identification choose one of two
+strategies over the source-ordered `Clause.Elements` view:
+
+1. **Strict authored-stream matching.** Match every modeled significant
+   element in source order. A strict matcher may define explicit operand slots
+   or wildcards, but it SHALL NOT discard an intervening argument merely
+   because the parser assigned it `Role=Argument`. Therefore a strict
+   `git commit` pattern does not match `git -C /repo commit`.
+2. **General executable-aware matching.** Pass the complete authored stream to
+   a grammar owned by the consumer. The grammar consumes known options and
+   operands, identifies the executable's semantic command, and returns both a
+   normalized approval identity and every policy-relevant operand or scope.
+   Equivalent syntax may reuse an approval only after complete interpretation.
+
+For example, a Git-aware matcher may interpret `git -C /repo commit` as the
+general identity `git commit` with effective directory `/repo`. It may then
+reuse a `git commit` approval only when that approval's directory policy covers
+`/repo`. Likewise, executable-aware matchers may intentionally normalize
+`git push origin main` to `git push` or `kubectl get pods my-pod` to
+`kubectl get pods` when their grammars establish which suffixes are operands.
+
+There is no shell-generic rule that selects all `Role=Verb` elements and
+compares them as a contiguous semantic prefix. For unknown executables or an
+unrecognized option shape, consumers should use strict matching or prompt;
+they should not silently fall back to a broader general identity.
 
 False-negative (re-prompt) is recoverable. False-positive (silent
 destructive grant) is not. Narrow-by-default favors the recoverable

docs/CONSUMER_GUIDE.md

@@ -165,9 +165,41 @@ audit UI can still show `gci`.
 `VerbChain` is a best-effort syntactic hint, not a complete executable grammar.
 The greedy native-command walk can include bare lowercase values because a
 generic parser cannot know whether `origin` is a Git remote or a subcommand.
-Unknown commands should therefore default to the full extracted chain, which
-produces narrower approvals and recoverable re-prompts. A consumer may shorten
-the chain only when it owns command-specific knowledge that justifies doing so.
+Unknown commands should therefore retain the complete authored shape through a
+strict pattern, producing narrower approvals and recoverable re-prompts. A
+consumer may normalize or shorten that shape only when it owns command-specific
+knowledge that justifies doing so.
+
+### Choosing strict or general matching
+
+`Clause.Elements` supports two security-conscious consumer strategies. The
+choice belongs to the approval product, not the parser.
+
+**Strict matching** evaluates the significant authored stream in order. A
+pattern may contain explicit operand slots, but unexpected or intervening
+elements prevent a match. For example, a strict `git commit` pattern does not
+match `git -C /repo commit`, because `-C /repo` appears between the executable
+and subcommand. This mode is easy to audit and fail-closed, but syntactic
+variations can produce more prompts.
+
+**General matching** uses an executable-aware interpreter. The interpreter
+consumes the complete element stream according to that executable's option
+grammar and returns a normalized approval identity plus the policy-relevant
+operands and scopes. A Git interpreter can normalize `git -C /repo commit` to
+`git commit` while retaining `/repo` as its effective-directory constraint.
+This preserves reusable approvals without treating the option as irrelevant.
+
+General matching does not mean filtering to `Role=Verb` or trusting
+`PrecedingVerbElementCount` as a semantic boundary. Both fields describe the
+generic parser's projection. If the executable-aware interpreter encounters an
+unknown option, missing operand, dynamic value, or otherwise incomplete shape,
+it should fall back to strict matching or prompt rather than broaden the
+approval.
+
+Netclaw is expected to use general matching for supported high-frequency
+commands so ordinary option placement does not create approval fatigue. Strict
+matching remains the safe fallback for commands whose grammar Netclaw does not
+yet understand.
 
 ## Evaluating arguments and paths
 
@@ -347,7 +379,7 @@ The consumer can collect the attributed cwd and both path operands to propose
 read/write mounts. It should still apply its own cmdlet policy and access-mode
 rules; ShellSyntaxTree reports paths, not filesystem permissions.
 
-### Command-aware policy
+### General command-aware policy
 
 Input:
 

openspec/changes/preserve-clause-element-order/design.md

@@ -58,6 +58,19 @@ count alone, to interpret the command.
 This avoids redundant `VerbIndex` and `AfterVerbIndex` fields whose invariants
 could drift.
 
+### Support strict and general consumer matching without defining either
+
+A strict consumer matches the significant authored stream in order and rejects
+unexpected intervening elements. A general consumer may normalize equivalent
+forms only through an executable-aware grammar that completely consumes the
+stream and returns policy-relevant operands and scope alongside the normalized
+identity. Selecting every `Role=Verb` element is not a general matcher: it can
+silently skip options authored between an executable and subcommand.
+
+This division keeps approval fatigue under consumer control. High-frequency
+executables can receive reusable command-aware approvals, while unknown or
+partially understood shapes retain a narrow strict fallback.
+
 ### Match native option spelling case-sensitively
 
 Native executables receive option spelling unchanged under both Bash and

openspec/changes/preserve-clause-element-order/specs/clause-element-provenance/spec.md

@@ -32,6 +32,12 @@ collection.
 - **THEN** `-C` has `PrecedingVerbElementCount` equal to `1`
 - **THEN** consumers SHALL NOT interpret that count alone as Git's semantic option scope
 
+#### Scenario: Intervening arguments are not a generic verb prefix
+- **WHEN** either parser parses `git -C /repo commit`
+- **THEN** a strict consumer sees `git`, `-C`, `/repo`, and `commit` in that order
+- **THEN** it does not discard the two argument elements and generically match `git commit`
+- **THEN** a consumer may derive `git commit` only through a Git-aware interpretation that retains `/repo` as policy-relevant scope
+
 #### Scenario: Verb-relative counts reset per clause
 - **WHEN** either parser parses `git -C /repo status | git commit -C HEAD~1`
 - **THEN** the first clause reports `-C` after one verb token

openspec/changes/preserve-clause-element-order/tasks.md

@@ -41,6 +41,9 @@
       this implementation change release-shaped.
 - [x] 4.3 Rewrite the Git consumer example to enumerate every occurrence,
       bind operands, and derive Git semantics from all authored elements.
+- [x] 4.4 Document strict authored-stream and general executable-aware
+      matching; forbid generic verb-role filtering and identify general
+      matching as Netclaw's approval-fatigue mitigation.
 
 ## 5. Completion