[v4.0.0] Phase 23: Feature Flags, Rollout Modes & Legacy Fallback #294

Overview

Add feature flag scaffolding (--multi-agent / kdm config set multi_agent true) to enable safe, opt-in testing before full rollout.

Part of Milestone v4.0.0 — Phase 23 of the Multi-Agent SRE Architecture.

⚠️ IMPORTANT CONTRIBUTOR & PR INSTRUCTIONS

TARGET BRANCH: All Pull Requests implementing this phase MUST target branch v4.0.0 (DO NOT target main).
PR TITLE: feat(cli): Phase 23 - Feature Flags, Rollout Modes & Legacy Fallback
PR SCOPE: CLI argument parsing and config storage.

1. Description of What Has to Be Done

Before enabling the multi-agent council by default, we must allow users and contributors to opt-in via a CLI flag or configuration key.

Contributors must:

1. Add --multi-agent boolean flag to src/commands/analyze.ts.
2. Add multi_agent: boolean option to the KDM configuration store (src/config/config.ts).
3. If --multi-agent is true (or config multi_agent == true), execute runAgentCouncilProcess. Otherwise, route to the frozen legacy pipeline.
4. Add deprecation notice advising users that legacy single-prompt mode will be deprecated in v4.1.0.

2. Desired Outcome & Expected Behavior

Expected Behavior

# Default (Legacy)
$ kdm analyze deployment/api
# Executes frozen single-agent analysis

# Opt-in Multi-Agent
$ kdm analyze deployment/api --multi-agent
# Launches Python Multi-Agent Council with Live Ink UI

3. The Implementation Plan & Architectural Blueprint

Files to Create and Modify

• [MODIFY] src/commands/analyze.ts: Add --multi-agent flag.
• [MODIFY] src/config/config.ts: Add multi_agent schema setting.
• [MODIFY] src/analysis/analysis.ts: Route execution based on flag.
• [NEW] src/__tests__/cli-flags.test.ts: Flag routing tests.

4. Detailed Task Breakdown

• Task 23.1: Register CLI Flag (analyze.ts)

  • .option('--multi-agent', 'Enable experimental multi-agent SRE council').

• Task 23.2: Update Config Store (config.ts)

  • Allow kdm config set multi_agent true.

• Task 23.3: Write Routing Tests (cli-flags.test.ts)

  • Assert flag routes to multi-agent bridge.
  • Assert absence of flag routes to legacy pipeline.

5. Verification & Acceptance Checklist

• Run npm test -- src/__tests__/cli-flags.test.ts — all tests pass.
• PR targets branch v4.0.0.