---
id: TASK-21
title: Fix extra-arg forwarding and support project.args globals
status: Done
assignee:
  - codex
created_date: '2026-02-27 17:13'
updated_date: '2026-02-27 18:43'
labels: []
dependencies: []
references:
  - src/config/schema.rs
  - src/core/config.rs
  - src/core/cmd.rs
  - docs/spec.md
  - README.md
  - docs/zync/README.md
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Switch schema to use `[project].args` as the only supported location for global phase args. Update codebase to read/merge args from `project.args` (remove `[args]` support), add validation/error for legacy `[args]`, and update docs/examples accordingly.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Schema supports global phase args only under `[project].args`; `[args]` is rejected with a clear error
- [x] #2 Config resolution merges `project.args` + profile args + CLI extras per phase in the documented order
- [x] #3 All code references updated to use `project.args` (no remaining usage of top-level `[args]`)
- [x] #4 Docs/spec/README examples updated to use `[project].args` and mention `[args]` is invalid
- [x] #5 Tests cover migration behavior (error on `[args]`) and correct arg merge order
- [x] #6 `just check` passes
<!-- AC:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Subtasks 21.1-21.3 completed: schema switched to `[project.args]` with legacy rejection, command dispatch merges config args + CLI extras per phase, docs/examples updated, and integration test added for merge order/run args.
<!-- SECTION:NOTES:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Switched global phase args schema to `[project.args]` (rejecting legacy top-level `[args]`), updated config resolution and command dispatch to use the new schema with per-phase CLI extras, and refreshed docs/examples. Added integration test for merge order + CLI run args and load test for legacy args rejection. Tests: `just check`, `just test`.
<!-- SECTION:FINAL_SUMMARY:END -->
