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

Bắt đầu với cli/specs/audit-sonnet.md và cli/specs/audit-delta.md, sau đó đối chiếu các phát hiện với cli/specs/requirements.md, cli/specs/design.md, cli/specs/validation.md, launch.js, cli.js, package.json, các test và cấu hình GitHub Actions. Chạy các test CLI hiện có và kiểm tra dry-run của npm pack; được xem là hoàn tất khi từng phát hiện được liệt kê đã được xử lý và assertion, bản cập nhật tài liệu hoặc độ bao phủ CI được chỉ định đều hiện diện.

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