Feat/structure polishing (#43)

* docs updates

* performance improvements

* fix: status line update

Author: RomanEmreis

AGENTS.md

@@ -28,21 +28,31 @@ All three checks must pass before submitting: `clippy -D warnings`, `fmt --check
 ```
 src/
   main.rs                    # CLI entry, tracing init, HQ logger
-  cli/                       # clap subcommands (init, serve, register)
-  config/mod.rs              # Deserialize ferrus.toml (ChecksConfig, LimitsConfig, LeaseConfig, HqConfig)
+  cli/                       # clap entry and command implementations (init, serve, register)
+  config/mod.rs              # Deserialize/update ferrus.toml (ChecksConfig, LimitsConfig, LeaseConfig, SpecConfig, HqConfig)
+  config/claude.rs           # Claude MCP isolation config helpers
+  templates.rs               # Embedded Markdown templates written by init/resource fallback
+  specs.rs                   # Spec discovery, milestone parsing, selected milestone resolution
+  agent_id.rs                # Stable agent IDs and MCP server names
+  agents/                    # Agent launcher/config adapters for Claude Code, Codex, Qwen Code
+  agents/mod.rs              # SupervisorAgent/ExecutorAgent traits, AgentRunMode, MCP config entry helpers, agent parsing
+  agents/claude/mod.rs       # Claude Code launchers, model override handling, MCP isolation, role-scoped config paths
+  agents/codex/mod.rs        # Codex launchers, stdin prompt transport, TOML MCP config and tool approvals
+  agents/qwen/mod.rs         # Qwen Code launchers, model override handling, JSON settings tool approvals
+  platform/                  # OS-specific process, shell, and parent-lifecycle helpers
   state/machine.rs           # TaskState enum + StateData + transition methods + lease helpers
   state/store.rs             # Async read/write of .ferrus/ files; open_lock_file, claim_state
   state/agents.rs            # AgentEntry, AgentsRegistry — .ferrus/agents.json lifecycle tracking
   update_check.rs            # HQ startup version-check helper (crates.io sparse index + local cache)
   checks/runner.rs           # Spawn check subprocesses, collect output
   hq/mod.rs                  # HQ entry point; HqContext; tokio::select! loop; transition_action
   hq/state_watcher.rs        # Background task: polls STATE.json every 250ms, watch channel
-  hq/tui.rs                  # Terminal UI (crossterm): App event loop, UiMessage, StatusSnapshot; autocomplete, command history, spec/milestone status line, confirmation/selection dialogs; double-Ctrl+C-to-quit (2-second window)
+  hq/tui.rs                  # Terminal UI (crossterm): App event loop, UiMessage, StatusSnapshot; autocomplete, command history, spec/milestone status line, confirmation/selection dialogs, AwaitingHuman answer hint; double-Ctrl+C-to-quit
   hq/commands.rs             # ShellCommand enum, parse_command() via clap + shlex
   hq/display.rs              # Display wrapper: sends UiMessage to TUI channel (info, error, transition, status, suspend, resume, confirm)
   hq/agent_manager.rs        # agent spawn helpers (headless for executor, reviewer, consultant); HeadlessHandle; agents.json updates
   server/mod.rs              # neva App setup; constructs agent_id, wires closures
-  server/tools/              # One file per MCP tool (one module = one tool)
+  server/tools/              # One file per MCP tool (one module = one tool); check_gate.rs is the shared check runner/report helper
   server/resources.rs        # MCP resource handler (ferrus://{file})
   server/prompts.rs          # MCP prompt handlers
 ```
@@ -59,6 +69,12 @@ src/
 
 **Spec selection**: `STATE.json` stores `selected_spec` and `selected_milestone` as UI references only. Active task progress uses `task_spec` and `task_milestone`, copied from `pending_task_*` when `/create_task` succeeds. Milestone display text is resolved from the spec Markdown by milestone `ID`. Keep milestone IDs stable across title edits.
 
+**Agent adapters**: keep backend-specific CLI behavior inside `src/agents/{claude,codex,qwen}`. Shared orchestration should depend on the `SupervisorAgent` and `ExecutorAgent` traits, not on a concrete agent CLI. When adding an agent, implement both role adapters, model normalization, headless prompt transport if needed, version/config entry behavior, registration wiring, and focused tests.
+
+**HQ checks**: `/check` calls the same MCP check handler as an Executor and therefore updates retry state. `/check --force` runs configured commands directly from HQ and does not modify `STATE.json`.
+
+**HQ reset vs MCP reset**: HQ `/reset` force-resets from any state after confirmation when active agents may be running, clears task/answer/consultation files, and preserves selected spec/milestone. The MCP `/reset` tool is only valid from `Failed`.
+
 ## Ferrus Executor
 
 This repository is orchestrated by Ferrus HQ.

CLAUDE.md

@@ -49,6 +49,9 @@ ferrus register [--supervisor <agent>] [--supervisor-model <model>] [--executor
 | `/task --manual` | Define a free-form task without selected milestone context |
 | `/spec` | Draft, approve, and save a feature specification |
 | `/milestones` | Select the current spec and milestone |
+| `/reset-spec` | Clear the selected spec and milestone |
+| `/check` | Run the Ferrus check gate from HQ, using the normal task-state rules |
+| `/check --force` | Run configured checks from HQ without modifying state |
 | `/supervisor` | Open an interactive supervisor session (no initial prompt, no state requirement) |
 | `/executor` | Open an interactive executor session (no initial prompt, no state requirement) |
 | `/resume` | Manually resume the executor headlessly; also recovers Consultation by relaunching both consultant and executor |
@@ -58,8 +61,9 @@ ferrus register [--supervisor <agent>] [--supervisor-model <model>] [--executor
 | `/stop` | Stop all running agent sessions (prompts for confirmation) |
 | `/reset` | Reset state to Idle and clear task files (prompts for confirmation) |
 | `/init [--agents-path]` | Initialize ferrus in the current directory |
-| `/register` | Register agent configs (same as `ferrus register`) |
-| `/model` | Update the supervisor or executor model override |
+| `/register [--supervisor <agent>] [--executor <agent>]` | Register Claude Code or Codex configs from HQ |
+| `/model <supervisor|executor> <model>` | Update the supervisor or executor model override |
+| `/model <supervisor|executor> --clear` | Clear the supervisor or executor model override |
 | `/help` | List all HQ commands |
 | `/quit` | Exit HQ |
 
@@ -124,6 +128,7 @@ model = ""             # optional override; empty = agent default
 | `/review_pending` | Reviewing | — | Read task + context for review |
 | `/approve` | Reviewing | Complete | Accept the submission |
 | `/reject` | Reviewing | Addressing | Reject with notes; resets Executor retry counter |
+| `/respond_consult` | Consultation | — | Record the Supervisor consultation response in `CONSULT_RESPONSE.md` |
 
 ### Executor tools
 
@@ -141,7 +146,6 @@ model = ""             # optional override; empty = agent default
 | Tool | From state | To state | Description |
 |---|---|---|---|
 | `/ask_human` | Executing, Addressing, Consultation, Reviewing | AwaitingHuman | Last-resort human fallback. Write question to QUESTION.md; agent must immediately call `/wait_for_answer` (executor) or wait for HQ to answer |
-| `/respond_consult` | Consultation | — | Record the Supervisor consultation response in `CONSULT_RESPONSE.md` |
 | `/answer` | AwaitingHuman | (previous state) | Provide answer to a pending question; restores previous state |
 | `/heartbeat` | any claimed | — | Renew lease; call every ~30s while working |
 | `/status` | any | — | Print current state + retry counters |
@@ -206,6 +210,7 @@ Executor verification is TDD-friendly: `/check` can be run as often as needed du
 |---|---|
 | `STATE.json` | Current `TaskState`, lease fields (`claimed_by`, `lease_until`, `last_heartbeat`), retry/cycle counters, failure reason, schema version, last-write timestamp and PID |
 | `STATE.lock` | Advisory lock file for atomic claiming (do not delete) |
+| `agents.json` | Runtime registry for agent sessions, statuses, PIDs, and log ownership |
 | `TASK.md` | Task description written by Supervisor |
 | `REVIEW.md` | Supervisor rejection notes |
 | `SUBMISSION.md` | Executor's submission notes (summary, verification steps, known limitations) |
@@ -225,31 +230,47 @@ Executor verification is TDD-friendly: `/check` can be run as often as needed du
 ```
 src/
   main.rs                    # CLI entry, tracing init, HQ logger
-  cli/                       # clap subcommands (init, serve, register)
-  config/mod.rs              # Deserialize ferrus.toml (ChecksConfig, LimitsConfig, LeaseConfig, HqConfig)
+  cli/                       # clap entry and command implementations (init, serve, register)
+  config/mod.rs              # Deserialize/update ferrus.toml (ChecksConfig, LimitsConfig, LeaseConfig, SpecConfig, HqConfig)
+  config/claude.rs           # Claude MCP isolation config helpers
+  templates.rs               # Embedded Markdown templates written by init/resource fallback
+  specs.rs                   # Spec discovery, milestone parsing, selected milestone resolution
+  agent_id.rs                # Stable agent IDs and MCP server names
+  agents/                    # Agent launcher/config adapters for Claude Code, Codex, Qwen Code
+  agents/mod.rs              # SupervisorAgent/ExecutorAgent traits, AgentRunMode, MCP config entry helpers, agent parsing
+  agents/claude/mod.rs       # Claude Code launchers, model override handling, MCP isolation, role-scoped config paths
+  agents/codex/mod.rs        # Codex launchers, stdin prompt transport, TOML MCP config and tool approvals
+  agents/qwen/mod.rs         # Qwen Code launchers, model override handling, JSON settings tool approvals
+  platform/                  # OS-specific process, shell, and parent-lifecycle helpers
   state/machine.rs           # TaskState enum + StateData + transition methods + lease helpers
   state/store.rs             # Async read/write of .ferrus/ files; open_lock_file, claim_state
   state/agents.rs            # AgentEntry, AgentsRegistry — .ferrus/agents.json lifecycle tracking
   update_check.rs            # HQ startup version-check helper (crates.io sparse index + local cache)
   checks/runner.rs           # Spawn check subprocesses, collect output
   hq/mod.rs                  # HQ entry point; HqContext; tokio::select! loop; transition_action
   hq/state_watcher.rs        # Background task: polls STATE.json every 250ms, sends on watch channel
-  hq/tui.rs                  # Terminal UI (crossterm): App event loop, UiMessage, StatusSnapshot; autocomplete, command history, status line, confirmation dialogs
+  hq/tui.rs                  # Terminal UI (crossterm): App event loop, UiMessage, StatusSnapshot; autocomplete, command history, spec/milestone status line, confirmation/selection dialogs, AwaitingHuman answer hint
   hq/commands.rs             # ShellCommand enum, parse_command() via clap + shlex
   hq/display.rs              # Display wrapper: sends UiMessage to TUI channel (info, error, transition, status, suspend, resume, confirm)
   hq/agent_manager.rs        # agent spawn helpers (headless for executor, reviewer, consultant); HeadlessHandle; agents.json updates
   server/mod.rs              # neva App setup; constructs agent_id, wires closures
-  server/tools/              # One file per MCP tool
+  server/tools/              # One file per MCP tool; check_gate.rs is the shared check runner/report helper
+    answer.rs                # /answer — writes ANSWER.md and restores AwaitingHuman state
     heartbeat.rs             # /heartbeat — lease renewal
     wait_for_task.rs         # /wait_for_task — atomic claim loop (STATE.lock + fs2)
     wait_for_review.rs       # /wait_for_review — same pattern for Supervisor
+    check_gate.rs            # Shared final/diagnostic check execution and report formatting
     consult.rs               # /consult — writes CONSULT_REQUEST.md and transitions to Consultation
     respond_consult.rs       # /respond_consult — records the supervisor consultation response
     wait_for_consult.rs      # /wait_for_consult — polls CONSULT_RESPONSE.md, restores state, returns answer
     ask_human.rs             # /ask_human — writes QUESTION.md, transitions to AwaitingHuman
     wait_for_answer.rs       # /wait_for_answer — polls ANSWER.md, restores state, returns answer
 ```
 
+## Agent Adapter Pattern
+
+Backend-specific CLI behavior belongs in `src/agents/{claude,codex,qwen}`. Shared orchestration should use the `SupervisorAgent` and `ExecutorAgent` traits from `src/agents/mod.rs` instead of matching on a concrete CLI. New agents need both role adapters, model normalization, headless prompt transport if needed, version/config entry behavior, registration wiring, and focused tests.
+
 <!-- ferrus-supervisor-instructions -->
 ## Ferrus Supervisor
 

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "ferrus"
-version = "0.2.7-alpha.3"
+version = "0.2.7-alpha.4"
 edition = "2024"
 rust-version = "1.95.0"
 license = "Apache-2.0"

Cargo.toml

@@ -1,6 +1,6 @@
 # ferrus
 
-[![Ferrus version](https://img.shields.io/badge/ferrus-0.2.7--alpha.3-orange)](https://crates.io/crates/ferrus)
+[![Ferrus version](https://img.shields.io/badge/ferrus-0.2.7--alpha.4-orange)](https://crates.io/crates/ferrus)
 [![Rust version](https://img.shields.io/badge/rustc-1.95+-964B00)](https://releases.rs/docs/1.95.0/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/RomanEmreis/ferrus/blob/main/LICENSE)
 [![Rust](https://github.com/RomanEmreis/ferrus/actions/workflows/rust.yml/badge.svg)](https://github.com/RomanEmreis/ferrus/actions/workflows/rust.yml)
@@ -29,6 +29,8 @@ Ferrus works with existing coding agents:
 
 Agents are treated as interchangeable workers — ferrus provides the runtime, coordination, and state.
 
+Internally, agent support is normalized through `src/agents/`: `mod.rs` defines the shared Supervisor/Executor contracts and MCP config entry shape, while `claude/`, `codex/`, and `qwen/` adapt each CLI's launch flags, model overrides, headless prompt transport, and local permission/config conventions.
+
 > 💡 **Status**: ferrus is currently in alpha and not ready for production.
 
 [Tutorial](https://romanemreis.github.io/ferrus-docs/) | [Roadmap](https://github.com/RomanEmreis/ferrus/blob/main/docs/milestones.md)
@@ -98,6 +100,9 @@ On Linux and macOS for `x86_64` and `aarch64`/`arm64`, `install.sh` downloads th
 | `/task --manual` | Define a free-form task without selected milestone context |
 | `/spec` | Draft, approve, and save a feature specification |
 | `/milestones` | Select the current spec and milestone |
+| `/reset-spec` | Clear the selected spec and milestone |
+| `/check` | Run the Ferrus check gate from HQ, using the normal task-state rules |
+| `/check --force` | Run configured checks from HQ without modifying state |
 | `/supervisor` | Open an interactive supervisor session (no initial prompt) |
 | `/executor` | Open an interactive executor session (no initial prompt) |
 | `/resume` | Manually resume the executor headlessly; also recovers Consultation by relaunching both supervisor and executor |
@@ -107,8 +112,9 @@ On Linux and macOS for `x86_64` and `aarch64`/`arm64`, `install.sh` downloads th
 | `/stop` | Stop all running agent sessions (prompts for confirmation) |
 | `/reset` | Reset state to Idle and clear task files (prompts for confirmation) |
 | `/init [--agents-path]` | Initialize ferrus in the current directory |
-| `/register` | Register agent configs (same as `ferrus register`) |
-| `/model` | Update the supervisor or executor model override |
+| `/register [--supervisor <agent>] [--executor <agent>]` | Register Claude Code or Codex configs from HQ |
+| `/model <supervisor|executor> <model>` | Update the supervisor or executor model override |
+| `/model <supervisor|executor> --clear` | Clear the supervisor or executor model override |
 | `/help` | List all HQ commands |
 | `/quit` | Exit HQ |
 
@@ -151,7 +157,7 @@ Idle
                    └─► Reviewing            ← submit (final check passed)
 ```
 
-Any active Executor work state (Executing, Addressing, Checking) can pause to `Consultation` via `/consult`. HQ spawns the configured Supervisor in consultation mode, and the executor immediately calls `/wait_for_consult` to block until the Supervisor answers via `/respond_consult`.
+Any active Executor work state (Executing, Addressing) can pause to `Consultation` via `/consult`. HQ spawns the configured Supervisor in consultation mode, and the executor immediately calls `/wait_for_consult` to block until the Supervisor answers via `/respond_consult`.
 
 Any active state, including `Consultation`, can pause to `AwaitingHuman` via `/ask_human`. The agent immediately calls `/wait_for_answer` to block until the human responds. The human types their answer in the HQ terminal (raw text, no slash prefix). `/wait_for_answer` restores the previous state and returns the answer.
 
@@ -166,8 +172,9 @@ Any active state, including `Consultation`, can pause to `AwaitingHuman` via `/a
 
 Scaffolds ferrus in the current project (default `--agents-path .agents`):
 
-- Creates `ferrus.toml` with default check commands and limits
+- Creates `ferrus.toml` with default limits and an empty check command list
 - Creates `.ferrus/` runtime directory with all state files and `logs/`
+- Creates `docs/specs/` for approved feature specifications
 - Creates skill files agents load to understand their role:
   - `<agents-path>/skills/ferrus/SKILL.md` — general overview
   - `<agents-path>/skills/ferrus-supervisor/SKILL.md` + `ROLE.md`
@@ -184,13 +191,13 @@ Starts the agent coordination server on stdio. Agents load this as an MCP server
 | `executor` | `wait_for_task`, `check`, `consult`, `submit`, `wait_for_consult`, `wait_for_answer`, `ask_human`, `answer`, `status`, `reset`, `heartbeat` |
 | *(omitted)* | All tools |
 
-### `ferrus register --supervisor <agent> [--supervisor-model <model>] --executor <agent> [--executor-model <model>]`
+### `ferrus register [--supervisor <agent>] [--supervisor-model <model>] [--executor <agent>] [--executor-model <model>]`
 
-Writes agent config files so they automatically load `ferrus serve` as a tool server, and adds only the selected agents' local files to `.gitignore`. Supported agents:
+Writes agent config files so they automatically load `ferrus serve` as a tool server, and adds only the selected agents' local files to `.gitignore`. At least one of `--supervisor` or `--executor` is required; each model flag requires the matching role flag. Supported agents:
 
 | Agent | Config written |
 |---|---|
-| `claude-code` | `.mcp.json` + `.claude/settings.local.json` permissions |
+| `claude-code` | `.claude/mcp-supervisor.json` or `.claude/mcp-executor.json` + `.claude/settings.local.json` permissions |
 | `codex` | `.codex/config.toml` |
 | `qwen-code` | `.qwen/settings.json` |
 
@@ -238,6 +245,7 @@ Check commands run in the directory where `ferrus serve` was started. Full outpu
 |---|---|
 | `STATE.json` | Current state, lease fields, retry/cycle counters, schema version, timestamp |
 | `STATE.lock` | Advisory lock file for atomic claiming (do not delete) |
+| `agents.json` | Runtime registry for agent sessions, statuses, PIDs, and log ownership |
 | `TASK.md` | Task description written by Supervisor |
 | `REVIEW.md` | Supervisor rejection notes |
 | `SUBMISSION.md` | Executor submission notes |