Skip to content

fix(droid-control): repair YAML frontmatter of command files#26

Merged
factory-ain3sh merged 1 commit intomasterfrom
fix/droid-control-command-frontmatter
Apr 21, 2026
Merged

fix(droid-control): repair YAML frontmatter of command files#26
factory-ain3sh merged 1 commit intomasterfrom
fix/droid-control-command-frontmatter

Conversation

@factory-ain3sh
Copy link
Copy Markdown
Contributor

Description

The argument-hint field 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 by or, 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 by or) 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-hint value 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?

  • Parsed each file's frontmatter with PyYAML before and after the change: before -> YAML ERROR: expected <block end>, but found '<scalar>' on all three; after -> clean parse with argument-hint equal to the original human-readable string in every case.
  • git diff --stat confirms 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_load on the frontmatter block extracted from each of plugins/droid-control/commands/{demo,qa-test,verify}.md. All three raised expected <block end>, but found '<scalar>' pointing at the column of the second opening " in argument-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 content or "<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.

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-ain3sh factory-ain3sh self-assigned this Apr 21, 2026
@factory-ain3sh factory-ain3sh added the bug Something isn't working label Apr 21, 2026
Copy link
Copy Markdown

@factory-sagar factory-sagar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — no issues found.

Verification performed

  • Bug reproduction: Confirmed the original argument-hint: "<URL>" or "<app-name>" ... fails yaml.safe_load with expected <block end>, but found '<scalar>' — YAML's double-quoted flow scalar terminates at the second ", leaving or "<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-hint value 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.

@factory-ain3sh factory-ain3sh merged commit 3db2a62 into master Apr 21, 2026
1 check passed
@factory-ain3sh factory-ain3sh deleted the fix/droid-control-command-frontmatter branch April 21, 2026 18:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants