fix(droid-control): repair YAML frontmatter of command files#26
Merged
factory-ain3sh merged 1 commit intomasterfrom Apr 21, 2026
Merged
Conversation
The argument-hint field in demo.md, qa-test.md and verify.md was a bare value containing multiple double-quoted tokens joined by 'or', which terminates the first flow scalar and causes strict YAML parsers to fail. Wrap each value in single quotes so the whole hint is one valid scalar while preserving the human-readable double-quoted placeholders. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
factory-sagar
approved these changes
Apr 21, 2026
factory-sagar
left a comment
There was a problem hiding this comment.
LGTM — no issues found.
Verification performed
- Bug reproduction: Confirmed the original
argument-hint: "<URL>" or "<app-name>" ...failsyaml.safe_loadwithexpected <block end>, but found '<scalar>'— YAML's double-quoted flow scalar terminates at the second", leavingor "<app-name>" ...as invalid trailing content. - Fix verification: Confirmed the single-quoted wrapping parses cleanly and yields the exact intended string character-for-character in all three files.
- Scope check: Swept all 43 markdown files in the repo for broken YAML frontmatter — the three files fixed here were the only ones affected. No adjacent patterns missed.
Assessment
- Diff is strictly 3 lines across 3 files; no runtime code touched.
- Diagnosis in the PR body matches actual YAML semantics.
- Rendered
argument-hintvalue is unchanged, so downstream consumers see identical output. - Single-quote wrapping is the idiomatic YAML choice for strings containing literal double quotes.
Correct, minimal, and well-scoped fix.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The
argument-hintfield in each of the three droid-control command files (demo.md,qa-test.md,verify.md) was written as a bare YAML value containing multiple double-quoted tokens joined byor, e.g.argument-hint: "<URL>" or "<app-name>" or .... YAML parses the first"..."as a complete flow scalar, then errors on the trailing tokens, so the frontmatter was invalid for any strict YAML reader. This wraps each full value in single quotes, producing a valid single YAML string while preserving the intended literal (double-quoted placeholder tokens separated byor) that users see in the argument hint.Related Issue
N/A -- no ticket.
Potential Risk & Impact
Low risk. Change is confined to frontmatter of three command-definition markdown files; no runtime code, no exported APIs, no schema shared with other plugins. The parsed
argument-hintvalue is unchanged character-for-character from the authors' original intent -- only the outer quoting style differs, so any UI rendering the hint sees the same string.How Has This Been Tested?
YAML ERROR: expected <block end>, but found '<scalar>'on all three; after -> clean parse withargument-hintequal to the original human-readable string in every case.git diff --statconfirms the PR is a strict 3-line change across 3 files, nothing else touched.Root Cause Analysis
How the bug was traced: Ran
yaml.safe_loadon the frontmatter block extracted from each ofplugins/droid-control/commands/{demo,qa-test,verify}.md. All three raisedexpected <block end>, but found '<scalar>'pointing at the column of the second opening"inargument-hint. The root cause is the YAML flow-scalar rule: a value that starts with"terminates at the next unescaped", so"<URL>" or "<app-name>"is seen as scalar<URL>followed by invalid trailing contentor "<app-name>".How root cause drove the fix: The intended display value is a single human-readable string that happens to contain double quotes. The idiomatic YAML way to express that is a single-quoted scalar wrapping the whole thing, which lets the inner
"characters pass through verbatim. That is a one-character change per line (open and close) and keeps the rendered argument hint identical, so it fixes the parse error without altering semantics or requiring downstream consumers to change.