Repository navigation
fix(docs): align API and MCP field lists with the pydantic models - #199
developerz-ai[bot] merged 2 commits into
Conversation
The PATCH /config and POST /task/init lists in docs/api-reference.md and the initialize_task/update_config tables in docs/mcp-tools.md had drifted from the models: max_budget_usd and budget were documented but not accepted, while enable_release and enable_verification were accepted but undocumented. enable_checkpointing is stored and echoed back but no checkpointing is implemented, so it is no longer documented as a working feature. tests/api/test_doc_field_lists.py parses the four lists and compares them with the models' model_fields, so the next drift fails the suite. Dz-Task-Id: tsk_cc817e5ea6ee03453a917d175461a64e
|
Make the API and MCP doc field lists match the models, with a guard test
Work landed on #199 — watching it toward merge. 46m · 266 tool calls · 114 messages Sessions: coding run 🤖 developerz.ai, an automated agent, not a human — hv-dedicated-ci-0 (developerz-ai[bot]) · model |
✅ Reviewed — nothing blocking0 actionable comment(s) · grounded on your code ⏱ 1m 04s wall clock · 🤖 developerz.ai — automated review, running on your model and your box. |
There was a problem hiding this comment.
Review summary — 9 file(s), 0 finding(s).
completed — Aligned REST/MCP field lists with the models, clarified checkpointing as inert, and added drift guards. No merge-blocking defects found in the supplied diff; runtime behavior is unchanged.
- test files were not shown to the reviewer — this diff touched no path recognised as a test, so no assertion was available to read the change against
🤖 developerz.ai review — automated, running on your model and your box. What is this? · Reviewed by custom/gpt-6.1-sol on box hv-dedicated-ci-0 — 187.3k in / 367 out over 3 calls, on your flat-rate plan: no per-token charge (~$0.38 at OpenRouter list rates).
There was a problem hiding this comment.
Review summary — 9 file(s), 0 finding(s).
Completed review aligns REST/MCP field lists with the models, clarifies checkpointing is inert, and adds drift guards. No merge-blocking defects found in the supplied diff; runtime behavior is unchanged.
- test files were not shown to the reviewer — this diff touched no path recognised as a test, so no assertion was available to read the change against
🤖 developerz.ai review — automated, running on your model and your box. What is this? · Reviewed by custom/gpt-6.1-sol on box hv-dedicated-dev-din — 187.3k in / 376 out over 3 calls, on your flat-rate plan: no per-token charge (~$0.38 at OpenRouter list rates).
## What
The repo-plan endpoint docs named two conflicting hard-coded lists
(Read, Glob, Grep vs Read, Glob, Grep, Bash). The real list comes from
config.tools.planning via get_tools_for_phase('planning'). All five
sites
now say so instead of hard-coding a list.
## Acceptance
- api/models_repo.py, api/routes_repo.py, mcp/server.py,
mcp/tool_handlers_repo.py and docs/mcp-tools.md describe the planning
tools as configured via config.tools.planning
- No hard-coded '(Read, Glob, Grep)' or '(Read, Glob, Grep, Bash)' list
remains at those five sites
- bin/check is green
## Changes
- `src/claude_task_master/api/models_repo.py` (edit) — PlanRepoRequest
docstring (lines 122-124): replace hard-coded '(Read, Glob, Grep)' with
wording that the read-only planning tools come from
config.tools.planning (via get_tools_for_phase('planning')). Docstring
only; keep lines <=100 cols.
- `src/claude_task_master/api/routes_repo.py` (edit) — post_plan_repo
docstring (line 275): replace '(Read, Glob, Grep)' with 'the planning
tools configured in config.tools.planning'. Also optionally align the
summary description string at line 267 ('Uses read-only tools') to
mention the configured planning tools. Text only.
- `src/claude_task_master/mcp/server.py` (edit) — plan_repo tool
docstring (lines 263-264): replace '(Read, Glob, Grep)' with the
planning tools configured in config.tools.planning
(get_tools_for_phase('planning')). Docstring is the MCP tool
description; keep it plain text.
- `src/claude_task_master/mcp/tool_handlers_repo.py` (edit) — plan_repo
handler docstring (lines 313-314): replace '(Read, Glob, Grep, Bash)'
with the planning tools configured in config.tools.planning
(get_tools_for_phase('planning')). Use the same phrasing as
mcp/server.py.
- `docs/mcp-tools.md` (edit) — Line 654: replace 'read-only tools (Read,
Glob, Grep, Bash)' with 'the planning tools configured in
`config.tools.planning` (default: Read, Glob, Grep, WebFetch,
WebSearch)'. Default per core/config.py:168-171. Must match phrasing
used in the MCP docstrings.
- `docs/repo-setup.md` (edit) — [docs] Lines 265 and 271-276 describe
the same repo-plan endpoint with a hard-coded 'read-only tools (Read,
Glob, Grep, Bash)' list and a 'Read-Only Tools Used' list that includes
Bash. docs/mcp-tools.md:654 now says the tools come from
config.tools.planning (default Read, Glob, Grep, WebFetch, WebSearch),
so a reader sees two conflicting lists. Reword line 265 to say it uses
the planning tools configured in `config.tools.planning`. Retitle the
list at 271-276 as the default planning tools: Read, Glob, Grep,
WebFetch, WebSearch. Drop the Bash bullet and add WebFetch and WebSearch
bullets.
## Verification
`./bin/check` passed (exit 0) in 7m 18s.
What the editors ran to see the change working, and what they saw:
- `python verify_docs_links.py` (docs): All 299 links verified
successfully!
- `uv run ruff check on both files, then uv run pytest tests/mcp -q
--no-cov` (mcp): Ruff: All checks passed. Pytest: 1 failed, 247 passed.
The failed test changed between runs (first
test_setup_repo_nodejs_project, then
test_setup_repo_with_multiple_project_types), both in
test_tools_repo_setup.py. The trace ends in selectors.py:398: Failed,
which looks like a timeout in the setup-repo tests. I did not diagnose
it. A rerun of test_setup_repo_nodejs_project on its own printed no
Failed, Timeout or Error lines.
- `uv run ruff check on both files` (api): All checks passed!
- `uv run pytest tests/api -q -p no:cacheprovider --no-cov (the scoped
command)` (api): Not green as run. The 2s per-test timeout fired on cold
imports: first run stopped after 1 failure, the second showed '207
passed, 40 errors'.
- `uv run pytest tests/api -q -p no:cacheprovider --no-cov --timeout=60`
(api): 247 passed in 52.65s. The edits are docstring and description
text only.
Part 2/7 of goal `rtk_3f7461e0031b4617af6a313e24e563cc`
- #196
- #199
- #197
- developerz-ai/claude-task-master (no PR yet)
- #198
- developerz-ai/claude-task-master (no PR yet)
<!-- dz-task:tsk_1a500a911a427cb0273167dfc07eb704 -->
---
🤖 Opened by **developerz.ai** for task
`tsk_1a500a911a427cb0273167dfc07eb704` on
developerz-ai/claude-task-master.
Raised automatically by the `raw_task_triage` lane.
<!-- dz-stack:start -->
> 🤖 developerz.ai, an automated agent, not a human — this PR is one
slice of a stacked plan.
> Dispatched automatically by the `raw_task_triage` lane
> Model `claude-sonnet-5-5` on `router.ai.developerz.ai` via `native`,
funded by `account_key`
> Ran on box `hv-dedicated-ci-0`
> Cost unknown: no list price on record for `claude-sonnet-5-5` on
`router.ai.developerz.ai`
> Run timeline
[`run_56326b2d8ea34a858a823fd4f3f8acef`](https://app.developerz.ai/fleet/runs/run_56326b2d8ea34a858a823fd4f3f8acef)
> Part 2/7 of plan
[`rtk_3f7461e0031b4617af6a313e24e563cc`](https://app.developerz.ai/fleet/plans/rtk_3f7461e0031b4617af6a313e24e563cc)
<!-- dz-stack:end -->
Co-authored-by: developerz-ai[bot] <286432749+developerz-ai[bot]@users.noreply.github.com>
## Acceptance - With all loader-mapped overrides unset, claudetm config show --env lists every CLAUDETM_MODEL_* entry from ENV_VAR_MAPPINGS, including FABLE and SONNET_1M with their correct config paths. - The CLI regression derives expected model variables from loader mappings and fails if either missing table row is removed; existing active-override and secret-masking tests pass. - ./bin/check exits successfully after the change. ## Changes - `tests/cli/test_config_commands.py` (edit) — Strengthen test_config_show_env_no_overrides: clear every ENV_VAR_MAPPINGS key, invoke config show --env with a wide test console, and assert the rendered model variable names and config paths match the loader mappings filtered by CLAUDETM_MODEL_. Replace the stale manual clearing list; the test must fail before the table fix. - `src/claude_task_master/cli_commands/config.py` (edit) — Add available-variable table rows for CLAUDETM_MODEL_FABLE → models.fable and CLAUDETM_MODEL_SONNET_1M → models.sonnet_1m, with model-name descriptions. Preserve the current no-overrides/active-overrides branches and secret masking; no loader or API changes. ## Verification `./bin/check` passed (exit 0) in 9m 09s. What the editors ran to see the change working, and what they saw: - `uv run pytest tests/cli/test_config_commands.py -q` (config-env): Before table fix: 5 failed, 27 passed. Strengthened regression reported missing CLAUDETM_MODEL_FABLE → models.fable and CLAUDETM_MODEL_SONNET_1M → models.sonnet_1m. Four unrelated TestConfigPath failures showed Rich wrapping .claude-task-master across lines. - `uv run pytest tests/cli/test_config_commands.py -q` (config-env): After table fix: 4 failed, 28 passed. Model-mapping regression, active-override tests, and secret-masking tests passed. Remaining failures: test_config_path_shows_path, test_config_path_output_is_pipeable, test_config_path_check_file_exists, test_config_path_check_file_not_exists; output contained '.claude-task\n-master/config.json'. Exit 1; full gate not run. ## Notes Premises of the request the team disproved: - (from a dropped noWork claim) None; the request is valid. Part 7/7 of goal `rtk_3f7461e0031b4617af6a313e24e563cc` - #196 - developerz-ai/claude-task-master (no PR yet) - #199 - #197 - #201 - #198 <!-- dz-task:tsk_0b39fea6c7f8a90c5e86acaaadcb2efa --> --- 🤖 Opened by **developerz.ai** for task `tsk_0b39fea6c7f8a90c5e86acaaadcb2efa` on developerz-ai/claude-task-master. Raised automatically by the `raw_task_triage` lane. <!-- dz-stack:start --> > 🤖 developerz.ai, an automated agent, not a human — this PR is one slice of a stacked plan. > Dispatched automatically by the `raw_task_triage` lane > Model `gpt-6-astra` on `router.ai.developerz.ai` via `native`, funded by `account_key` > Ran on box `hv-dedicated-dev-marshall` > Cost unknown: no list price on record for `gpt-6-astra` on `router.ai.developerz.ai` > Run timeline [`run_a22fd4369ef447b195caee2b90774cf7`](https://app.developerz.ai/fleet/runs/run_a22fd4369ef447b195caee2b90774cf7) > Part 7/7 of plan [`rtk_3f7461e0031b4617af6a313e24e563cc`](https://app.developerz.ai/fleet/plans/rtk_3f7461e0031b4617af6a313e24e563cc) <!-- dz-stack:end --> Co-authored-by: developerz-ai[bot] <286432749+developerz-ai[bot]@users.noreply.github.com>
What
The PATCH /config and POST /task/init lists in docs/api-reference.md and the
initialize_task/update_config tables in docs/mcp-tools.md had drifted from the
models: max_budget_usd and budget were documented but not accepted, while
enable_release and enable_verification were accepted but undocumented.
enable_checkpointing is stored and echoed back but no checkpointing is
implemented, so it is no longer documented as a working feature.
tests/api/test_doc_field_lists.py parses the four lists and compares them with
the models' model_fields, so the next drift fails the suite.
Acceptance
Changes
docs/api-reference.md(edit) — Make the PATCH /config Supported Options bullets (413-424) and the POST /task/init Parameters bullets (475-484) equal their pydantic models: drop max_budget_usd and budget, add enable_release + enable_verification, and stop presenting enable_checkpointing as working. Add the two missing keys to the GET /status options sample (149-160).docs/mcp-tools.md(edit) — Add enable_release and enable_verification rows to the initialize_task parameter table (287-297) and the update_config table (436-448) so both match the MCP handlers' parameters, and reword the enable_checkpointing row so it no longer reads as a working feature.tests/api/test_doc_field_lists.py(create) — New guard: parse the four documented field lists (api-reference PATCH /config + POST /task/init, mcp-tools initialize_task + update_config) and assert each documented set equals the model's model_fields (plus state_dir for the two MCP tables); on drift it fails, naming the missing and extra fields.src/claude_task_master/api/models_task.py(edit) — [docs] The REST field description and both docstrings still present the flag as working: :117 "enable_checkpointing: Whether to enable state checkpointing.", :158 description="Whether to enable state checkpointing" (the OpenAPI text every /docs client reads) and :291 "enable_checkpointing: Whether state checkpointing is enabled." No checkpointing exists in src/ (only the flag is stored; api/routes_info.py:164 reports it), so these contradict this PR's own docs/api-reference.md:425. Re-word all three to the PR's claim: accepted and stored, but has no effect because no checkpointing is [trimmed]src/claude_task_master/mcp/server_specs.py(edit) — [docs] :195 — the client-facing MCPupdate_configtool description still reads "enable_checkpointing: Whether to enable state checkpointing.", so every MCP client is told the option works while this PR's docs/mcp-tools.md:447 says it has no effect. Re-word that one line to the PR's claim (accepted and stored, but has no effect because no checkpointing is implemented). No other description line changes.src/claude_task_master/mcp/tool_handlers_control.py(edit) — [docs] :210 — theupdate_configdocstring "enable_checkpointing: Whether to enable state checkpointing." is the source text copied into mcp/server_specs.py:195; re-word it to the PR's claim (accepted and stored, but has no effect because no checkpointing is implemented). No parameter, default or behaviour changes.src/claude_task_master/cli_commands/workflow_start.py(edit) — [docs] :102 — the--checkpointinghelp "Enable file checkpointing for safe rollbacks" promises a rollback feature that does not exist (no checkpoint code in src/; the flag is only stored, workflow_start.py:256), contradicting this PR's docs/api-reference.md:425. Re-word the help to say the flag is accepted and stored but has no effect because no checkpointing is implemented. The flag and its wiring stay.src/claude_task_master/core/control_ops.py(edit) — [docs] :248 — update_config's "Supported options" list says "enable_checkpointing: bool - Whether to enable checkpointing", the same claim this PR's docs/api-reference.md:425 now contradicts. Re-word that entry to say it is accepted and stored but has no effect because no checkpointing is implemented. Leave the rest of the list and all code untouched.src/claude_task_master/core/state.py(edit) — [docs] :416 — update_options' "Supported options" list says "enable_checkpointing: bool - Whether to enable checkpointing", contradicting this PR's docs/api-reference.md:425 and docs/mcp-tools.md:447. Re-word that entry to say it is accepted and stored but has no effect because no checkpointing is implemented. No code change.Verification
./bin/checkpassed (exit 0) in 8m 23s.What the editors ran to see the change working, and what they saw:
.venv/bin/python verify_docs_links.py(docs): ✓ All 299 links verified successfully! (exit 0) - the repo's read-only markdown path/anchor check over every *.md in the treePYTHONPATH=src .venv/bin/python /tmp/check_doc_lists.py (read-only guard simulation: parses the four documented lists out of the two docs and compares them with ConfigUpdateRequest/TaskInitRequest/TaskOptionsResponse model_fields)(docs): ALL OK - api PATCH /config 11 names missing=[] extra=[]; api POST /task/init 9 names missing=[] extra=[]; mcp initialize_task 10 names (9 fields + state_dir) missing=[] extra=[]; mcp update_config 12 names (11 fields + state_dir) missing=[] extra=[]; api GET /status options sample keys=12 missing=[] extra=[]; both enable_checkpointing rows contain 'no effect' + 'no checkpointing is implemented'PYTHONPATH=src .venv/bin/python -c "print(list(ConfigUpdateRequest.model_fields), list(TaskInitRequest.model_fields), list(TaskOptionsResponse.model_fields))"(docs): ConfigUpdateRequest: ['auto_merge','enable_release','enable_verification','max_sessions','max_prs','pause_on_pr','enable_checkpointing','log_level','log_format','pr_per_task','parallel']; TaskInitRequest: ['goal','model','auto_merge','enable_release','enable_verification','max_sessions','max_prs','pause_on_pr','parallel']; TaskOptionsResponse: [...,'max_budget_usd'] (12 fields) - the authority the docs now mirroruv run pytest tests/api/test_doc_field_lists.py(guard-test): 6 passed in 2.90s — test_api_patch_config_lists_exactly_the_config_update_request_fields, test_api_task_init_lists_exactly_the_task_init_request_fields, test_mcp_initialize_task_lists_exactly_the_tool_parameters, test_mcp_update_config_lists_exactly_the_tool_parameters, test_mcp_tools_expose_the_model_fields_plus_state_dir, test_checkpointing_is_documented_as_inert — all PASSEDpython drift harness over mutated copies of docs/ in /tmp (never the repo docs): dropped/renamed enable_release and enable_verification bullets, added budget and max_budget_usd entries, dropped the state_dir row from each MCP table, reworded enable_checkpointing as working(guard-test): every mutation tripped the intended guard, e.g. 'docs/api-reference.md POST /task/init: the documented fields drifted from the model. / missing from the documentation: [enable_verification] / documented but not accepted: [enable_verification_x]' and 'docs/mcp-tools.md update_config: the documented fields drifted from the model. / missing from the documentation: [state_dir]'ruff check tests/api/test_doc_field_lists.py && ruff format --check tests/api/test_doc_field_lists.py(guard-test): 'All checks passed!' and '1 file already formatted' (ruff 0.16.1, repo config)MYPYPATH=src mypy --follow-imports=silent tests/api/test_doc_field_lists.py(guard-test): 'Success: no issues found in 1 source file'inspect.signature on the MCP tool functions vs the models (via the guard itself)(guard-test): initialize_task exposes 10 params = TaskInitRequest.model_fields (9) + state_dir; update_config exposes 12 = ConfigUpdateRequest.model_fields (11) + state_dir; work_dir is the only name the forwarding wrapper dropsuv run pytest tests/api/test_doc_field_lists.py(guard-test): 8 passed in 2.89s — all four documented lists, the GET /status options sample, the MCP tool signatures and the checkpointing wording are in agreementuv run python /tmp/guard_drift_check.py (temp copy of docs/api-reference.md, guard module imported from tests/api/test_doc_field_lists.py)(guard-test): 'missing enable_release' FAILED AS EXPECTED: missing from the documentation: ['enable_release']; 'extra max_budget_usd' FAILED AS EXPECTED: documented but not accepted: ['max_budget_usd'] — the guard fires and names missing and extra fieldsNotes
Premises of the request the team disproved:
state_dirparameter that is in neither TaskInitRequest nor ConfigUpdateRequest (mcp/tool_handlers_task.py:288, mcp/tool_handlers_control.py:191). The guard compares the MCP tables against model_fields + {state_dir}.Handoffs this run could not complete:
examples/README.md— My edit to src/claude_task_master/cli_commands/workflow_start.py replaced the --checkpointing help text 'Enable file checkpointing for safe rollbacks' with the inert wording, so this README now quotes a help string that no longer exists and still promises a rollback feature nothing implements.; examples/README.md:105-112 still advertises checkpointing as working: the heading '## Checkpointing (Experimental)', the sentence 'Enable file checkpointing for safe rollbacks:' and the code comment '# Can rollback changes if things go wrong'. It must be re-worded to say the flag is accepted and stored but has no effect because no checkpointing is implemented (drop the rollback comment), matching docs/api-reference.md:425 and docs/mcp-tools.md:447. I did not write it: this path is outside my brief. (named after the handoff rounds ran, by a repair round)examples/08-advanced-workflows.md— My edit to src/claude_task_master/cli_commands/workflow_start.py changed the --checkpointing help text, and this example still presents the flag as a working safety feature.; examples/08-advanced-workflows.md:337-344 ('### 5. Checkpointing for Safety', '# Enable checkpointing for risky changes', '# If something goes wrong, checkpoint allows rollback') still claims rollback works. It must be re-worded to say the flag is accepted and stored but has no effect because no checkpointing is implemented. I did not write it: this path is outside my brief. (named after the handoff rounds ran, by a repair round)tests/api/test_doc_field_lists.py— I re-worded the six source-facing strings that presented enable_checkpointing as working: the REST OpenAPI description and two docstrings (api/models_task.py), the MCP client-facing update_config description (mcp/server_specs.py) and its handler docstring (mcp/tool_handlers_control.py), the --checkpointing CLI help (cli_commands/workflow_start.py) and two 'Supported options' docstring entries (core/control_ops.py, core/state.py).; The existing checkpointing guards (test_checkpointing_is_documented_as_accepted_but_inert, test_status_sample_reports_checkpointing_as_inert) read only the committed Markdown, so nothing pins the source strings and a later edit can silently restore the false 'Whether to enable state checkpointing' c…(truncated)
Part 3/7 of goal
rtk_3f7461e0031b4617af6a313e24e563cc🤖 Opened by developerz.ai for task
tsk_cc817e5ea6ee03453a917d175461a64eon developerz-ai/claude-task-master.Raised automatically by the
raw_task_triagelane.