docs(cli): update agents validation attach synopsis to use --key value named option format #10919
Labels
Clear labels
auto/needs-reevaluation
controller-managed
overdue
auto/blocked-by-deps
auto/ci-timeout
auto/claimed-implementer
auto/claimed-merge
auto/claimed-reviewer
auto/driver-down
auto/invariant-violation
auto/last-attempt-tier-0
auto/last-attempt-tier-1
auto/last-attempt-tier-2
auto/last-attempt-tier-min
Automation Tracking
auto/needs-conflict-resolution
auto/needs-implementer
auto/postmortem
auto/ready-to-merge
auto/restart-throttled
auto/revert
auto/sentinel
auto/stale-inactivity
auto/unstable
Blocked
Needs Feedback
Signed-off: Owner
Signed-off: Scrum Master
Signed-off: Tech Lead
Spike
Controller deferred this PR; awaiting Phase 6+ scope-evaluator or operator re-enablement.
Auto-agents controller manages this PR/issue (see tools/controller/deploy/RUNBOOK.md). Remove this label to abandon controller management.
PR blocked by an open issue dependency. Operator must close the dep (or remove the dependency link) before the merge driver can act. Auto-cleared by merge_drive when no open deps remain.
Most recent merge cycle hit CI timeout. Driver excludes this PR while last merge_cycle row is < 30 min old; label persists thereafter as visible history.
Currently being processed by an implementer worker.
Currently being processed by the merge driver.
Currently being processed by a reviewer worker.
Merge driver heartbeat stale; pipeline halted. Closed automatically on next clean tick.
Detected master commit violating the strict merge invariant. Tracked as an issue (not a PR label); kept here for label completeness.
In-cycle escalation: most recent attempt ran at the Tier 0 slot (`tier-0`). Slot's model defined in .opencode/models/tiers.yaml.
In-cycle escalation: most recent attempt ran at the Tier 1 slot (`tier-1`). Slot's model defined in .opencode/models/tiers.yaml.
In-cycle escalation: most recent attempt ran at the Tier 2 slot (`tier-2`). Slot's model defined in .opencode/models/tiers.yaml. Gated behind IMPLEMENTER_ESCALATION_TIER2_ENABLED.
In-cycle escalation: most recent attempt ran at the Tier -1 slot (`tier-min`). Slot's model defined in .opencode/models/tiers.yaml. Suffix is ``-min`` (not ``--1``) so the Forgejo UI reads naturally.
Tracking issues used by the AI Automation system for agents to communicate and report.
Rebase conflict needs LLM conflict-resolver.
Failing CI needs implementer attention.
Documenting a driver incident or rollback.
Reviewer has APPROVED this PR and no later REQUEST_CHANGES is outstanding. The merge driver requires this label to even consider a PR for merging. Set by the reviewer worker on APPROVE; cleared on REQUEST_CHANGES.
Train repeatedly lost master-tempo races. Driver excludes via merge_cycle until cooldown elapses; label persists as visible history.
Revert PR backing out an invariant violation. Fast-tracked through the merge driver.
Sentinel PR duplicated from upstream into a personal fork by tools/duplicate_prs_to_fork.py for pipeline testing. Lives only in the fork; the canonical pipeline never sees it.
No implementer activity for N days. Flagged for human review. Auto-cleared on next push to head branch.
Repeatedly fails on current master (>= 3 ci-fail-on-rebased-sha releases in 12 h). Excluded from driver until human triage.
A ticket in a blocked state and unable to complete until some other task is completed first.
Bounty
$100
A bounty of $100 for any open-source contributor who provides a MR that solves this issue
Bounty
$1000
A bounty of $1000 for any open-source contributor who provides a MR that solves this issue
Bounty
$10000
A bounty of $10000 for any open-source contributor who provides a MR that solves this issue
Bounty
$20
A bounty of $20 for any open-source contributor who provides a MR that solves this issue
Bounty
$2000
A bounty of $2000 for any open-source contributor who provides a MR that solves this issue
Bounty
$250
A bounty of $250 for any open-source contributor who provides a MR that solves this issue
Bounty
$50
A bounty of $50 for any open-source contributor who provides a MR that solves this issue
Bounty
$500
A bounty of $500 for any open-source contributor who provides a MR that solves this issue
Bounty
$5000
A bounty of $5000 for any open-source contributor who provides a MR that solves this issue
Bounty
$750
A bounty of $750 for any open-source contributor who provides a MR that solves this issue
MoSCoW
Could have
Could have feature in order to satisfy the epic/legendary.
MoSCoW
Must have
Must have feature in order to satisfy the epic/legendary.
MoSCoW
Should have
Should have feature in order to satisfy the epic/legendary.
There are questions in the ticket that can not be completed until the project owner provides clarity.
Points
1
1 man-hours worth of work for an expert with no learning curve.
Points
13
13 man-hours worth of work for an expert with no learning curve.
Points
2
2 man-hours worth of work for an expert with no learning curve.
Points
21
21 man-hours worth of work for an expert with no learning curve.
Points
3
3 man-hours worth of work for an expert with no learning curve.
Points
34
34 man-hours worth of work for an expert with no learning curve.
Points
5
5 man-hours worth of work for an expert with no learning curve.
Points
55
55 man-hours worth of work for an expert with no learning curve.
Points
8
8 man-hours worth of work for an expert with no learning curve.
Points
88
88 man-hours worth of work for an expert with no learning curve.
Priority
Backlog
This ticket has backlogged priority and is not to be worked on yet
Priority
CI Blocker
Critical priority issue that blocks CI/CD pipeline and prevents PR merges
Priority
Critical
The priority is critical
Priority
High
The priority is high
Priority
Low
The priority is low
Priority
Medium
The priority is medium
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
A ticket for learning a tool or technology that is needed to be able to do future planning and design.
State
Completed
The ticket has been fully implemented, completed, and merged with the source code. This label should only be applied once a ticket is closed.
State
Duplicate
A ticket that represents the same content as an existing ticket.
State
In Progress
A ticket that is actively being developed.
State
In Review
A ticket that has had some code completed to implement but is waiting to pass peer review and is not yet merged in.
State
Paused
This ticket's work started but wasn't finished. It's on hold (likely in a feature branch) and will be resumed later, either due to a blocker or a delay.
State
Unverified
All new tickets start in this state. A developer may set it to show the ticket is unverified. This means we haven't agreed to work on it. It will either move to a verified state or be closed as wontdo.
State
Verified
The issue has been verified by a developer as legitimate. It will be worked on and verified tickets are now considered part of the backlog.
State
Wont Do
This ticket has been decided it wont be done. This may mean the bug has been determined to not be real (cant verify) or the feature is one we have decided we dont want to adopt.
Type
Automation
Any edits or discussion about the AI automated coding system.
Type
Bug
Something that doesnt work as intended.
Type
Discussion
Anytime a ticket represents a discussion about a subject and doesnt fall into one of the other categories.
Type
Documentation
An error or improvement needed in the documentation.
Type
Epic
Any first tier epic. That is, an epic which contains only issues as children and will not have sub-epics.
Type
Feature
Some new functionality not present.
Type
Legendary
A type of Epic which will contain other Epics.
Type
Refactor
A code change that restructures existing code without changing its external behavior.
Type
Support
Someone needs help using the project.
Type
Task
A generic task that doesnt fit into the other type categories.
Type
Testing
Work exclusively focusing on fixing or expanding testing.
No Label
Projects
Clear projects
No project
Assignees
aditya (Aditya Chhabra)
aleenaumair (Aleena Umair)
brent.edwards (Brent Edwards)
CoreRasurae (Luis Mendes)
drew (Drew Morris)
eugen.thaci (Eugen Thaci)
freemo (Jeffrey Phillips Freeman)
HAL9000 (HAL 9000)
HAL9001 (HAL9001)
hamza.khyari (Hamza Khyari)
hurui200320 (Rui Hu)
justin.morris
khird (Kyle Hird)
org.cleveragents
Clear assignees
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: cleveragents/cleveragents-core#10919
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Delete Branch "feature/issue-4747-agents-validation-attach-synopsis-clarify-key-value"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Updates
docs/specification.mdto clarify thatagents validation attachextra arguments use--key valuenamed option format (not the ambiguous positional[<ARGS>...]format).Changes
[<ARGS>...]→[--<KEY> <VALUE>]...agents validation attach~line 9650): Updated[<ARGS>...]→[--<KEY> <VALUE>]...<ARGS>...description with full explanation of--key valueformat, hyphen-to-underscore conversion, and rejection of positionalkey=valueformat[args...]→[--<KEY> <VALUE>]...Rationale
PR #3837 changed the implementation to enforce
--key valuenamed option format. The spec examples were already correct (using--coverage-threshold 90), but the synopsis and argument description still showed the ambiguous[<ARGS>...]placeholder. This PR aligns the spec with the implementation.Closes #4747
This PR blocks issue #4747
Automated by CleverAgents Bot
Supervisor: Implementation | Agent: task-implementor
Review Summary
This PR is titled "docs(cli): update agents validation attach synopsis to use --key value named option format" and claims to touch 1 file, but the diff between master and the PR head commit reveals 7 changed files across 6+ unrelated concerns. The PR description only documents the
docs/specification.mdchanges.Issues Found
BLOCKER 1: PR not atomic — 6+ unrelated concerns in one commit
The diff reveals the following changes bundled into a single commit:
docs/specification.md— synopsis/argument description updates (the stated purpose)CHANGELOG.md— removal of PR #10714 changelog entrydocs/timeline.md— bulk removal of all Day-99 timeline entries.devcontainer/opencode.json— replacing context/output limits withtoolsflag for 3 models.forgejo/workflows/ci.yml— reverting PR #10714 by removingunit_testsfrom coverage jobneedsfeatures/tdd_gemini_fallback_order_4750.feature— deletionfeatures/steps/tdd_gemini_fallback_order_4750_steps.py— deletionPer contributing guidelines, each PR must be atomic (one logical change only). This PR should be split into separate PRs for each concern.
BLOCKER 2: CI change is destructive
The
ci.ymlchange removesunit_testsfrom thecoveragejob’sneedslist, reverts the quality gate from PR #10714, and allows the coverage job to run in parallel with unit tests. Per contributing guidelines, the coverage job ≥97% is a hard merge gate, and running it while tests are still in-flight produces misleading pass results. This is a destructive regression.BLOCKER 3: CHANGELOG.md entry removed without justification
A changelog entry describing the CI coverage guard (PR #10714) is removed, but no new entry explains why it’s being removed. Contributing guidelines require one changelog entry per commit, per PR. No changelog entry is found for any of the changes made.
BLOCKER 4: TDD test deletion
features/tdd_gemini_fallback_order_4750.featureand its step definitions are deleted. Issue #4750 / TDD Issue #10896 (ProviderType.GEMINI missing from fallback order) — was it resolved? If so, this should be documented. If not, removing the TDD capture test means the bug will be untracked. TDD capture tests should not disappear without clear explanation.BLOCKER 5: No Type/ label
There are zero labels on this PR. Contributing guidelines require exactly one Type/ label (Type/Bug, Type/Feature, Type/Task, etc.).
BLOCKER 6: No PR labels at all
The PR has no Priority/ label either (priority_rank is 6 = unlabelled). Contributing guidelines require proper label assignment.
Docs/specification.md changes (the stated purpose)
Evaluating the actual spec changes on their own merit:
[<ARGS>...]→[--<KEY> <VALUE>]...is correct and aligns with implementation (PR #3837)--key valueformat, hyphen-to-underscore conversion, and rejection of positionalkey=valueIf this PR were split to contain only the
docs/specification.mdchanges, the documentation itself would be acceptable.CI Status
All 14 CI checks are passing on the head commit, including lint, typecheck, security, unit_tests, and coverage. However, CI passing does not validate atomicity, changelog completeness, or dependency direction correctness.
Recommendations
docs/specification.mdchanges, one forCHANGELOG.mdchanges, one forci.ymlchanges, one fordevcontainerchanges, and one for TDD test cleanupdocs/specification.mdPR should useCloses #4747with the proper Forgejo dependency direction (PR blocks issue)unit_testsfrom coverageneeds) needs a separate, justified PRBLOCKER: Context/output limits replaced with
toolsflag for 3 models. This is a separate infrastructure concern from the spec change and should be in its own PR.BLOCKER: This removes
unit_testsfrom the coverage job’sneedslist, reverting the quality gate from PR #10714. Withoutunit_testsinneeds, the coverage job runs in parallel with unit tests, producing misleading pass results. All 5 required CI gates (lint, typecheck, security, unit_tests, coverage) must pass before merge — this change undermines that gate. If the intent is to remove this guard, submit a separate, justified PR.BLOCKER: A changelog entry for PR #10714 is removed. Contributing guidelines require one changelog entry per commit describing the change. No replacement entry is provided. What change is replacing the CI coverage guard? This needs documentation.
BLOCKER: Bulk removal of Day 99 timeline entries. This is a separate concern from the spec synopsis change. Timeline updates should be in their own PR.
BLOCKER: TDD capture test deleted. Issue #4750 has TDD Issue #10896, which is the first step in the bug-fix TDD workflow (prove bug exists, then fix it). Is #4750 resolved? If so, why was the fix not included here? If not, deleting the TDD test means the bug will be untracked.
Review of PR #10919:
docs(cli): update agents validation attach synopsis to use --key value named option formatOverview
This PR updates
docs/specification.mdto align theagents validation attachcommand synopsis and argument descriptions with the actual implementation (PR #3837), which uses--key valuenamed options instead of positional<ARGS>....Previous Feedback (from prior review)
The prior REQUEST_CHANGES review was based on an earlier commit (
9888c2f) that bundled 6+ unrelated changes. That commit was not the final PR head. The diff for this final commit (43e883ea) is clean and isolated — onlydocs/specification.mdis changed (10 additions, 10 deletions). The prior concerns about atomicity, CI revert, CHANGELOG removal, and TDD test deletion do not apply to this final commit.10-Category Evaluation
CORRECTNESS: The changes are 100% correct. The implementation (PR #3837) enforces
--key valuenamed option format with hyphen-to-underscore conversion. All 8 inline references across synopsis, argument description, inline examples, and the validation management table are consistently updated.SPECIFICATION ALIGNMENT: This PR is updating the spec to match the implementation. Per contributing guidelines, when the implementation is clearer than the spec, the spec should follow the implementation. This is explicitly an "implementation-is-better" case documented in issue #4747.
TEST QUALITY: This is a documentation-only PR — no code changes, no test impact. The underlying implementation was already tested in PR #3837. No Behave scenarios needed.
TYPE SAFETY: N/A — no Python code changes.
READABILITY: The new
[--<KEY> <VALUE>]...syntax is clearer than the ambiguous<ARGS>.... The argument description now explicitly explains the--key valueformat, hyphen-to-underscore conversion, and rejection of positionalkey=value. Well written.PERFORMANCE: N/A — documentation change only.
SECURITY: N/A — documentation change only.
CODE STYLE: N/A — documentation change only.
DOCUMENTATION: Properly updated across all relevant sections of
docs/specification.md: global synopsis (~line 271), attach section synopsis (~line 9650), argument description (~line 9663), inline attachment descriptions (~lines 9381-9383), attachment model section (~lines 22679-22699), and validation management table (~line 23129). All 8 occurrences are consistently updated.COMMIT AND PR QUALITY:
docs(cli): ...ISSUES CLOSED: #4747Closes #4747Type/Task— the PR should ideally mirror this. Also no Priority/ label; issue hasPriority/Mediumwithpriority_rank: 6(unlabelled in PR context).CI Status
All 14 CI checks passing (lint, typecheck, security, unit_tests, coverage, integration_tests, e2e_tests, etc.).
Verdict: APPROVED
The spec changes are correct, consistent, and well-scoped. The documentation accurately reflects the implementation behavior. The atomic commit is clean.
Minor Suggestions:
Type/Taskmatching the linked issue).Automated by CleverAgents Bot
Supervisor: PR Review | Agent: pr-review-worker
43e883ea98to0ade2526eb