qa/README.html at main · HelixDevelopment/qa · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
  <title>README</title>
  <style>
    /* Default styles provided by pandoc.
    ** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
    */
    html {
      color: #1a1a1a;
      background-color: #fdfdfd;
    }
    body {
      margin: 0 auto;
      max-width: 36em;
      padding-left: 50px;
      padding-right: 50px;
      padding-top: 50px;
      padding-bottom: 50px;
      hyphens: auto;
      overflow-wrap: break-word;
      text-rendering: optimizeLegibility;
      font-kerning: normal;
    }
    @media (max-width: 600px) {
      body {
        font-size: 0.9em;
        padding: 12px;
      }
      h1 {
        font-size: 1.8em;
      }
    }
    @media print {
      html {
        background-color: white;
      }
      body {
        background-color: transparent;
        color: black;
        font-size: 12pt;
      }
      p, h2, h3 {
        orphans: 3;
        widows: 3;
      }
      h2, h3, h4 {
        page-break-after: avoid;
      }
    }
    p {
      margin: 1em 0;
    }
    a {
      color: #1a1a1a;
    }
    a:visited {
      color: #1a1a1a;
    }
    img {
      max-width: 100%;
    }
    svg {
      height: auto;
      max-width: 100%;
    }
    h1, h2, h3, h4, h5, h6 {
      margin-top: 1.4em;
    }
    h5, h6 {
      font-size: 1em;
      font-style: italic;
    }
    h6 {
      font-weight: normal;
    }
    ol, ul {
      padding-left: 1.7em;
      margin-top: 1em;
    }
    li > ol, li > ul {
      margin-top: 0;
    }
    blockquote {
      margin: 1em 0 1em 1.7em;
      padding-left: 1em;
      border-left: 2px solid #e6e6e6;
      color: #606060;
    }
    code {
      white-space: pre-wrap;
      font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
      font-size: 85%;
      margin: 0;
      hyphens: manual;
    }
    pre {
      margin: 1em 0;
      overflow: auto;
    }
    pre code {
      padding: 0;
      overflow: visible;
      overflow-wrap: normal;
    }
    .sourceCode {
     background-color: transparent;
     overflow: visible;
    }
    hr {
      border: none;
      border-top: 1px solid #1a1a1a;
      height: 1px;
      margin: 1em 0;
    }
    table {
      margin: 1em 0;
      border-collapse: collapse;
      width: 100%;
      overflow-x: auto;
      display: block;
      font-variant-numeric: lining-nums tabular-nums;
    }
    table caption {
      margin-bottom: 0.75em;
    }
    tbody {
      margin-top: 0.5em;
      border-top: 1px solid #1a1a1a;
      border-bottom: 1px solid #1a1a1a;
    }
    th {
      border-top: 1px solid #1a1a1a;
      padding: 0.25em 0.5em 0.25em 0.5em;
    }
    td {
      padding: 0.125em 0.5em 0.25em 0.5em;
    }
    header {
      margin-bottom: 4em;
      text-align: center;
    }
    #TOC li {
      list-style: none;
    }
    #TOC ul {
      padding-left: 1.3em;
    }
    #TOC > ul {
      padding-left: 0;
    }
    #TOC a:not(:hover) {
      text-decoration: none;
    }
    span.smallcaps{font-variant: small-caps;}
    div.columns{display: flex; gap: min(4vw, 1.5em);}
    div.column{flex: auto; overflow-x: auto;}
    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
    /* The extra [class] is a hack that increases specificity enough to
       override a similar rule in reveal.js */
    ul.task-list[class]{list-style: none;}
    ul.task-list li input[type="checkbox"] {
      font-size: inherit;
      width: 0.8em;
      margin: 0 0.8em 0.2em -1.6em;
      vertical-align: middle;
    }
    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
    /* CSS for syntax highlighting */
    html { -webkit-text-size-adjust: 100%; }
    pre > code.sourceCode { white-space: pre; position: relative; }
    pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
    pre > code.sourceCode > span:empty { height: 1.2em; }
    .sourceCode { overflow: visible; }
    code.sourceCode > span { color: inherit; text-decoration: inherit; }
    div.sourceCode { margin: 1em 0; }
    pre.sourceCode { margin: 0; }
    @media screen {
    div.sourceCode { overflow: auto; }
    }
    @media print {
    pre > code.sourceCode { white-space: pre-wrap; }
    pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
    }
    pre.numberSource code
      { counter-reset: source-line 0; }
    pre.numberSource code > span
      { position: relative; left: -4em; counter-increment: source-line; }
    pre.numberSource code > span > a:first-child::before
      { content: counter(source-line);
        position: relative; left: -1em; text-align: right; vertical-align: baseline;
        border: none; display: inline-block;
        -webkit-touch-callout: none; -webkit-user-select: none;
        -khtml-user-select: none; -moz-user-select: none;
        -ms-user-select: none; user-select: none;
        padding: 0 4px; width: 4em;
        color: #aaaaaa;
      }
    pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
    div.sourceCode
      {   }
    @media screen {
    pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
    }
    code span.al { color: #ff0000; font-weight: bold; } /* Alert */
    code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
    code span.at { color: #7d9029; } /* Attribute */
    code span.bn { color: #40a070; } /* BaseN */
    code span.bu { color: #008000; } /* BuiltIn */
    code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
    code span.ch { color: #4070a0; } /* Char */
    code span.cn { color: #880000; } /* Constant */
    code span.co { color: #60a0b0; font-style: italic; } /* Comment */
    code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
    code span.do { color: #ba2121; font-style: italic; } /* Documentation */
    code span.dt { color: #902000; } /* DataType */
    code span.dv { color: #40a070; } /* DecVal */
    code span.er { color: #ff0000; font-weight: bold; } /* Error */
    code span.ex { } /* Extension */
    code span.fl { color: #40a070; } /* Float */
    code span.fu { color: #06287e; } /* Function */
    code span.im { color: #008000; font-weight: bold; } /* Import */
    code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
    code span.kw { color: #007020; font-weight: bold; } /* Keyword */
    code span.op { color: #666666; } /* Operator */
    code span.ot { color: #007020; } /* Other */
    code span.pp { color: #bc7a00; } /* Preprocessor */
    code span.sc { color: #4070a0; } /* SpecialChar */
    code span.ss { color: #bb6688; } /* SpecialString */
    code span.st { color: #4070a0; } /* String */
    code span.va { color: #19177c; } /* Variable */
    code span.vs { color: #4070a0; } /* VerbatimString */
    code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
  </style>
</head>
<body>
<header id="title-block-header">
<h1 class="title">README</h1>
</header>
<h1 id="helixqa">HelixQA</h1>
<blockquote>
<p><strong>Status banner (round 219, 2026-05-19).</strong> Governance
baseline: constitution submodule §11.4 covenant; CONST-035 anti-bluff;
CONST-048 full-automation coverage; CONST-050 no-fakes + 100%-test-type
coverage (15-row matrix in <a
href="docs/test-coverage.md"><code>docs/test-coverage.md</code></a>);
CONST-051 submodules-as-equal-codebase + decoupling; CONST-054
dependency manifest (<a
href="helix-deps.yaml"><code>helix-deps.yaml</code></a>); CONST-061
pre-force-push merge-first; CONST-062 + CONST-063 documentation
always-sync. i18n migration rounds 112 / 205 / 214 landed (25
user-facing strings now LLM-/resource-loaded per CONST-046). New this
round: <a
href="challenges/scripts/helixqa_orchestrator_challenge.sh"><code>challenges/scripts/helixqa_orchestrator_challenge.sh</code></a>
— 8-phase orchestrator-surface validator with built-in §1.1 paired
mutation.</p>
</blockquote>
<h2 id="what-this-submodule-is">What this submodule is</h2>
<p>HelixQA is an <strong>anti-bluff QA orchestration framework</strong>
for cross-platform testing with real-time crash detection, step
validation, evidence collection, and automated ticket generation.</p>
<p>Built on <a href="../challenges">digital.vasic.challenges</a> and <a
href="../containers">digital.vasic.containers</a> — both incorporated at
the parent project’s root per CONST-051(C) (nested own-org submodule
chains forbidden; this submodule MUST NOT introduce its own
<code>.gitmodules</code> entries for those repos).</p>
<p>The orchestrator’s design centre is the §11.4 Operative Rule:
<strong>the bar for shipping is not “tests pass” but “users can use the
feature.”</strong> Every PASS HelixQA emits MUST carry positive runtime
evidence captured during execution. A green summary line without that
evidence is a critical defect of equal severity to a missing
feature.</p>
<h2 id="features">Features</h2>
<ul>
<li><strong>Cross-platform testing</strong>: Android, Android TV, Web,
and Desktop</li>
<li><strong>Android TV Channels testing</strong>: Automatic detection
and comprehensive testing of Android TV Home Screen Channels (default
channel, category channels, Watch Next row, deep links)</li>
<li><strong>Real-time crash detection</strong>: ADB-based Android
crash/ANR detection, browser and JVM process monitoring</li>
<li><strong>Step-by-step validation</strong>: Evidence collection at
each test step to prevent false positives</li>
<li><strong>YAML test banks</strong>: QA-specific test case definitions
with platform targeting, priority, and documentation references</li>
<li><strong>Evidence collection</strong>: Screenshots, logcat, video
recording, stack traces — all centralized</li>
<li><strong>Markdown ticket generation</strong>: Auto-generated issue
tickets with full evidence for AI fix pipelines</li>
<li><strong>Multiple report formats</strong>: Markdown, HTML, JSON</li>
<li><strong>Speed modes</strong>: Slow (debugging), Normal, Fast
(CI)</li>
<li><strong>Composable architecture</strong>: Reuses Challenges
framework for test execution and reporting</li>
</ul>
<h2 id="prerequisites">Prerequisites</h2>
<ul>
<li>Go 1.24+</li>
<li>Sibling directories:
<ul>
<li><code>../challenges</code> (digital.vasic.challenges)</li>
<li><code>../containers</code> (digital.vasic.containers)</li>
</ul></li>
</ul>
<h2 id="installation">Installation</h2>
<div class="sourceCode" id="cb1"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> install digital.vasic.helixqa/cmd/helixqa@latest</span></code></pre></div>
<p>Or build from source:</p>
<div class="sourceCode" id="cb2"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span> build</span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="co"># Binary at bin/helixqa</span></span></code></pre></div>
<h2 id="usage">Usage</h2>
<div class="sourceCode" id="cb3"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="co"># Run QA pipeline</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="ex">helixqa</span> run <span class="at">--banks</span> tests/banks/ <span class="at">--platform</span> all</span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="co"># Android-specific with device</span></span>
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a><span class="ex">helixqa</span> run <span class="at">--banks</span> tests/ <span class="at">--platform</span> android <span class="dt">\</span></span>
<span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a>  <span class="at">--device</span> emulator-5554 <span class="dt">\</span></span>
<span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a>  <span class="at">--package</span> com.example.app</span>
<span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a><span class="co"># List test cases from banks</span></span>
<span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a><span class="ex">helixqa</span> list <span class="at">--banks</span> tests/banks/ <span class="at">--platform</span> android</span>
<span id="cb3-11"><a href="#cb3-11" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb3-12"><a href="#cb3-12" aria-hidden="true" tabindex="-1"></a><span class="co"># Generate report from existing results</span></span>
<span id="cb3-13"><a href="#cb3-13" aria-hidden="true" tabindex="-1"></a><span class="ex">helixqa</span> report <span class="at">--input</span> qa-results <span class="at">--format</span> html</span>
<span id="cb3-14"><a href="#cb3-14" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb3-15"><a href="#cb3-15" aria-hidden="true" tabindex="-1"></a><span class="co"># Version info</span></span>
<span id="cb3-16"><a href="#cb3-16" aria-hidden="true" tabindex="-1"></a><span class="ex">helixqa</span> version</span></code></pre></div>
<h2 id="test-bank-format-yaml">Test Bank Format (YAML)</h2>
<div class="sourceCode" id="cb4"><pre
class="sourceCode yaml"><code class="sourceCode yaml"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="fu">version</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;1.0&quot;</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="fu">name</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Sample Core Tests&quot;</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="fu">test_cases</span><span class="kw">:</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="at">  </span><span class="kw">-</span><span class="at"> </span><span class="fu">id</span><span class="kw">:</span><span class="at"> TC-001</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="at">    </span><span class="fu">name</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Create new document&quot;</span></span>
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a><span class="at">    </span><span class="fu">category</span><span class="kw">:</span><span class="at"> functional</span></span>
<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a><span class="at">    </span><span class="fu">priority</span><span class="kw">:</span><span class="at"> critical</span></span>
<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a><span class="at">    </span><span class="fu">platforms</span><span class="kw">:</span><span class="at"> </span><span class="kw">[</span><span class="at">android</span><span class="kw">,</span><span class="at"> web</span><span class="kw">,</span><span class="at"> desktop</span><span class="kw">]</span></span>
<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a><span class="at">    </span><span class="fu">steps</span><span class="kw">:</span></span>
<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a><span class="at">      </span><span class="kw">-</span><span class="at"> </span><span class="fu">name</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Open app&quot;</span></span>
<span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a><span class="at">        </span><span class="fu">action</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Launch application&quot;</span></span>
<span id="cb4-12"><a href="#cb4-12" aria-hidden="true" tabindex="-1"></a><span class="at">        </span><span class="fu">expected</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;Main editor screen visible&quot;</span></span>
<span id="cb4-13"><a href="#cb4-13" aria-hidden="true" tabindex="-1"></a><span class="at">    </span><span class="fu">tags</span><span class="kw">:</span><span class="at"> </span><span class="kw">[</span><span class="at">core</span><span class="kw">,</span><span class="at"> smoke</span><span class="kw">]</span></span>
<span id="cb4-14"><a href="#cb4-14" aria-hidden="true" tabindex="-1"></a><span class="at">    </span><span class="fu">documentation_refs</span><span class="kw">:</span></span>
<span id="cb4-15"><a href="#cb4-15" aria-hidden="true" tabindex="-1"></a><span class="at">      </span><span class="kw">-</span><span class="at"> </span><span class="fu">type</span><span class="kw">:</span><span class="at"> user_guide</span></span>
<span id="cb4-16"><a href="#cb4-16" aria-hidden="true" tabindex="-1"></a><span class="at">        </span><span class="fu">section</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;3.1&quot;</span></span>
<span id="cb4-17"><a href="#cb4-17" aria-hidden="true" tabindex="-1"></a><span class="at">        </span><span class="fu">path</span><span class="kw">:</span><span class="at"> </span><span class="st">&quot;docs/USER_MANUAL.md&quot;</span></span></code></pre></div>
<h2 id="architecture">Architecture</h2>
<pre><code>cmd/helixqa/          CLI entry point (subcommands: run, list, report, autonomous, version)
pkg/
  config/             Configuration types and validation
  testbank/           YAML test bank management with platform/priority filtering
  detector/           Platform-specific crash/ANR detection
    android.go        ADB-based detection (pidof, logcat, screencap)
    web.go            Browser process monitoring (pgrep)
    desktop.go        JVM/process monitoring (pgrep, kill)
  validator/          Step-by-step validation with evidence
  evidence/           Centralized evidence collection (screenshots, video, logs)
  ticket/             Markdown ticket generation for AI fix pipelines
  reporter/           QA report generation (reuses challenges/pkg/report)
  orchestrator/       Main QA pipeline coordinator
  autonomous/         SessionCoordinator, PlatformWorker, PhaseManager
  navigator/          NavigationEngine, ActionExecutor (ADB, Playwright, X11)
  issuedetector/      LLM-powered bug detection (visual, UX, accessibility, functional)
  planning/           Test plan generation with platform-specific test cases
    androidtv_channels_framework.go  Generic Android TV Channels testing framework
  session/            SessionRecorder, Timeline, VideoManager</code></pre>
<p>See <a href="ARCHITECTURE.md">ARCHITECTURE.md</a> and <a
href="API_REFERENCE.md">API_REFERENCE.md</a> for details.</p>
<h2 id="autonomous-qa-session">Autonomous QA Session</h2>
<p>HelixQA includes an <strong>Autonomous QA Session</strong> mode that
uses LLM-powered agents and computer vision to autonomously navigate
applications, verify documented features, discover bugs, and generate
comprehensive QA reports with video evidence.</p>
<h3 id="what-it-does">What It Does</h3>
<p>The autonomous session runs in 4 phases:</p>
<ol type="1">
<li><strong>Setup</strong> – Select LLMs via LLMsVerifier, build a
feature map from project docs via DocProcessor, spawn CLI agents via
LLMOrchestrator, and initialize VisionEngine.</li>
<li><strong>Doc-Driven Verification</strong> – Platform workers verify
every documented feature against the running app, capturing screenshots
and video evidence at each step.</li>
<li><strong>Curiosity-Driven Exploration</strong> – Workers explore
undiscovered areas of the app, testing edge cases, empty inputs, rapid
interactions, and undocumented behaviors.</li>
<li><strong>Report &amp; Cleanup</strong> – Aggregate coverage, tickets,
and navigation maps into a QA report (Markdown, HTML, JSON) with linked
video timestamps.</li>
</ol>
<h3 id="new-packages">New Packages</h3>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th>Package</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>pkg/autonomous</code></td>
<td>SessionCoordinator, PlatformWorker, PhaseManager</td>
</tr>
<tr>
<td><code>pkg/navigator</code></td>
<td>NavigationEngine with platform-specific ActionExecutors (ADB,
Playwright, X11)</td>
</tr>
<tr>
<td><code>pkg/issuedetector</code></td>
<td>LLM-powered bug detection across visual, UX, accessibility, and
functional categories</td>
</tr>
<tr>
<td><code>pkg/session</code></td>
<td>SessionRecorder with video management and timeline event
tracking</td>
</tr>
</tbody>
</table>
<h3 id="external-modules">External Modules</h3>
<p>The autonomous session integrates 4 external Go modules (consumed as
Git submodules):</p>
<table>
<colgroup>
<col style="width: 47%" />
<col style="width: 52%" />
</colgroup>
<thead>
<tr>
<th>Module</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td>LLMsVerifier</td>
<td>Strategy-based LLM selection and scoring</td>
</tr>
<tr>
<td>LLMOrchestrator</td>
<td>Headless CLI agent management (opencode, claude-code, gemini, junie,
qwen-code)</td>
</tr>
<tr>
<td>VisionEngine</td>
<td>GoCV mechanical vision + LLM Vision API analysis</td>
</tr>
<tr>
<td>DocProcessor</td>
<td>Documentation loading, feature map building, coverage tracking</td>
</tr>
</tbody>
</table>
<h3 id="cli-subcommand">CLI Subcommand</h3>
<div class="sourceCode" id="cb6"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="ex">helixqa</span> autonomous <span class="at">--project</span> /path/to/your-project <span class="dt">\</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a>  <span class="at">--platforms</span> android,desktop,web <span class="dt">\</span></span>
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>  <span class="at">--env</span> .env <span class="dt">\</span></span>
<span id="cb6-4"><a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>  <span class="at">--timeout</span> 2h <span class="dt">\</span></span>
<span id="cb6-5"><a href="#cb6-5" aria-hidden="true" tabindex="-1"></a>  <span class="at">--coverage-target</span> 0.9 <span class="dt">\</span></span>
<span id="cb6-6"><a href="#cb6-6" aria-hidden="true" tabindex="-1"></a>  <span class="at">--output</span> qa-results/ <span class="dt">\</span></span>
<span id="cb6-7"><a href="#cb6-7" aria-hidden="true" tabindex="-1"></a>  <span class="at">--report</span> markdown,html,json</span></code></pre></div>
<h3 id="configuration">Configuration</h3>
<p>All settings are managed via a <code>.env</code> file. Copy
<code>.env.example</code> to <code>.env</code> and fill in your API keys
and platform-specific paths. Key configuration groups:</p>
<ul>
<li><strong>Master switch</strong>: Enable/disable, platform selection,
timeout, coverage target</li>
<li><strong>LLMsVerifier</strong>: Strategy, score thresholds,
caching</li>
<li><strong>API keys</strong>: OpenAI, Anthropic, Google, Groq, Mistral,
DeepSeek, xAI, Together, Qwen, Junie</li>
<li><strong>CLI agents</strong>: Enabled agents, binary paths, pool
size, retry config</li>
<li><strong>Vision</strong>: Provider selection, OpenCV toggle, SSIM
threshold</li>
<li><strong>Recording</strong>: Video/screenshot capture, ffmpeg path,
quality</li>
<li><strong>Platforms</strong>: Android device, web URL/browser, desktop
process/display</li>
</ul>
<h3 id="quick-start">Quick Start</h3>
<div class="sourceCode" id="cb7"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="co"># 1. Copy and edit the configuration</span></span>
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="fu">cp</span> .env.example .env</span>
<span id="cb7-3"><a href="#cb7-3" aria-hidden="true" tabindex="-1"></a><span class="co"># Edit .env — set at least one API key and platform settings</span></span>
<span id="cb7-4"><a href="#cb7-4" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb7-5"><a href="#cb7-5" aria-hidden="true" tabindex="-1"></a><span class="co"># 2. Run an autonomous session against a project</span></span>
<span id="cb7-6"><a href="#cb7-6" aria-hidden="true" tabindex="-1"></a><span class="ex">helixqa</span> autonomous <span class="at">--project</span> /path/to/your-project <span class="dt">\</span></span>
<span id="cb7-7"><a href="#cb7-7" aria-hidden="true" tabindex="-1"></a>  <span class="at">--platforms</span> desktop <span class="dt">\</span></span>
<span id="cb7-8"><a href="#cb7-8" aria-hidden="true" tabindex="-1"></a>  <span class="at">--env</span> .env <span class="dt">\</span></span>
<span id="cb7-9"><a href="#cb7-9" aria-hidden="true" tabindex="-1"></a>  <span class="at">--timeout</span> 30m <span class="dt">\</span></span>
<span id="cb7-10"><a href="#cb7-10" aria-hidden="true" tabindex="-1"></a>  <span class="at">--output</span> qa-results/</span>
<span id="cb7-11"><a href="#cb7-11" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb7-12"><a href="#cb7-12" aria-hidden="true" tabindex="-1"></a><span class="co"># 3. View the results</span></span>
<span id="cb7-13"><a href="#cb7-13" aria-hidden="true" tabindex="-1"></a><span class="fu">cat</span> qa-results/qa-report.md</span>
<span id="cb7-14"><a href="#cb7-14" aria-hidden="true" tabindex="-1"></a><span class="fu">ls</span> qa-results/tickets/</span>
<span id="cb7-15"><a href="#cb7-15" aria-hidden="true" tabindex="-1"></a><span class="fu">ls</span> qa-results/videos/</span></code></pre></div>
<p>See <a href="USER_GUIDE_AUTONOMOUS.md">USER_GUIDE_AUTONOMOUS.md</a>
and <a href="VIDEO_COURSE_AUTONOMOUS.md">VIDEO_COURSE_AUTONOMOUS.md</a>
for detailed tutorials.</p>
<h2 id="testing">Testing</h2>
<div class="sourceCode" id="cb8"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb8-1"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span> test                 <span class="co"># Run all unit + integration tests</span></span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span> test-race            <span class="co"># With race detection</span></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span> test-cover           <span class="co"># With coverage report (coverage.html)</span></span>
<span id="cb8-4"><a href="#cb8-4" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span> vet                  <span class="co"># Static analysis</span></span>
<span id="cb8-5"><a href="#cb8-5" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span> qa-all               <span class="co"># Full QA: every challenges/scripts/*.sh</span></span>
<span id="cb8-6"><a href="#cb8-6" aria-hidden="true" tabindex="-1"></a>                          <span class="co"># + CONST-035 anti-bluff gates</span></span>
<span id="cb8-7"><a href="#cb8-7" aria-hidden="true" tabindex="-1"></a><span class="fu">make</span> anti-bluff           <span class="co"># Scan + behaviour-anchor manifest +</span></span>
<span id="cb8-8"><a href="#cb8-8" aria-hidden="true" tabindex="-1"></a>                          <span class="co"># mutation ratchet (per CONST-035)</span></span>
<span id="cb8-9"><a href="#cb8-9" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb8-10"><a href="#cb8-10" aria-hidden="true" tabindex="-1"></a><span class="co"># Round-219 addition — orchestrator-surface Challenge:</span></span>
<span id="cb8-11"><a href="#cb8-11" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> challenges/scripts/helixqa_orchestrator_challenge.sh</span></code></pre></div>
<p>See <strong><a
href="docs/test-coverage.md"><code>docs/test-coverage.md</code></a></strong>
for the full 15-row CONST-050(B) test-type matrix (unit, integration,
e2e, full-automation, security, ddos, scaling, chaos, stress,
performance, benchmarking, ui, ux, Challenges, autonomous-QA-session) —
each row tied to an executable asset under this submodule’s tree, each
PASS tied to a captured-evidence shape per §11.4.2.</p>
<h2 id="test-bank-conventions">Test-bank conventions</h2>
<p>Test banks under <a href="banks/"><code>banks/</code></a> are YAML
(or JSON peer) documents describing platform-targeted test cases.
Conventions:</p>
<ul>
<li><strong>Filename = test-bank logical name</strong> (kebab-case
<code>&lt;purpose&gt;-&lt;scope&gt;.yaml</code>). YAML and JSON peers
share the base name (<code>atmosphere.yaml</code> /
<code>atmosphere.json</code>) so tooling can auto-pair.</li>
<li><strong>Required top-level keys</strong>: <code>version</code>
(string, currently <code>"1.0"</code>), <code>name</code>
(human-readable), <code>test_cases</code> (array).</li>
<li><strong>Per-test-case keys</strong>: <code>id</code>
(<code>TC-XXX</code>), <code>name</code>, <code>category</code>
(<code>functional</code> / <code>performance</code> /
<code>security</code> / <code>ux</code> / <code>chaos</code> / …),
<code>priority</code> (<code>critical</code> / <code>high</code> /
<code>medium</code> / <code>low</code>), <code>platforms</code> (subset
of
<code>[android, android_tv, web, desktop, ios, aurora_os, harmony_os]</code>),
<code>steps[]</code> (each with <code>name</code>, <code>action</code>,
<code>expected</code>), <code>tags[]</code>, optional
<code>documentation_refs[]</code> for traceability into
<code>docs/</code>.</li>
<li><strong>Bank inventory floor</strong> (round 219): ≥ 30 YAML banks
on disk. Drops below the floor trigger phase 3 of the orchestrator
Challenge to FAIL.</li>
<li><strong>No hardcoded English user-facing strings in banks</strong>
per CONST-046 — <code>name</code> / <code>expected</code> strings drive
LLM-generated question prompts at runtime; banks describe
<strong>structure</strong>, not prose.</li>
</ul>
<h2 id="governance-pointers">Governance pointers</h2>
<table>
<colgroup>
<col style="width: 50%" />
<col style="width: 50%" />
</colgroup>
<thead>
<tr>
<th>Document</th>
<th>Authority</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="CONSTITUTION.md"><code>CONSTITUTION.md</code></a></td>
<td>Submodule-scoped constitutional anchors (CONST-035…063) inherited
from the constitution submodule</td>
</tr>
<tr>
<td><a href="CLAUDE.md"><code>CLAUDE.md</code></a> / <a
href="AGENTS.md"><code>AGENTS.md</code></a></td>
<td>AI-agent operating manuals — cascade pointers + anti-bluff
rules</td>
</tr>
<tr>
<td><a
href="docs/test-coverage.md"><code>docs/test-coverage.md</code></a></td>
<td>CONST-050(B) test-type coverage matrix — 15 rows, one per type</td>
</tr>
<tr>
<td><a href="helix-deps.yaml"><code>helix-deps.yaml</code></a></td>
<td>CONST-054 dependency manifest (Challenges + Containers, both
flat-layout)</td>
</tr>
<tr>
<td><a href="Upstreams/"><code>Upstreams/</code></a></td>
<td>CONST-056 upstream-remote recipes — <code>install_upstreams</code>
reads these on clone</td>
</tr>
<tr>
<td><a
href="docs/ANTI_BLUFF.md"><code>docs/ANTI_BLUFF.md</code></a></td>
<td>Anti-bluff posture details + baseline maintenance</td>
</tr>
<tr>
<td><a
href="docs/behavior-anchors.md"><code>docs/behavior-anchors.md</code></a></td>
<td>CONST-035 behaviour-anchor manifest (every advertised capability
anchored to a test)</td>
</tr>
<tr>
<td><a
href="docs/USER_MANUAL.md"><code>docs/USER_MANUAL.md</code></a></td>
<td>End-user-facing operating manual</td>
</tr>
<tr>
<td><a
href="USER_GUIDE_AUTONOMOUS.md"><code>USER_GUIDE_AUTONOMOUS.md</code></a>
/ <a
href="VIDEO_COURSE_AUTONOMOUS.md"><code>VIDEO_COURSE_AUTONOMOUS.md</code></a></td>
<td>Autonomous-QA-session tutorials</td>
</tr>
</tbody>
</table>
<h2 id="license">License</h2>
<p>Apache-2.0</p>
</body>
</html>