agent-method 1.5.12

package/lib/cli/completion.js

@@ -0,0 +1,735 @@
+/** wwa completion — generate shell completion scripts. */
+
+// ---------------------------------------------------------------------------
+// Command / option tree (single source of truth for completions)
+// ---------------------------------------------------------------------------
+
+const COMMANDS = [
+  "check", "scan", "route", "refine", "status", "upgrade", "init",
+  "plan", "implement", "review", "digest", "close",
+  "casestudy", "docs",
+  "project-discovery", "context-refresh", "phase-complete", "backlog",
+  "plan-create", "dependency-analysis", "debt-assessment",
+  "docs-update", "cross-reference",
+  "add", "record",
+  "pipeline", "serve", "watch", "completion",
+];
+
+const PIPELINE_SUBCOMMANDS = ["classify", "select", "resolve", "cascade", "test"];
+
+const PROJECT_TYPES = ["code", "context", "data", "mix", "general"];
+const TIERS = ["starter", "full"];
+const RUNTIMES = ["claude", "cursor", "all"];
+const PROFILES = ["lite", "standard", "full"];
+const ONBOARDING_MODES = ["greenfield", "brownfield", "auto"];
+const STAGES = ["initialize", "scope", "plan", "execute", "verify", "close"];
+const WORKFLOWS = ["WF-01", "WF-02", "WF-03", "WF-04", "WF-05", "WF-06", "WF-07", "WF-08"];
+const SHELLS = ["bash", "zsh", "fish", "powershell"];
+
+const CMD_OPTIONS = {
+  check:     ["--project-type", "-p", "--registry", "--json"],
+  scan:      ["--registry", "--json", "--no-overview"],
+  route:     ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  refine:    ["--output", "-o", "--json"],
+  status:    ["--json"],
+  upgrade:   ["--dry-run"],
+  init:      ["--tier", "--runtime", "--profile", "--onboarding", "--registry", "--json", "--describe"],
+  plan:      ["--json"],
+  implement: ["--json"],
+  review:    ["--json"],
+  digest:    ["--status", "--json"],
+  close:     ["--json"],
+  casestudy: ["--output", "-o", "--name", "--json"],
+  docs:      ["--json"],
+  serve:     ["--registry"],
+  watch:     ["--registry"],
+  completion:["--install"],
+  "project-discovery": ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "context-refresh":   ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "phase-complete":    ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "backlog":           ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "plan-create":       ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "dependency-analysis": ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "debt-assessment":   ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "docs-update":      ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  "cross-reference": ["--project-type", "-p", "--stage", "-s", "--first-session", "--registry", "--json"],
+  add:       ["--directory", "-d", "--file", "--dry-run", "--json"],
+  record:    ["--directory", "-d", "--dry-run", "--json"],
+};
+
+const ADD_TYPES = ["backlog", "decision", "finding", "session", "summary"];
+
+const PIPELINE_OPTIONS = {
+  classify: ["--project-type", "-p", "--registry", "--json"],
+  select:   ["--first-session", "--registry", "--json"],
+  resolve:  ["--registry", "--json"],
+  cascade:  ["--context", "--registry", "--json"],
+  test:     ["--registry"],
+};
+
+// ---------------------------------------------------------------------------
+// Bash completion script
+// ---------------------------------------------------------------------------
+
+function bashScript() {
+  return `# wwa bash completion — auto-generated by wwa completion bash
+# Add to ~/.bashrc:  eval "$(wwa completion bash)"
+
+_wwa_completions() {
+  local cur prev cmd subcmd
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Determine the command (first non-option arg after wwa)
+  cmd=""
+  subcmd=""
+  for ((i=1; i<COMP_CWORD; i++)); do
+    case "\${COMP_WORDS[i]}" in
+      -*) ;;
+      *)
+        if [[ -z "$cmd" ]]; then
+          cmd="\${COMP_WORDS[i]}"
+        elif [[ "$cmd" == "pipeline" && -z "$subcmd" ]]; then
+          subcmd="\${COMP_WORDS[i]}"
+        fi
+        ;;
+    esac
+  done
+
+  # Complete command names
+  if [[ -z "$cmd" ]]; then
+    COMPREPLY=( $(compgen -W "${COMMANDS.join(" ")}" -- "$cur") )
+    return
+  fi
+
+  # Complete pipeline subcommands
+  if [[ "$cmd" == "pipeline" && -z "$subcmd" ]]; then
+    COMPREPLY=( $(compgen -W "${PIPELINE_SUBCOMMANDS.join(" ")}" -- "$cur") )
+    return
+  fi
+
+  # Complete add type (first positional)
+  if [[ "$cmd" == "add" && "$prev" == "add" ]]; then
+    COMPREPLY=( $(compgen -W "${ADD_TYPES.join(" ")}" -- "$cur") )
+    return
+  fi
+
+  # Complete option values
+  case "$prev" in
+    -p|--project-type)
+      COMPREPLY=( $(compgen -W "${PROJECT_TYPES.join(" ")}" -- "$cur") )
+      return ;;
+    --tier)
+      COMPREPLY=( $(compgen -W "${TIERS.join(" ")}" -- "$cur") )
+      return ;;
+    --runtime)
+      COMPREPLY=( $(compgen -W "${RUNTIMES.join(" ")}" -- "$cur") )
+      return ;;
+    --profile|--context)
+      COMPREPLY=( $(compgen -W "${PROFILES.join(" ")}" -- "$cur") )
+      return ;;
+    --onboarding)
+      COMPREPLY=( $(compgen -W "${ONBOARDING_MODES.join(" ")}" -- "$cur") )
+      return ;;
+    -s|--stage)
+      COMPREPLY=( $(compgen -W "${STAGES.join(" ")}" -- "$cur") )
+      return ;;
+  esac
+
+  # Complete options for pipeline subcommands
+  if [[ "$cmd" == "pipeline" && -n "$subcmd" ]]; then
+    local opts="${Object.entries(PIPELINE_OPTIONS).map(([k, v]) => `${k}) opts="${v.join(" ")}" ;;`).join("\n        ")}"
+    case "$subcmd" in
+      ${Object.entries(PIPELINE_OPTIONS).map(([k, v]) => `${k}) COMPREPLY=( $(compgen -W "${v.join(" ")}" -- "$cur") ) ;;`).join("\n      ")}
+    esac
+    return
+  fi
+
+  # Complete init positional arg (project type)
+  if [[ "$cmd" == "init" && "$cur" != -* ]]; then
+    COMPREPLY=( $(compgen -W "${PROJECT_TYPES.join(" ")}" -- "$cur") )
+    return
+  fi
+
+  # Complete docs directory (first positional) — Phase 7r
+  if [[ "$cmd" == "docs" && "$cur" != -* ]]; then
+    COMPREPLY=( $(compgen -d -- "$cur") )
+    return
+  fi
+
+  # Complete completion positional arg (shell name)
+  if [[ "$cmd" == "completion" && "$cur" != -* ]]; then
+    COMPREPLY=( $(compgen -W "${SHELLS.join(" ")}" -- "$cur") )
+    return
+  fi
+
+  # Complete options for the current command
+  case "$cmd" in
+    ${Object.entries(CMD_OPTIONS).map(([k, v]) => `${k}) COMPREPLY=( $(compgen -W "${v.join(" ")}" -- "$cur") ) ;;`).join("\n    ")}
+  esac
+}
+
+complete -o default -F _wwa_completions wwa
+complete -o default -F _wwa_completions agent-method
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Zsh completion script
+// ---------------------------------------------------------------------------
+
+function zshScript() {
+  return `#compdef wwa agent-method
+# wwa zsh completion — auto-generated by wwa completion zsh
+# Add to ~/.zshrc:  eval "$(wwa completion zsh)"
+
+_wwa() {
+  local -a commands pipeline_commands project_types tiers runtimes profiles stages shells
+
+  commands=(
+    'check:Validate your entry point and project setup'
+    'scan:Detect project type from directory contents'
+    'route:Show how a query routes through the pipeline'
+    'refine:Extract a refinement report from session history'
+    'status:Check if your methodology version is current'
+    'upgrade:Update your project to the latest methodology version'
+    'init:Set up a new project with methodology templates'
+    'plan:Display current plan status from PLAN.md'
+    'implement:Show implementation guidance for the current plan step'
+    'review:Display project review dashboard'
+    'digest:Show management digest'
+    'close:Session close checklist and cascade reminders'
+    'pipeline:Advanced pipeline commands for debugging'
+    'serve:Start MCP server on stdio transport'
+    'watch:Watch files and validate on save'
+    'completion:Generate shell completion scripts'
+  )
+
+  pipeline_commands=(
+    'classify:Classify a natural language query'
+    'select:Select workflow for a query type'
+    'resolve:Resolve features for a workflow stage'
+    'cascade:Compute cascade chain from a trigger'
+    'test:Run YAML test fixtures'
+  )
+
+  project_types=(${PROJECT_TYPES.map(t => `'${t}'`).join(" ")})
+  tiers=(${TIERS.map(t => `'${t}'`).join(" ")})
+  runtimes=(${RUNTIMES.map(t => `'${t}'`).join(" ")})
+  profiles=(${PROFILES.map(t => `'${t}'`).join(" ")})
+  stages=(${STAGES.map(t => `'${t}'`).join(" ")})
+  shells=(${SHELLS.map(t => `'${t}'`).join(" ")})
+
+  _arguments -C \\
+    '1:command:->command' \\
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'wwa command' commands
+      ;;
+    args)
+      case $words[1] in
+        check)
+          _arguments \\
+            '(-p --project-type)'{-p,--project-type}'[Project type]:type:($project_types)' \\
+            '--registry[Path to feature-registry.yaml]:file:_files' \\
+            '--json[Output as JSON]' \\
+            '1:entry-point:_files'
+          ;;
+        scan)
+          _arguments \\
+            '--registry[Path to feature-registry.yaml]:file:_files' \\
+            '--json[Output as JSON]' \\
+            '1:directory:_directories'
+          ;;
+        route)
+          _arguments \\
+            '(-p --project-type)'{-p,--project-type}'[Project type]:type:($project_types)' \\
+            '(-s --stage)'{-s,--stage}'[Workflow stage]:stage:($stages)' \\
+            '--first-session[Force WF-04 bootstrap]' \\
+            '--registry[Path to feature-registry.yaml]:file:_files' \\
+            '--json[Output as JSON]' \\
+            '1:query:'
+          ;;
+        refine)
+          _arguments \\
+            '(-o --output)'{-o,--output}'[Output file]:file:_files' \\
+            '--json[Output as JSON]' \\
+            '1:session-log:_files'
+          ;;
+        status)
+          _arguments '--json[Output as JSON]' '1:directory:_directories'
+          ;;
+        upgrade)
+          _arguments '--dry-run[Show changes without modifying]' '1:directory:_directories'
+          ;;
+        init)
+          _arguments \\
+            '--tier[Template tier]:tier:($tiers)' \\
+            '--runtime[Agent runtime]:runtime:($runtimes)' \\
+            '--profile[Integration profile]:profile:($profiles)' \\
+            '--onboarding[Onboarding mode]:mode:(greenfield brownfield auto)' \\
+            '--registry[Path to feature-registry.yaml]:file:_files' \\
+            '--json[Output as JSON]' \\
+            '--describe[Describe without creating files]' \\
+            '1:project-type:($project_types)' \\
+            '2:directory:_directories'
+          ;;
+        plan|implement|review|close)
+          _arguments '--json[Output as JSON]' '1:directory:_directories'
+          ;;
+        digest)
+          _arguments '--status[Show STATUS.md instead]' '--json[Output as JSON]' '1:directory:_directories'
+          ;;
+        casestudy)
+          _arguments \\
+            '(-o --output)'{-o,--output}'[Output file]:file:_files' \\
+            '--name[Project name override]:name:' \\
+            '--json[Output as JSON]' \\
+            '1:directory:_directories'
+          ;;
+        docs)
+          _arguments '--json[Output as JSON]' '1:directory:_directories'
+          ;;
+        project-discovery|context-refresh|phase-complete|backlog|plan-create|dependency-analysis|debt-assessment|docs-update|cross-reference)
+          _arguments \\
+            '(-p --project-type)'{-p,--project-type}'[Project type]:type:($project_types)' \\
+            '(-s --stage)'{-s,--stage}'[Workflow stage]:stage:($stages)' \\
+            '--first-session[Force WF-04 bootstrap]' \\
+            '--registry[Path to feature-registry.yaml]:file:_files' \\
+            '--json[Output as JSON]'
+          ;;
+        add)
+          _arguments \\
+            '(-d --directory)'{-d,--directory}'[Project directory]:dir:_directories' \\
+            '--file[Read content from file]:file:_files' \\
+            '--dry-run[Show what would be written]' \\
+            '--json[Output as JSON]' \\
+            '1:type:(backlog decision finding session summary)' \\
+            '*:content:'
+          ;;
+        pipeline)
+          _arguments '1:subcommand:->pipeline_sub' '*::arg:->pipeline_args'
+          case $state in
+            pipeline_sub)
+              _describe 'pipeline subcommand' pipeline_commands
+              ;;
+            pipeline_args)
+              case $words[1] in
+                classify)
+                  _arguments \\
+                    '(-p --project-type)'{-p,--project-type}'[Project type]:type:($project_types)' \\
+                    '--registry[Path to registry]:file:_files' \\
+                    '--json[Output as JSON]' \\
+                    '1:query:'
+                  ;;
+                select)
+                  _arguments \\
+                    '--first-session[Force WF-04]' \\
+                    '--registry[Path to registry]:file:_files' \\
+                    '--json[Output as JSON]' \\
+                    '1:query-type:' \\
+                    '2:project-type:($project_types)'
+                  ;;
+                resolve)
+                  _arguments \\
+                    '--registry[Path to registry]:file:_files' \\
+                    '--json[Output as JSON]' \\
+                    '1:workflow-id:(WF-01 WF-02 WF-03 WF-04 WF-05 WF-06 WF-07 WF-08)' \\
+                    '2:stage:($stages)'
+                  ;;
+                cascade)
+                  _arguments \\
+                    '--context[Cascade context]:context:($project_types universal)' \\
+                    '--registry[Path to registry]:file:_files' \\
+                    '--json[Output as JSON]' \\
+                    '1:trigger:'
+                  ;;
+                test)
+                  _arguments '--registry[Path to registry]:file:_files' '*:fixtures:_files'
+                  ;;
+              esac
+              ;;
+          esac
+          ;;
+        serve)
+          _arguments '--registry[Path to feature-registry.yaml]:file:_files'
+          ;;
+        watch)
+          _arguments '--registry[Path to feature-registry.yaml]:file:_files' '1:directory:_directories'
+          ;;
+        completion)
+          _arguments '--install[Install to shell profile]' '1:shell:($shells)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+compdef _wwa wwa
+compdef _wwa agent-method
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Fish completion script
+// ---------------------------------------------------------------------------
+
+function fishScript() {
+  const lines = [
+    "# wwa fish completion — auto-generated by wwa completion fish",
+    "# Add to ~/.config/fish/completions/wwa.fish",
+    "",
+    "# Disable file completions by default",
+    "complete -c wwa -f",
+    "complete -c agent-method -f",
+    "",
+    "# Commands",
+  ];
+
+  const cmdDescs = {
+    check: "Validate your entry point",
+    scan: "Detect project type",
+    route: "Show query routing",
+    refine: "Extract refinement report",
+    status: "Check methodology version",
+    upgrade: "Update methodology files",
+    init: "Set up a new project",
+    plan: "Display current plan status",
+    implement: "Show implementation guidance",
+    review: "Display project review dashboard",
+    digest: "Show management digest",
+    close: "Session close checklist",
+    casestudy: "Extract structured case study",
+    docs: "Show docs coverage report",
+    "project-discovery": "Run project discovery workflow",
+    "context-refresh": "Run context refresh workflow",
+    "phase-complete": "Run phase completion workflow",
+    backlog: "Show routing for backlog",
+    "plan-create": "Run planning workflow",
+    "dependency-analysis": "Run dependency analysis workflow",
+    "debt-assessment": "Run debt assessment workflow",
+    "docs-update": "Run docs update workflow",
+    "cross-reference": "Run cross-reference workflow",
+    add: "Append to backlog, decision, finding, session, summary",
+    record: "Record last CLI run summary to SESSION-LOG.md",
+    pipeline: "Advanced pipeline commands",
+    serve: "Start MCP server",
+    watch: "Watch files for changes",
+    completion: "Generate shell completions",
+  };
+
+  for (const [cmd, desc] of Object.entries(cmdDescs)) {
+    lines.push(`complete -c wwa -n "__fish_use_subcommand" -a "${cmd}" -d "${desc}"`);
+    lines.push(`complete -c agent-method -n "__fish_use_subcommand" -a "${cmd}" -d "${desc}"`);
+  }
+
+  lines.push("", "# Pipeline subcommands");
+  const pipeDescs = {
+    classify: "Classify a query", select: "Select workflow",
+    resolve: "Resolve features", cascade: "Compute cascade",
+    test: "Run test fixtures",
+  };
+  for (const [sub, desc] of Object.entries(pipeDescs)) {
+    lines.push(`complete -c wwa -n "__fish_seen_subcommand_from pipeline" -a "${sub}" -d "${desc}"`);
+    lines.push(`complete -c agent-method -n "__fish_seen_subcommand_from pipeline" -a "${sub}" -d "${desc}"`);
+  }
+
+  lines.push("", "# Global options");
+  lines.push(`complete -c wwa -l json -d "Output as JSON"`);
+  lines.push(`complete -c wwa -l registry -d "Path to feature-registry.yaml" -rF`);
+  lines.push(`complete -c agent-method -l json -d "Output as JSON"`);
+  lines.push(`complete -c agent-method -l registry -d "Path to feature-registry.yaml" -rF`);
+
+  lines.push("", "# Project type completions for -p/--project-type and init");
+  for (const bin of ["wwa", "agent-method"]) {
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from check route init" -s p -l project-type -xa "${PROJECT_TYPES.join(" ")}" -d "Project type"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from init" -xa "${PROJECT_TYPES.join(" ")}"`);
+  }
+
+  lines.push("", "# Command-specific options");
+  for (const bin of ["wwa", "agent-method"]) {
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from route" -s s -l stage -xa "${STAGES.join(" ")}" -d "Workflow stage"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from route" -l first-session -d "Force WF-04 bootstrap"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from refine" -s o -l output -d "Output file" -rF`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from upgrade" -l dry-run -d "Show changes without modifying"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from init" -l tier -xa "${TIERS.join(" ")}" -d "Template tier"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from init" -l runtime -xa "${RUNTIMES.join(" ")}" -d "Agent runtime"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from init" -l profile -xa "${PROFILES.join(" ")}" -d "Integration profile"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from init" -l onboarding -xa "${ONBOARDING_MODES.join(" ")}" -d "Onboarding mode"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from init" -l describe -d "Describe without creating files"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from casestudy" -s o -l output -d "Output file" -rF`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from casestudy" -l name -d "Project name override"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from digest" -l status -d "Show STATUS.md instead"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from completion" -xa "${SHELLS.join(" ")}"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from completion" -l install -d "Install to shell profile"`);
+    const routableCmds = "project-discovery context-refresh phase-complete backlog plan-create dependency-analysis debt-assessment docs-update cross-reference";
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from ${routableCmds}" -s p -l project-type -xa "${PROJECT_TYPES.join(" ")}" -d "Project type"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from ${routableCmds}" -s s -l stage -xa "${STAGES.join(" ")}" -d "Workflow stage"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from ${routableCmds}" -l first-session -d "Force WF-04 bootstrap"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from add" -s d -l directory -d "Project directory" -a "(pwd)"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from add" -l file -d "Read content from file" -rF`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from add" -l dry-run -d "Show what would be written"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from add" -xa "${ADD_TYPES.join(" ")}" -d "Type (backlog, decision, finding, session, summary)"`);
+    lines.push(`complete -c ${bin} -n "__fish_seen_subcommand_from docs" -xa "(__fish_complete_directories)" -d "Project directory"`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// PowerShell completion script
+// ---------------------------------------------------------------------------
+
+function powershellScript() {
+  return `# wwa PowerShell completion — auto-generated by wwa completion powershell
+# Add to $PROFILE:  wwa completion powershell | Out-String | Invoke-Expression
+
+$wwaCommands = @(${COMMANDS.map(c => `'${c}'`).join(", ")})
+$wwaPipelineSubs = @(${PIPELINE_SUBCOMMANDS.map(c => `'${c}'`).join(", ")})
+$wwaAddTypes = @(${ADD_TYPES.map(c => `'${c}'`).join(", ")})
+$wwaProjectTypes = @(${PROJECT_TYPES.map(c => `'${c}'`).join(", ")})
+$wwaTiers = @(${TIERS.map(c => `'${c}'`).join(", ")})
+$wwaRuntimes = @(${RUNTIMES.map(c => `'${c}'`).join(", ")})
+$wwaProfiles = @(${PROFILES.map(c => `'${c}'`).join(", ")})
+$wwaOnboarding = @(${ONBOARDING_MODES.map(c => `'${c}'`).join(", ")})
+$wwaStages = @(${STAGES.map(c => `'${c}'`).join(", ")})
+$wwaWorkflows = @(${WORKFLOWS.map(c => `'${c}'`).join(", ")})
+$wwaShells = @(${SHELLS.map(c => `'${c}'`).join(", ")})
+
+Register-ArgumentCompleter -CommandName wwa, agent-method -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+
+  $tokens = $commandAst.ToString().Substring(0, $cursorPosition).Trim() -split '\\s+'
+  $cmd = if ($tokens.Count -gt 1) { $tokens[1] } else { '' }
+  $subcmd = if ($tokens.Count -gt 2 -and $cmd -eq 'pipeline') { $tokens[2] } else { '' }
+  $prev = if ($tokens.Count -gt 1) { $tokens[-2] } else { '' }
+
+  # Option value completions
+  switch ($prev) {
+    { $_ -in '-p', '--project-type' } { $wwaProjectTypes | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }; return }
+    '--tier'    { $wwaTiers | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }; return }
+    '--runtime' { $wwaRuntimes | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }; return }
+    { $_ -in '--profile', '--context' } { $wwaProfiles | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }; return }
+    '--onboarding' { $wwaOnboarding | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }; return }
+    { $_ -in '-s', '--stage' } { $wwaStages | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }; return }
+  }
+
+  # Command completions
+  if (-not $cmd -or ($tokens.Count -eq 2 -and $wordToComplete)) {
+    $wwaCommands | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+    return
+  }
+
+  # Pipeline subcommand completions
+  if ($cmd -eq 'pipeline' -and (-not $subcmd -or ($tokens.Count -eq 3 -and $wordToComplete))) {
+    $wwaPipelineSubs | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+    return
+  }
+
+  # Init project type completions
+  if ($cmd -eq 'init' -and $wordToComplete -notlike '-*') {
+    $wwaProjectTypes | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+    return
+  }
+
+  # Completion shell name completions
+  if ($cmd -eq 'completion' -and $wordToComplete -notlike '-*') {
+    $wwaShells | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+    return
+  }
+
+  # Pipeline resolve workflow completions
+  if ($cmd -eq 'pipeline' -and $subcmd -eq 'resolve' -and $tokens.Count -eq 4 -and $wordToComplete) {
+    $wwaWorkflows | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+    return
+  }
+
+  # Add type completions (first positional after add)
+  if ($cmd -eq 'add' -and $tokens.Count -eq 3 -and $wordToComplete) {
+    $wwaAddTypes | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+    return
+  }
+
+  # docs directory completions (first positional) — Phase 7r
+  if ($cmd -eq 'docs' -and $wordToComplete -notlike '-*') {
+    try {
+      Get-ChildItem -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -like "$wordToComplete*" } | ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new($_.Name, $_.Name, 'ParameterValue', $_.Name)
+      }
+    } catch {}
+    return
+  }
+
+  # Option completions per command
+  $opts = @()
+  switch ($cmd) {
+    'check'      { $opts = @('--project-type', '-p', '--registry', '--json') }
+    'scan'       { $opts = @('--registry', '--json', '--no-overview') }
+    'route'      { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'refine'     { $opts = @('--output', '-o', '--json') }
+    'status'     { $opts = @('--json') }
+    'upgrade'    { $opts = @('--dry-run') }
+    'init'       { $opts = @('--tier', '--runtime', '--profile', '--onboarding', '--registry', '--json', '--describe') }
+    'plan'       { $opts = @('--json') }
+    'implement'  { $opts = @('--json') }
+    'review'     { $opts = @('--json') }
+    'digest'     { $opts = @('--status', '--json') }
+    'close'      { $opts = @('--json') }
+    'casestudy'  { $opts = @('--output', '-o', '--name', '--json') }
+    'docs'       { $opts = @('--json') }
+    'project-discovery' { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'context-refresh'   { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'phase-complete'    { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'backlog'           { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'plan-create'       { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'dependency-analysis' { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'debt-assessment'   { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'docs-update'       { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'cross-reference'   { $opts = @('--project-type', '-p', '--stage', '-s', '--first-session', '--registry', '--json') }
+    'add'               { $opts = @('--directory', '-d', '--file', '--dry-run', '--json') }
+    'record'            { $opts = @('--directory', '-d', '--dry-run', '--json') }
+    'serve'      { $opts = @('--registry') }
+    'watch'      { $opts = @('--registry') }
+    'completion' { $opts = @('--install') }
+    'pipeline' {
+      switch ($subcmd) {
+        'classify' { $opts = @('--project-type', '-p', '--registry', '--json') }
+        'select'   { $opts = @('--first-session', '--registry', '--json') }
+        'resolve'  { $opts = @('--registry', '--json') }
+        'cascade'  { $opts = @('--context', '--registry', '--json') }
+        'test'     { $opts = @('--registry') }
+      }
+    }
+  }
+
+  $opts | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterName', $_)
+  }
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Shell profile paths and install logic
+// ---------------------------------------------------------------------------
+
+import { existsSync, readFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+function detectShell() {
+  const shell = process.env.SHELL || "";
+  if (shell.includes("zsh")) return "zsh";
+  if (shell.includes("fish")) return "fish";
+  if (shell.includes("bash")) return "bash";
+  // Windows: check for PowerShell
+  if (process.env.PSModulePath || process.platform === "win32") return "powershell";
+  return "bash";
+}
+
+function getScript(shell) {
+  switch (shell) {
+    case "bash": return bashScript();
+    case "zsh": return zshScript();
+    case "fish": return fishScript();
+    case "powershell": return powershellScript();
+    default:
+      console.error(`Unknown shell: ${shell}\nSupported: ${SHELLS.join(", ")}`);
+      process.exit(1);
+  }
+}
+
+function getProfilePath(shell) {
+  const home = homedir();
+  switch (shell) {
+    case "bash": return join(home, ".bashrc");
+    case "zsh": return join(home, ".zshrc");
+    case "fish": return join(home, ".config", "fish", "completions", "wwa.fish");
+    case "powershell": return process.env.PROFILE || join(home, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1");
+    default: return null;
+  }
+}
+
+function installSnippet(shell) {
+  switch (shell) {
+    case "bash": return '\n# wwa shell completion\neval "$(wwa completion bash)"\n';
+    case "zsh": return '\n# wwa shell completion\neval "$(wwa completion zsh)"\n';
+    case "fish": return null; // fish uses a file, not a snippet
+    case "powershell": return '\n# wwa shell completion\nwwa completion powershell | Out-String | Invoke-Expression\n';
+    default: return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Register command
+// ---------------------------------------------------------------------------
+
+export function register(program) {
+  program
+    .command("completion [shell]")
+    .description("Generate shell completion scripts (bash, zsh, fish, powershell)")
+    .option("--install", "Install completions to your shell profile")
+    .action(async (shell, opts) => {
+      shell = shell || detectShell();
+
+      if (!SHELLS.includes(shell)) {
+        console.error(`Unknown shell: ${shell}\nSupported: ${SHELLS.join(", ")}`);
+        process.exit(1);
+      }
+
+      if (opts.install) {
+        const profilePath = getProfilePath(shell);
+
+        if (shell === "fish") {
+          // Fish uses a completions file directly
+          const { mkdirSync } = await import("node:fs");
+          const dir = join(homedir(), ".config", "fish", "completions");
+          mkdirSync(dir, { recursive: true });
+          const { writeFileSync } = await import("node:fs");
+          writeFileSync(profilePath, getScript(shell), "utf-8");
+          console.log(`Completions written to ${profilePath}`);
+          console.log("Restart your shell or run: source ~/.config/fish/config.fish");
+          return;
+        }
+
+        const snippet = installSnippet(shell);
+        if (!snippet) {
+          console.error(`Cannot auto-install for ${shell}. Output the script manually:\n  wwa completion ${shell}`);
+          process.exit(1);
+        }
+
+        // Check if already installed
+        if (existsSync(profilePath)) {
+          const content = readFileSync(profilePath, "utf-8");
+          if (content.includes("wwa completion")) {
+            console.log(`Completions already installed in ${profilePath}`);
+            return;
+          }
+        }
+
+        appendFileSync(profilePath, snippet, "utf-8");
+        console.log(`Completions added to ${profilePath}`);
+        console.log(`Restart your shell or run: source ${profilePath}`);
+        return;
+      }
+
+      // Print the script to stdout for eval
+      process.stdout.write(getScript(shell));
+    });
+}