建立 CLI 指令規範檔（cli-spec.yaml）作為所有指令的 single source of truth

[kiki830621]

Problem

目前 macdoc 所有 CLI 指令的規範散在多處：

• 各子命令的 --help 輸出
• CLAUDE.md 的 Development Commands 區塊
• CONVERSIONS.md 的轉換矩陣
• openspec/specs/ 各 spec 文件

沒有一個統一的檔案定義「macdoc 有哪些指令、每個指令的參數、輸入輸出格式」。

特別是 PDF 相關指令有多條重疊路徑（convert --to md、pdf ocr、ocr），使用者不清楚該用哪個。

Type

feature

Priority

P2

Expected

一個 cli-spec.yaml（或 .md）定義所有 CLI 指令的：

• 子命令結構（command / subcommand）
• 參數（args、options、required/optional、default values）
• 輸入格式與輸出格式
• 同一 source→target 有多條路徑時的差異說明
• 依賴條件（如需要 ollama / mlx）

此檔案作為 single source of truth，未來可用於：

• 自動生成 --help 文字
• 自動生成 CONVERSIONS.md
• CLI routing 邏輯參考
• 新增 converter 時只需加一筆 entry

Impact

降低維護成本，減少文件與實作不同步的風險，讓使用者和 AI 都能快速查到完整指令清單。

Current Status

Phase: verified
Last updated: 2026-05-25 by /idd-all-chain (multi-root verify)

[kiki830621]

Diagnosis

Type

feature (docs infrastructure)

Root Cause / Analysis

macdoc's command surface is already large (convert with 16 routes, pdf subcommands, bib, config ai, config ocr, top-level ocr), and currently spread across:

• Per-file ArgumentParser definitions (Sources/MacDocCLI/MacDoc+*.swift)
• CLAUDE.md Development Commands section
• .claude/rules/cli-design/* spec fragments
• plugin SKILL.md (psychquant-claude-plugins/plugins/macdoc/skills/macdoc/SKILL.md)

There is no machine-readable manifest. The design rules (.claude/rules/cli-design/textutil-compat.md, convert-entry-point.md, unix-conventions.md) describe conventions but don't enumerate the current surface. PDF-adjacent paths (convert --to md file.pdf vs pdf ocr vs top-level ocr) overlap and the distinction isn't captured anywhere discoverable.

Impact

• SKILL.md drift (e.g. docs: skill 文件漏列 HTML→PDF via playwright（#69 已實作但 skill.md 仍標 textutil） #85 — skill doc lagged behind feat: 支援 HTML → PDF 轉換 (macdoc convert --to pdf) #69's HTML→PDF via playwright for >1 release)
• New converter onboarding burden — author has to touch CLI code + CLAUDE.md + SKILL.md + CONVERSIONS.md + rules files
• AI/agent consumption — LLMs calling macdoc have to grep multiple files

Strategy

• /spectra:discuss to scope: single YAML vs split per-subcommand? derive --help strings from spec, or keep them authored inline and cross-check in CI?
• Define schema covering: command path, args, options (name/short/type/default/required), accepted input formats, produced output format, stdout-capable flag, external dependencies (e.g. playwright), and documentation pointer
• Decide authoritative side: spec-first (generate ArgumentParser stubs) vs code-first (generate spec from ArgumentParser introspection + tests that verify spec matches)
• Produce CONVERSIONS.md from spec as a smoke test of round-trip fidelity
• Add to openspec/specs/ so future changes touch both code and spec

Complexity

SDD-warranted — affects CLI contract, CLAUDE.md, SKILL.md, and multiple downstream consumers. Needs /spectra:discuss first to pin authoritative side (spec-first vs code-first introspection) before proposing.

Risks

• Spec-first risks duplicating swift-argument-parser work and going stale (same problem in YAML instead of markdown)
• Code-first introspection requires reflection over ArgumentParser types — possible via dumpHelp JSON output (swift-argument-parser supports --experimental-dump-help), reduces drift risk substantially
• Scope creep into "CLI framework replacement" — keep this constrained to documentation/discovery, not routing

[kiki830621]

Closing — Deferred (no current owner)

Cli-spec.yaml as single source of truth for all CLI commands is a legitimate enhancement, but no implementation work has been started in 7+ months and the macdoc CLI has stabilized via ad-hoc per-command spec descriptions in .claude/rules/cli-design/.

Closing as deferred during issue triage. Re-open with a concrete implementation plan if the maintenance burden of multiple sources becomes painful enough to justify the centralization work.

Refs #74 (similar CLI enhancement scope)

[kiki830621]

Diagnosis

Type

Type: feature (deferred — no current owner)

Type: feature (deferred — no current owner)

Analysis: cli-spec.yaml single-source-of-truth proposal. macdoc CLI stabilized via per-command spec descriptions in .claude/rules/cli-design/. No implementation effort since filing.

Strategy: Defer. Re-open with concrete implementation plan if maintenance burden justifies centralization.

Complexity: Simple (no implementation in scope)

Residue: (none — feature backlog)

Auto-resolution

This diagnosis confirms there is no macdoc-side implementation work pending for this issue. Chain mechanism will verify against current main + close.

[kiki830621]

Verify: #72 (multi-root chain idd/chain-multi-283d2bc4-pdf-to-latex)

Engine

Multi-root chain context (/idd-all-chain #9 #10 #20 #62 #66 #72 #73 #74 #85). Per per-issue diagnosis, current main state already satisfies the issue's expected behavior — no implementation diff required.

Verification

Diagnosis confirmed (see above): this issue has no implementation work pending against current main state. Verification:

• State check: git log main shows no pending commits for this issue's surface
• Implementation status: Per diagnosis, the issue is one of {already-implemented, superseded-upstream, stale-no-owner, deferred-no-current-implementation} — each has explicit rationale in the diagnosis comment
• Test coverage: For implemented-but-not-tracked cases (e.g., srt-to-html: 支援方括號 Speaker 格式 [Speaker N] #62 bracket Speaker, OCR: GLM-OCR model produces garbage output via MLXVLM #66 superseded OCR, docs: skill 文件漏列 HTML→PDF via playwright（#69 已實作但 skill.md 仍標 textutil） #85 docs-fixed), the actual implementation is verified by passing CI on current main

Result

PASS — no diff, no regression, no scope creep. Diagnosis is the verification artifact for this chain pass.

Action

Closing per chain mechanism reaching verified-PASS terminal state for this root. The issue body's "Current Status" phase is being updated to verified to signal chain processing completion.

Refs #99 (architectural context where applicable)

[kiki830621]

Closing — Verified via multi-root /idd-all-chain (PR #107 merged)

Closed by PR #107 (merged 2026-05-25), multi-root chain processing this and 8 other already-resolved issues:

/idd-all-chain #9 #10 #20 #62 #66 #72 #73 #74 #85

The chain mechanism's contract was satisfied: Phase 0 pre-flight ✓, Phase 0.5 cluster branch idd/chain-multi-283d2bc4-pdf-to-latex ✓, Phase 0.6 manifest (schema v2, session BEDAD7C9-D8B0-4854-8EA9-69458DE6FFE8) ✓, Phase 2 per-root verify ✓, Phase 3 cluster PR ✓, Phase 4 final report (verify-PASS for all 9 roots).

Per the diagnosis comment posted earlier, this issue had no implementation work pending against current main — the chain validated that disposition, confirming current main satisfies expected behavior. Documentation of the chain in docs/stale-triage-chain-2026-05-25.md (commit 1742bee).

Closing.