CLI maintenance audit: 21 findings (spec drift, missing tests, weak assertions)

[Alan-Jowett]

Background

A maintenance audit of the CLI was conducted against cli/specs/requirements.md, cli/specs/design.md, cli/specs/validation.md, implementation files, and tests. Full audit report: cli/specs/audit-sonnet.md. Delta analysis (what agents missed and why): cli/specs/audit-delta.md.

Not urgent — nothing is broken in production — but these shouldn't get lost.

---

High Severity

F-001 — TC-CLI-080/081 spawn arg assertions are illusory

• Tests check function exports and source strings, but never intercept spawn to verify cmd/args per CLI
• The switch/case in launch.js:89–105 is behaviorally untested
• Fix: intercept child_process.spawn with a mock, assert correct cmd and args for each CLI variant

F-002 — REQ-CLI-019 spawn failure path completely untested

• No test triggers child.on("error", ...) in launch.js:112–119
• Traceability matrix maps REQ-CLI-019 → TC-CLI-076, but TC-CLI-076 tests "no CLI found" (different path)
• Fix: add a test that passes a nonexistent binary and asserts error message/exit code

F-003 — Spec frontmatter says version 0.3.0, package.json is 0.5.0

• Affects requirements.md, design.md, validation.md — all say version: "0.3.0"
• Fix: bump all three to 0.5.0 and add revision history entries

---

Medium Severity

F-004 — REQ-CLI-082 (publishConfig) has no automated test

• Validation plan says "verified by package.json inspection" — no TC covers this
• Fix: add a test asserting publishConfig.access === "public" and scoped package name

F-005 — REQ-CLI-091 (cross-platform) has no CI matrix

• Platform-aware code exists but no CI runs tests on Windows + macOS + Linux
• Fix: add a GitHub Actions matrix job

F-006 — TC-CLI-071 (gh-copilot detection) not implemented

• detectCli() gh-copilot branch is untested
• Fix: implement TC-CLI-071

F-007 — TC-CLI-075 (--cli flag override) not implemented

• REQ-CLI-011 core behavior is untested
• Fix: implement TC-CLI-075

F-008 — TC-CLI-079 (temp dir cleanup on exit) not implemented

• REQ-CLI-018 cleanup behavior is untested
• Fix: implement TC-CLI-079

F-009 — TC-CLI-100/121 (npm pack distribution) not implemented

• No test runs npm pack --dry-run to verify package contents
• Fix: implement as a build-type test

F-010 — TC-CLI-073 type mismatch (integration vs spec's unit)

• Spec says "Type: Unit — call detectCli() directly"; test runs full CLI binary via execFileSync
• Fix: refactor TC-CLI-073 to call detectCli() as a unit

F-011 — REQ-CLI-094 (dependency count) has no automated test

• One assertion (Object.keys(pkg.dependencies).length === 2) would cover this
• Fix: add assertion to package.json inspection test

---

Low Severity

F-012 — REQ-CLI-082/090 not traced in design document

• engines and publishConfig fields not mentioned in design doc §6
• Fix: add brief §6 entries for both

F-013 — GAP-010 in design.md should be marked resolved

• cli.js:48 already documents valid --cli values; gap is closed
• Fix: update GAP-010 status to "Resolved in v0.5.0"

F-014 — Informational launch messages undocumented

• launch.js prints "PromptKit content staged at: ..." and "Launching [cli]..." — not in any spec
• Fix: document in design.md §4 or requirements

F-015 — Usage hint references stale assemble verb

• cli.js:98 hint doesn't mention interactive subcommand
• Fix: update hint to say "run promptkit interactive"

F-016 — TC-CLI-077 (fallback warning) not implemented

• Fix: implement TC-CLI-077

F-017 — TC-CLI-101 (content/ gitignored) not automated

• Could be a static test asserting .gitignore contains content/
• Fix: implement as a simple assertion

F-018 — TC-CLI-078 only checks 2 of 5 component directories

• Test asserts personas/ and templates/ exist but skips protocols/, formats/, taxonomies/
• Fix: add assertions for all five

F-019 — TC-CLI-002 doesn't test -V short flag

• REQ-CLI-003 says "--version or -V" but test only uses --version
• Fix: add -V assertion

F-020 — TC-CLI-053 assertion too weak

• Spec says hint should reference "promptkit interactive"; test only checks for "promptkit"
• Fix: tighten assertion to check for "interactive"

---

Reference Files

• cli/specs/audit-sonnet.md — Sonnet blind audit (18 findings, overlaps heavily)
• cli/specs/audit-delta.md — Root cause analysis of what agents miss and why
• cli/specs/maintenance-audit.md — Original 8-finding audit