feat(007)!: decommission the FueliX AI analyzer — the Cisco API check is the only mode (4.0.0)

[Ali Bahaloo (alibahaloo)]

Spec 006 shipped a check that gets its verdicts from Cisco directly. That made the older AI-driven mode the weaker of the two on every axis that matters for a security decision, while its cost was paid continuously — a second credential every user had to obtain, inventory context leaving the organisation, two report formats, two undecided labels, and a mode-comparison table a reader had to work through before running anything.

This removes it. caia with no options now does what caia --api used to do.

	Before	After
Default caia	prompt for an ERP link, AI reads it, Excel report	check the whole inventory against Cisco, HTML report
Credentials	FueliX key and Cisco client ID + secret	Cisco client ID + secret
Outputs	analysis_output_*.xlsx and impact_report_*.html	impact_report_*.html
Undecided label	Indeterminate and Needs review	Needs review
Endpoints contacted	api.fuelix.ai, sec.cloudapps.cisco.com, apix.cisco.com, id.cisco.com	apix.cisco.com, id.cisco.com
Product name	Cisco Advisory Impact Agent	Cisco Advisory Impact Analyzer

The command, the caia-cli distribution, and the repository name are unchanged. Only the descriptive product name moves, because "Agent" and "Agentic firewall impact analysis" now misdescribe the tool — and for a security tool, overstating how the answer is reached is a trust problem rather than a marketing one.

Breaking change

Five options are withdrawn: --api, --url, --dry-run, --keep-temp, --no-keep-temp. VERSION goes to 4.0.0 — documented options and a documented mode are removed, which is MAJOR under the repo's own semver rule.

Passing a removed option refuses by name and says what to run instead, rather than falling through to argparse's unrecognized arguments:

✗  --api has been removed.
Checking your whole inventory against Cisco's published advisory data is now what caia does by default. Just run: caia

The guard runs before the parser is built, which is the one piece of genuinely new behaviour here. Argparse gives --help precedence over a merely-absent option, so with --api simply deleted from the parser, caia --api --help prints help and exits 0 — verified empirically. Worse, caia --uninstall --dry-run would really uninstall, when a script author who wrote --dry-run there plausibly meant "rehearse this". A withdrawn option therefore outranks everything, including --help and --uninstall.

Matching is exact (including the --url=VALUE form), so --dry — a valid abbreviation before — still gets argparse's ordinary error. That keeps the removal notice meaningful: it appears only for options that genuinely existed.

Saved credentials survive. Leftover FUELIX_* values in an existing config file or in the environment are inert — no error, no warning, no effect — and disappear the next time --config saves, because save() writes only the keys the product still manages. No migration step, no pruning pass on an ordinary run.

--dry-run is removed as a capability, not renamed. It was not an AI feature — under the surviving check it previewed what would be asked of Cisco without contacting it — so this is a deliberate loss, accepted in review. Consequence: there is no longer any way to exercise the tool end to end without Cisco credentials, which narrows what the clean-room test and offline checks can prove.

Changes

• Deleted — caia/fuelix.py, caia/cisco.py, caia/report.py, tests/test_extraction.py
• caia/analyzer.py — the advisory-run path, URL validation/prompting, CSAF download, and the dry run go; run_api() becomes run(). The shared helpers both flows used (die, resolve_inventory, ensure_dirs, default_output_dir, _result_line, …) are untouched — altering one in passing was the single most likely way to break equivalence
• caia/cli.py — five options removed; REMOVED_OPTIONS + refuse_removed_options() added and invoked from main() before the banner and the parser; dispatch collapses to one call; the update offer now keys on the TTY check alone, since args.url was its proxy for "scripted run" and the TTY check already covers that
• caia/config.py — managed keys 5 → 2, DEFAULTS emptied, fuelix import dropped, run_config() prompts only for Cisco. Its verification behaviour — visible ID prompt, non-echoing secret with capture confirmation, skippable prompts, accepted/rejected/unreachable — is preserved exactly
• caia/inventory.py — build_combos()/expand_combo_ids() removed (AI-only compaction)
• caia/matching.py — the now-dead validate_alias parameter removed. Mechanical only; this module is verdict logic under Principle IV and nothing else in it changed
• caia/ui.py, caia/__init__.py, caia/psirt.py, pyproject.toml — product name, canonical tagline, canonical description
• README.md — restructured, not patched. The mode-comparison table, advisory-mode section, FueliX key section, and AI troubleshooting entries are removed as units and the remainder re-sequenced as one path. Deleting the 25 references sentence-by-sentence would have left a document shaped around a choice the reader no longer has
• docs/index.html — title, meta, hero, three feature cards, prerequisites, run steps; the FueliX key section removed. Both documents carry a 4.0.0 removal notice, per the Documentation gate
• tools/install-test.sh — advisory-mode and dry-run steps replaced with the removed-option guard, the precedence case, and the credential gate
• .env.example, .gitignore — Cisco variables only; ignore rules for artifacts the tool can no longer produce (analysis_output_*.xlsx, csaf_*/) removed
• .specify/memory/constitution.md — 2.2.1 → 3.0.0 (MAJOR), landed first as a prerequisite

Runtime dependencies re-justified rather than assumed: openpyxl stays (it still reads the inventory; only the Excel writer is deleted), python-dotenv stays (.env support is retained for automation, with only its AI variables withdrawn).

specs/ and brds/ are left as written — frozen spec-kit records; rewriting them would falsify the record.

Verification

Behavioural equivalence is the requirement most at risk here, because the deletion runs straight through code both flows shared. A unit test asserting "a report was written" would not catch a reworded reason or a reordered row, so a golden report was captured from the current --api path before anything was deleted and diffed afterwards:

• Byte-identical except the run timestamp — same 13 devices, same 6 Impacted / 1 Not impacted / 6 Needs review, same 8 questions to Cisco, same printed output, same exit code. Re-verified after every subsequent change, not just after the first
• Live run against the real 70-row inventory: 27 distinct checks, 55 Impacted / 0 Not impacted / 15 Needs review — matching the BRD-003 feasibility spike, including its 15 unanswerable rows
• 246 unit tests pass (244 before; 10 removed with the capability, 12 added for the guard and obsolete-key inertness)
• Clean-room install on python:3.9-slim — the minimum supported Python, fresh container, no prior copy: caia-cli==4.0.0 built from the tree, only openpyxl + python-dotenv resolved, all five removed options refuse, the credential gate refuses, and --uninstall --dry-run refused while leaving the tool installed — the footgun that motivated the precedence rule, proven outside a mock

Constitution compliance (v3.0.0)

• I. Standard-library-first — net removal of code and of one external service; no dependency added, both survivors re-justified against surviving behaviour
• II. Cross-platform parity — no OS-conditional code touched; config path resolution unchanged in substance
• III. CLI-first — every surviving capability stays reachable, exit codes keep their meanings (a removed option reuses 2, the existing argument-error status; 130 on interrupt unchanged). The principle's clause that a withdrawn option must be refused by name is what the guard implements
• IV. Conservative & traceable analysis — verdict logic untouched beyond the dead-parameter removal; Needs review is now the sole undecided label; positive confirmation before Not impacted intact. Equivalence is proven, not asserted
• V. Secrets hygiene & data locality — strictly improved: one credential instead of two, one fewer external destination, and the endpoint that received the largest disclosure is gone. The bound "only family, platform, release may leave the machine" is now the tool's actual maximum
• Documentation gate — README and landing page corrected in this same change and checked against each other
• Tests gate — the surviving logic keeps its tests; the guard has its own; the whole suite runs with no credentials and no network

One documented exception: tests/test_config.py deliberately writes FUELIX_API_KEY / FUELIX_MODEL / FUELIX_BASE_URL into a fixture, to prove those values are inert and vanish on save. That behaviour cannot be tested without naming the real keys users have on disk. The only other mentions anywhere are the two 4.0.0 removal notices the Documentation requirement asks for.

After merge

1. Tag 4.0.0 (python tools/release.py) — the Release workflow refuses to publish when the tag does not match VERSION
2. Update the GitHub repository description, which still carries the old product name (outside the codebase, so out of this change's scope)
3. Tell existing users of the advisory-URL mode directly — the product's only obligation to them is the refusal message and accurate docs, both of which are in place

🤖 Generated with Claude Code