agentnative 0.5.0

The agent-native CLI linter — audit whether your CLI follows agent-readiness principles

using namespace System.Management.Automation
using namespace System.Management.Automation.Language

Register-ArgumentCompleter -Native -CommandName 'anc' -ScriptBlock {
    param($wordToComplete, $commandAst, $cursorPosition)

    $commandElements = $commandAst.CommandElements
    $command = @(
        'anc'
        for ($i = 1; $i -lt $commandElements.Count; $i++) {
            $element = $commandElements[$i]
            if ($element -isnot [StringConstantExpressionAst] -or
                $element.StringConstantType -ne [StringConstantType]::BareWord -or
                $element.Value.StartsWith('-') -or
                $element.Value -eq $wordToComplete) {
                break
        }
        $element.Value
    }) -join ';'

    $completions = @(switch ($command) {
        'anc' {
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            [CompletionResult]::new('-V', '-V ', [CompletionResultType]::ParameterName, 'Print version')
            [CompletionResult]::new('--version', '--version', [CompletionResultType]::ParameterName, 'Print version')
            [CompletionResult]::new('audit', 'audit', [CompletionResultType]::ParameterValue, 'Audit a CLI project or binary for agent-readiness')
            [CompletionResult]::new('completions', 'completions', [CompletionResultType]::ParameterValue, 'Generate shell completions')
            [CompletionResult]::new('emit', 'emit', [CompletionResultType]::ParameterValue, 'Render build artifacts (coverage matrix, scorecard schema)')
            [CompletionResult]::new('skill', 'skill', [CompletionResultType]::ParameterValue, 'Install or manage the agentnative skill bundle')
            [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
            break
        }
        'anc;audit' {
            [CompletionResult]::new('--command', '--command', [CompletionResultType]::ParameterName, 'Resolve a command from PATH and run behavioral audits against it')
            [CompletionResult]::new('--principle', '--principle', [CompletionResultType]::ParameterName, 'Filter audits by principle number (1-8)')
            [CompletionResult]::new('--output', '--output', [CompletionResultType]::ParameterName, 'Output format')
            [CompletionResult]::new('--audit-profile', '--audit-profile', [CompletionResultType]::ParameterName, 'Exemption category for the target. Suppresses audits that do not apply to this class of tool — e.g., TUI apps legitimately intercept the TTY, so `--audit-profile human-tui` skips the interactive-prompt MUSTs. Suppressed audits emit `Skip` with structured evidence so readers see what was excluded')
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('--binary', '--binary', [CompletionResultType]::ParameterName, 'Run only behavioral audits (skip source analysis)')
            [CompletionResult]::new('--source', '--source', [CompletionResultType]::ParameterName, 'Run only source audits (skip behavioral)')
            [CompletionResult]::new('--include-tests', '--include-tests', [CompletionResultType]::ParameterName, 'Include test code in source analysis')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            break
        }
        'anc;completions' {
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help')
            break
        }
        'anc;emit' {
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help')
            [CompletionResult]::new('coverage-matrix', 'coverage-matrix', [CompletionResultType]::ParameterValue, 'Render the spec coverage matrix (registry → audits → artifact)')
            [CompletionResult]::new('schema', 'schema', [CompletionResultType]::ParameterValue, 'Print the scorecard JSON Schema (draft 2020-12) to stdout')
            [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
            break
        }
        'anc;emit;coverage-matrix' {
            [CompletionResult]::new('--out', '--out', [CompletionResultType]::ParameterName, 'Path for the Markdown artifact. Defaults to `docs/coverage-matrix.md`')
            [CompletionResult]::new('--json-out', '--json-out', [CompletionResultType]::ParameterName, 'Path for the JSON artifact. Defaults to `coverage/matrix.json`')
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('--check', '--check', [CompletionResultType]::ParameterName, 'Exit non-zero when committed artifacts differ from rendered output. CI drift guard')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help')
            break
        }
        'anc;emit;schema' {
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            break
        }
        'anc;emit;help' {
            [CompletionResult]::new('coverage-matrix', 'coverage-matrix', [CompletionResultType]::ParameterValue, 'Render the spec coverage matrix (registry → audits → artifact)')
            [CompletionResult]::new('schema', 'schema', [CompletionResultType]::ParameterValue, 'Print the scorecard JSON Schema (draft 2020-12) to stdout')
            [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
            break
        }
        'anc;emit;help;coverage-matrix' {
            break
        }
        'anc;emit;help;schema' {
            break
        }
        'anc;emit;help;help' {
            break
        }
        'anc;skill' {
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            [CompletionResult]::new('install', 'install', [CompletionResultType]::ParameterValue, 'Install the skill bundle into a host''s canonical skills directory')
            [CompletionResult]::new('update', 'update', [CompletionResultType]::ParameterValue, 'Refresh an installed skill bundle to the latest upstream revision')
            [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
            break
        }
        'anc;skill;install' {
            [CompletionResult]::new('--output', '--output', [CompletionResultType]::ParameterName, 'Output format for the result envelope')
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('--all', '--all', [CompletionResultType]::ParameterName, 'Install into every known host in one invocation')
            [CompletionResult]::new('--dry-run', '--dry-run', [CompletionResultType]::ParameterName, 'Print the resolved git command without spawning. Captures cleanly via `eval $(anc skill install --dry-run <host>)`')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help (see more with ''--help'')')
            break
        }
        'anc;skill;update' {
            [CompletionResult]::new('--output', '--output', [CompletionResultType]::ParameterName, 'Output format for the result envelope')
            [CompletionResult]::new('--color', '--color', [CompletionResultType]::ParameterName, 'Color control for text output. `auto` (default) emits ANSI styling when stdout is a terminal and `NO_COLOR` is unset. `always` forces styling on; `never` strips it. Honors the `NO_COLOR` environment variable in `auto` mode (https://no-color.org/)')
            [CompletionResult]::new('--all', '--all', [CompletionResultType]::ParameterName, 'Refresh every known host in one invocation')
            [CompletionResult]::new('--dry-run', '--dry-run', [CompletionResultType]::ParameterName, 'Print the resolved commands without spawning')
            [CompletionResult]::new('-q', '-q', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('--quiet', '--quiet', [CompletionResultType]::ParameterName, 'Suppress non-essential output. Default: false (warnings and progress notes are written to stderr)')
            [CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--verbose', '--verbose', [CompletionResultType]::ParameterName, 'Escalate diagnostic detail. `-v` is shorthand for `--verbose`. Mutually exclusive with `--quiet`; the last flag on the command line wins when both appear')
            [CompletionResult]::new('--examples', '--examples', [CompletionResultType]::ParameterName, 'Print a curated examples block and exit. Pairs with `--output json` (or `--json`) so structured-output consumers can fetch the examples without parsing the full `--help` body')
            [CompletionResult]::new('--json', '--json', [CompletionResultType]::ParameterName, 'Emit JSON output. Short alias for `--output json` on subcommands that support it. Per the agent-native convention (`p2-should-json-aliases`), the short form works alongside the canonical `--output` enum')
            [CompletionResult]::new('--raw', '--raw', [CompletionResultType]::ParameterName, 'Strip section headers, evidence lines, summary line, and badge hint — emit only `id<TAB>status` per audit. Pipe-safe for grep, awk, and downstream tooling that wants the raw verdict stream without prose. Ignored in `--output json` mode')
            [CompletionResult]::new('-h', '-h', [CompletionResultType]::ParameterName, 'Print help')
            [CompletionResult]::new('--help', '--help', [CompletionResultType]::ParameterName, 'Print help')
            break
        }
        'anc;skill;help' {
            [CompletionResult]::new('install', 'install', [CompletionResultType]::ParameterValue, 'Install the skill bundle into a host''s canonical skills directory')
            [CompletionResult]::new('update', 'update', [CompletionResultType]::ParameterValue, 'Refresh an installed skill bundle to the latest upstream revision')
            [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
            break
        }
        'anc;skill;help;install' {
            break
        }
        'anc;skill;help;update' {
            break
        }
        'anc;skill;help;help' {
            break
        }
        'anc;help' {
            [CompletionResult]::new('audit', 'audit', [CompletionResultType]::ParameterValue, 'Audit a CLI project or binary for agent-readiness')
            [CompletionResult]::new('completions', 'completions', [CompletionResultType]::ParameterValue, 'Generate shell completions')
            [CompletionResult]::new('emit', 'emit', [CompletionResultType]::ParameterValue, 'Render build artifacts (coverage matrix, scorecard schema)')
            [CompletionResult]::new('skill', 'skill', [CompletionResultType]::ParameterValue, 'Install or manage the agentnative skill bundle')
            [CompletionResult]::new('help', 'help', [CompletionResultType]::ParameterValue, 'Print this message or the help of the given subcommand(s)')
            break
        }
        'anc;help;audit' {
            break
        }
        'anc;help;completions' {
            break
        }
        'anc;help;emit' {
            [CompletionResult]::new('coverage-matrix', 'coverage-matrix', [CompletionResultType]::ParameterValue, 'Render the spec coverage matrix (registry → audits → artifact)')
            [CompletionResult]::new('schema', 'schema', [CompletionResultType]::ParameterValue, 'Print the scorecard JSON Schema (draft 2020-12) to stdout')
            break
        }
        'anc;help;emit;coverage-matrix' {
            break
        }
        'anc;help;emit;schema' {
            break
        }
        'anc;help;skill' {
            [CompletionResult]::new('install', 'install', [CompletionResultType]::ParameterValue, 'Install the skill bundle into a host''s canonical skills directory')
            [CompletionResult]::new('update', 'update', [CompletionResultType]::ParameterValue, 'Refresh an installed skill bundle to the latest upstream revision')
            break
        }
        'anc;help;skill;install' {
            break
        }
        'anc;help;skill;update' {
            break
        }
        'anc;help;help' {
            break
        }
    })

    $completions.Where{ $_.CompletionText -like "$wordToComplete*" } |
        Sort-Object -Property ListItemText
}