v0.9.1: Report artifact-skill readiness and define a managed dependency runtime

[Hmbown]

Problem

CodeWhale bundles four first-party workflow recipes for presentations, spreadsheets, PDFs, and documents. The recipes are discoverable as Available/Built-in, but CodeWhale does not currently report whether the host has the external tools needed for each operation.

The v0.9.0 audit initially misclassified all four as broken. The actual state is more nuanced:

• document structure work and CSV analysis can work with the current host
• PDF reading is self-contained through the bundled Rust extractor
• XLSX/PPTX authoring and advanced PDF/document rendering may require Python/Node/Poppler/LibreOffice dependencies
• the similarly named Codex skills use a separate managed runtime and cannot simply be copied into CodeWhale

Installing packages globally on one maintainer machine would hide the product gap rather than solve it for npm, Cargo, binary, and Docker users.

Current evidence

• Bundled skill installation: crates/tui/src/skills/system.rs
• Skill recipes: crates/tui/assets/skills/{presentations,spreadsheets,pdf,documents}/SKILL.md
• PDF extraction: crates/tui/src/tools/file.rs
• Human doctor probes some host tools, but doctor --json does not map them to individual skills
• Docker ships the Rust binary without Python/Node/Poppler/LibreOffice

Scope

1. Add deterministic per-skill readiness probes with states such as ready, partial, and needs_setup.
2. Surface the result in /skills and doctor --json without claiming that a recipe is turnkey when dependencies are absent.
3. Clarify bundled-skill copy: these are dependency-conditional workflow guides.
4. Decide and document the long-term runtime:
   • checksummed, versioned, per-platform CodeWhale artifact runtime and loader, or
   • deliberately external dependencies with guided setup.
5. Keep PDF read readiness distinct from PDF create/edit/render readiness.

Acceptance criteria

• A clean Docker fixture reports truthful status for all four bundled artifact skills.
• PDF reading reports ready when the Rust extractor is present even without Poppler/Python.
• XLSX/PPTX authoring reports needs setup when required tooling is absent.
• doctor --json exposes per-skill readiness and missing capabilities.
• /skills does not conflate recipe discovery with runtime readiness.
• Tests use mocked command/module probes and do not install packages globally.
• If bundled SKILL.md copy changes, BUNDLED_SKILL_VERSION is bumped and migration behavior is covered.

Non-goals

• Do not depend on the maintainer's Codex-managed runtime.
• Do not silently pip install or mutate a user's system Python.
• Do not remove bundled PDF reading, which is already self-contained.

[CCChisato]

Implementation progress update — artifact-skill readiness (Issue #4407)

This comment documents the work done so far on this issue, what works, what doesn't, and why.

Files changed

8 files (7 tracked + 1 new):

File	Change
crates/tui/src/skills/probe.rs (new)	ReadinessProbe trait, global HashMap registry, helpers, NeverReadyProbe test struct
crates/tui/src/skills/mod.rs	SkillReadiness enum, readiness field on Skill, pub mod probe
crates/tui/src/skills/system.rs	BundledSkill gains probe field; PresentationsProbe, SpreadsheetsProbe; Phase 1/2 separation in install_system_skills()
crates/tui/src/runtime_api.rs	SkillEntry includes readiness, populated via probe::probe()
crates/tui/src/commands/groups/skills/skills.rs	skill_readiness_badge() helper; activate_skill() appends readiness notice
crates/tui/src/tui/slash_menu.rs	/skill preview includes readiness badge
crates/tui/src/main.rs	doctor --json per-skill readiness + required_tools

What works

• ReadinessProbe trait + global registry, no hardcoded match. Each BundledSkill with known deps has probe: Some(make_xxx_probe).
• doctor --json verified working: 3 probed skills show NeedsSetup, others Unknown. Required tools listed.
• Runtime API SkillEntry.readiness populated on query.
• Activation readiness notice injected for NeedsSetup skills.
• BUNDLED_SKILL_VERSION bumped 4->5.

What does NOT work

1. TUI /skills display: skill_readiness_badge() IS called, text IS in the CommandResult::message() output (confirmed via file-write debug). But the TUI transcript renderer does not display it. Even plain ! is swallowed. Root cause is in the HistoryCell::System rendering pipeline.

2. TUI /skill preview: Same rendering pipeline issue.

3. Agent-update-readiness tool: Not implemented. Needs a temporary tool registered during skill execution.

Design rationale

• Trait over hardcoded: Each skill with deps implements ReadinessProbe via struct + factory fn.
• Phase 1/2 in install_system_skills(): Probe registration (memory ops) before file installation, survives filesystem errors.
• Semantic honesty: Unprobed skills show Unknown, not Ready.

Suggestions for next work

1. Debug transcript.rs HistoryCell::System rendering.
2. Implement /skill readiness set + persistence (skills_readiness.toml).
3. Register temporary tool for agent-driven readiness updates.
4. Add /skill readiness probe for manual re-testing.
5. Clean up: cargo fmt, #[allow(dead_code)] on readiness field, remove test skill.

[Hmbown]

Thank you—this is substantial progress, and the honest Unknown fallback is the right bias.

Please open a draft PR with the current branch, even while the TUI path is still red. That lets us review and preserve your authorship instead of reconstructing the work from a status comment. Use Refs #4407 while it is partial; only use a closing reference once the issue's acceptance criteria are all covered.

For the first mergeable slice, keep the cutline tight:

• a capability-level readiness model that can distinguish Ready, Partial, NeedsSetup, and Unknown—especially PDF read versus create/render;
• deterministic, injectable/mocked probes for the four bundled artifact skills;
• truthful doctor --json and Runtime API output;
• one verified /skills presentation path that does not conflate discovery with readiness;
• Docker-fixture coverage with no global package installation.

Please defer the temporary agent-update tool and persisted manual readiness overrides to a follow-up. Those introduce a second source of truth and an authority/persistence surface before the probes themselves are stable. Also, only bump BUNDLED_SKILL_VERSION if bundled SKILL.md copy actually changes; a Rust-only readiness implementation should not force a content migration.

One review flag for the draft: a process-global mutable HashMap registry may make reset behavior and parallel tests brittle. An injected/read-only registry owned by the skill system would be easier to reason about, but seeing your exact implementation in the draft is better than redesigning it from the comment alone.

Once the draft is up, we can help isolate the HistoryCell::System rendering issue and decide whether that fix belongs in the same PR or a small prerequisite.