Persist derived machine states for agent manifests so downstream monitors can distinguish working, blocked, degraded, and finished-cleanable lanes without inferring everything from prose. This also records commit provenance in terminal-state manifests and marks the new session-state classification roadmap item as done.
Constraint: Keep the change scoped to manifest persistence and tests without introducing a new monitoring service layer
Rejected: Leave state classification as downstream text scraping only | repeated dogfood runs showed quiet/finished lanes being misreported as stale
Confidence: medium
Scope-risk: narrow
Directive: Reuse derived_state + commit provenance from manifests before adding any new stale-session heuristics elsewhere
Tested: python .github/scripts/check_doc_source_of_truth.py
Tested: cd rust && cargo fmt --all --check
Tested: cd rust && cargo test -q -p tools
Tested: cd rust && cargo clippy -p tools --all-targets --no-deps -- -D warnings
Not-tested: full cargo clippy --workspace --all-targets -- -D warnings still fails on unrelated pre-existing runtime lint debt
Finish the remaining roadmap work by making direct CLI JSON output deterministic across the non-interactive surface, restoring the degraded-startup MCP test as a real workspace test, and adding branch-lock plus commit-lineage primitives so downstream lane consumers can distinguish superseded worktree commits from canonical lineage.
Constraint: Keep the user-facing config namespace centered on .claw while preserving legacy fallback discovery for compatibility
Constraint: Verification needed to stay clean-room and reproducible from the checked-in workspace alone
Rejected: Leave the output-format contract implied by ad-hoc smoke runs only | too easy for direct CLI regressions to slip back into prose-only output
Rejected: Keep commit provenance as free-form detail text | downstream consumers need structured branch/worktree/supersession metadata
Confidence: medium
Scope-risk: moderate
Directive: Extend the JSON contract through the same direct CLI entrypoints instead of adding one-off serializers on parallel code paths
Tested: python .github/scripts/check_doc_source_of_truth.py
Tested: cd rust && cargo fmt --all --check
Tested: cd rust && cargo test --workspace
Tested: cd rust && cargo clippy -p commands -p tools -p rusty-claude-cli --all-targets --no-deps -- -D warnings
Not-tested: full cargo clippy --workspace --all-targets -- -D warnings still reports unrelated pre-existing runtime lint debt outside this change set
Replace the stale Python-first README narrative, old community links, and leftover branded metadata with the current Rust-first repo guidance. Also align funding handles and asset naming so the public docs point at the canonical ultraworkers/claw-code surface.\n\nConstraint: Scope limited to docs/metadata and branding residue; no runtime behavior changes\nRejected: Add a new CI lint in this pass | outside the requested docs-and-config cleanup scope\nConfidence: medium\nScope-risk: narrow\nReversibility: clean\nDirective: Keep README, funding metadata, and community links aligned with ultraworkers/claw-code and the current UltraWorkers Discord invite\nTested: stale-branding grep across markdown/.github; root doc-link existence checks; cargo fmt --all --check; cargo check --workspace; cargo test --workspace\nNot-tested: cargo clippy --workspace --all-targets -- -D warnings | fails on pre-existing runtime lint debt unrelated to these doc changes
Add a checked-in Containerfile plus container-first documentation so Docker and Podman users have a canonical image build, bind-mount, and cargo test entrypoint. The README now links directly to the new guide.
Constraint: The repo already had runtime container detection but no checked-in Dockerfile, Containerfile, or devcontainer config
Rejected: Put all container steps inline in README only | harder to maintain and less reusable than a dedicated guide plus Containerfile
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep docs/container.md and Containerfile aligned whenever Rust workspace prerequisites change
Tested: docker build -t claw-code-dev-docs-verify -f Containerfile .
Tested: cargo test --workspace (host, in rust/)
Not-tested: Podman commands were documented but not executed in this environment
Not-tested: Repeated in-container cargo test --workspace currently trips crates/tools PowerShell stub detection on this minimal image even though host cargo test passes
The skills and mcp inventory handlers were still emitting prose tables even when the global --output-format json flag was set. This wires structured JSON renderers into the command handlers and CLI dispatch so direct invocations and resumed slash-command execution both return machine-readable payloads while preserving existing text output in the REPL path.
Constraint: Must preserve existing text output and help behavior for interactive slash commands
Rejected: Parse existing prose tables into JSON at the CLI edge | brittle and loses structured fields
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep text and JSON variants driven by the same command parsing branches so --output-format stays deterministic across entry points
Tested: cargo test -p commands
Tested: cargo test -p rusty-claude-cli
Not-tested: Manual invocation against a live user skills registry or external MCP services
Agents, skills, and init output were still surfacing .codex/.claude paths even though the runtime already treats .claw as the canonical config home. This updates help text, reports, skill install defaults, and repo bootstrap output to present a single .claw namespace while keeping legacy discovery fallbacks in place for existing setups.
Constraint: Existing .codex/.claude agent and skill directories still need to load for compatibility
Rejected: Remove legacy discovery entirely | would break existing user setups instead of just cleaning up surfaced output
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep future user-facing config, agent, and skill path copy aligned to .claw and even when legacy fallbacks remain supported internally
Tested: cargo fmt --all --check; cargo test --workspace --exclude compat-harness
Not-tested: cargo clippy --workspace --all-targets -- -D warnings | fails in pre-existing unrelated runtime files (for example mcp_lifecycle_hardened.rs, mcp_tool_bridge.rs, lsp_client.rs, permission_enforcer.rs, recovery_recipes.rs, stale_branch.rs, task_registry.rs, team_cron_registry.rs, worker_boot.rs)
The direct CLI wrappers for agents, skills, and mcp treated nested help flags as ordinary operands. That made commands like `claw mcp show --help` report a missing server and `claw skills install --help` fall into filesystem install logic instead of surfacing usage.
This change normalizes help-path arguments before dispatch so nested help stays on the help path. The regression tests cover both handler-level behavior and end-to-end CLI output for nested help and unknown subcommands with trailing help flags.
Constraint: Keep the fix scoped to direct CLI slash-command wrappers without changing unrelated parser behavior
Rejected: Rework top-level argument parsing for all subcommands | broader risk than needed for the regression
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If more nested subcommands are added, extend the help-path normalization table before relying on raw operand dispatch
Tested: cargo build -p commands -p rusty-claude-cli
Tested: cargo test -p commands -p rusty-claude-cli
Not-tested: cargo clippy -p commands -p rusty-claude-cli --all-targets --no-deps -- -D warnings (pre-existing warnings in untouched files block clean run)
Promote doctor into a real top-level CLI action, reuse the same local report for resumed and REPL doctor invocations, and intercept doctor/status/sandbox help flags before prompt-mode dispatch. The parser change also closes the help fallthrough that previously wandered into runtime startup for local-info commands.
Constraint: Preserve prompt shorthand for normal multi-word text input while fixing exact local subcommand help paths
Rejected: Route \7[1G[2K[m⠋ 🦀 Thinking...[0m8[1G[2K[m✘ ❌ Request failed
[0m through prompt/slash guidance | still shells out through the wrong surface and keeps health checks hidden
Rejected: Reuse the status report as doctor output | status does not explain auth/config health or expose a dedicated diagnostic summary
Confidence: high
Scope-risk: narrow
Directive: Keep doctor local-only unless an explicit network probe is intentionally added and separately tested
Tested: cargo build -p rusty-claude-cli; cargo test -p rusty-claude-cli; cargo run -p rusty-claude-cli -- doctor --help; CLAW_CONFIG_HOME=/tmp/tmp.7pm9SVzOPN ANTHROPIC_API_KEY= ANTHROPIC_AUTH_TOKEN= cargo run -p rusty-claude-cli -- doctor
Not-tested: direct /doctor outside the REPL remains interactive-only
The shipped CLI surface lives in `src/main.rs`, which only wires `init`,
`input`, and `render`. The legacy `app.rs` and `args.rs` prototypes were
not in the module tree and had no inbound references, so this change deletes
those orphaned files instead of widening scope into a larger refactor.
It also aligns the TUI enhancement plan with that reality so the document no
longer describes the removed prototypes as current tracked structure.
Constraint: Must preserve shipped CLI parsing and slash-command behavior
Rejected: Refactor main.rs into smaller modules now | widens scope beyond behavior-safe cleanup
Rejected: Leave TUI plan wording untouched | leaves low-risk stale documentation behind
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep this slice deletion-first; do not reintroduce alternate CLI surfaces without wiring them into main.rs and its tests
Tested: cargo test -p rusty-claude-cli defaults_to_repl_when_no_args
Tested: cargo test -p rusty-claude-cli parses_login_and_logout_subcommands
Tested: cargo test -p rusty-claude-cli parses_direct_agents_mcp_and_skills_slash_commands
Tested: cargo test -p rusty-claude-cli direct_slash_commands_surface_shared_validation_errors
Tested: cargo test -p rusty-claude-cli parses_resume_flag_with_multiple_slash_commands -- --nocapture
Tested: cargo test -p rusty-claude-cli resumed_binary_accepts_slash_commands_with_arguments -- --nocapture
Tested: cargo check -p rusty-claude-cli
Tested: git diff --check
Not-tested: cargo clippy -p rusty-claude-cli --all-targets -- -D warnings (pre-existing failures in rust/crates/runtime/* and existing warnings outside this diff)
Promote doctor into a real top-level CLI action, reuse the same local report for resumed and REPL doctor invocations, and intercept doctor/status/sandbox help flags before prompt-mode dispatch. The parser change also closes the help fallthrough that previously wandered into runtime startup for local-info commands.
Constraint: Preserve prompt shorthand for normal multi-word text input while fixing exact local subcommand help paths
Rejected: Route \7[1G[2K[m⠋ 🦀 Thinking...[0m8[1G[2K[m✘ ❌ Request failed
[0m through prompt/slash guidance | still shells out through the wrong surface and keeps health checks hidden
Rejected: Reuse the status report as doctor output | status does not explain auth/config health or expose a dedicated diagnostic summary
Confidence: high
Scope-risk: narrow
Directive: Keep doctor local-only unless an explicit network probe is intentionally added and separately tested
Tested: cargo build -p rusty-claude-cli; cargo test -p rusty-claude-cli; cargo run -p rusty-claude-cli -- doctor --help; CLAW_CONFIG_HOME=/tmp/tmp.7pm9SVzOPN ANTHROPIC_API_KEY= ANTHROPIC_AUTH_TOKEN= cargo run -p rusty-claude-cli -- doctor
Not-tested: direct /doctor outside the REPL remains interactive-only
The global --output-format json flag already reached prompt-mode responses, but
status and sandbox still bypassed that path and printed human-readable tables.
This change threads the selected output format through direct command aliases
and resumed slash-command execution so status queries emit valid structured
JSON instead of mixed prose.
It also adds end-to-end regression coverage for direct status/sandbox JSON
and resumed /status JSON so shell automation can rely on stable parsing.
Constraint: Global output formatting must stay compatible with existing text-mode reports
Rejected: Require callers to scrape text status tables | fragile and breaks automation
Confidence: high
Scope-risk: narrow
Directive: New direct commands that honor --output-format should thread the format through CliAction and resumed slash execution paths
Tested: cargo build -p rusty-claude-cli
Tested: cargo test -p rusty-claude-cli -- --nocapture
Tested: cargo test --workspace
Tested: cargo run -q -p rusty-claude-cli -- --output-format json status
Tested: cargo run -q -p rusty-claude-cli -- --output-format json sandbox
Not-tested: cargo clippy --workspace --all-targets -- -D warnings (fails in pre-existing runtime files unrelated to this change)
The runtime already tracked rough token estimates for compaction, but provider-bound
requests still relied on naive model output limits and could be sent upstream even
when the selected model could not fit the estimated prompt plus requested output.
This adds a small model token/context registry in the API layer, estimates request
size from the serialized prompt payload, and fails locally with a dedicated
context-window error before Anthropic or xAI calls are made. Focused integration
coverage asserts the preflight fires before any HTTP request leaves the process.
Constraint: Keep the first pass minimal and reusable across both Anthropic and OpenAI-compatible providers
Rejected: Auto-compact-and-retry in the same patch | broader control-flow change than the requested minimal preflight
Confidence: medium
Scope-risk: narrow
Reversibility: clean
Directive: Expand the model registry before enabling preflight for additional providers or aliases
Tested: cargo build -p api -p tools -p rusty-claude-cli; cargo test -p api
Not-tested: End-to-end CLI auto-compaction or retry behavior after a local context_window_blocked failure
The direct CLI wrappers for agents, skills, and mcp treated nested help flags as ordinary operands. That made commands like `claw mcp show --help` report a missing server and `claw skills install --help` fall into filesystem install logic instead of surfacing usage.
This change normalizes help-path arguments before dispatch so nested help stays on the help path. The regression tests cover both handler-level behavior and end-to-end CLI output for nested help and unknown subcommands with trailing help flags.
Constraint: Keep the fix scoped to direct CLI slash-command wrappers without changing unrelated parser behavior
Rejected: Rework top-level argument parsing for all subcommands | broader risk than needed for the regression
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If more nested subcommands are added, extend the help-path normalization table before relying on raw operand dispatch
Tested: cargo build -p commands -p rusty-claude-cli
Tested: cargo test -p commands -p rusty-claude-cli
Not-tested: cargo clippy -p commands -p rusty-claude-cli --all-targets --no-deps -- -D warnings (pre-existing warnings in untouched files block clean run)
session_control is pub exported but has zero consumers workspace-wide.
trust_resolver types are re-exported but never instantiated outside
unit tests. These implement core clawability contracts that are
structurally dead — built but not wired into the actual execution path.
This adds crate-level and type-level Rustdoc to the runtime crate's core exported types so downstream crates and contributors can understand the session, prompt, permission, OAuth, usage, and tool I/O primitives without spelunking every implementation file.
Constraint: The docs pass needed to stay focused on public runtime types without changing behavior
Rejected: Add blanket docs to every public item in one sweep | larger churn than needed for a targeted docs pass
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When exporting new runtime primitives from lib.rs, add a short Rustdoc summary in the defining module at the same time
Tested: cargo build --workspace; cargo test --workspace
Not-tested: rustdoc HTML rendering beyond doc-test coverage
The root and Rust-facing docs now point readers at a single task-oriented usage guide with build, auth, CLI, session, and parity-harness examples. This also fixes stale workspace references and updates the Rust workspace inventory to match the current crate set.
Constraint: Existing README copy still referenced the old dev/rust status and needed to stay lightweight
Rejected: Fold all usage details into README.md only | too much noise for the landing page
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep USAGE examples aligned with when CLI flags change
Tested: cargo build --workspace; cargo test --workspace
Not-tested: External links and rendered Markdown in GitHub UI
Config merge validation gap fixed at 5bee22b:
- Hook validation before deep-merge in config.rs
- Source-path context for malformed entries
- Prevents non-string hook arrays from poisoning runtime
Validate hook arrays in each config file before deep-merging so malformed entries fail with source-path context instead of surfacing later as a merged hook parse error.
Constraint: Runtime hook config currently supports only string command arrays
Rejected: Add hook-specific schema logic inside deep_merge_objects | keeps generic merge helper decoupled from config semantics
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep hook validation source-aware before generic config merges so file-specific errors remain diagnosable
Tested: cargo build --workspace; cargo test --workspace
Not-tested: live claw --help against a malformed external user config
