-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathCLAUDE.html
More file actions
4399 lines (4399 loc) · 244 KB
/
CLAUDE.html
File metadata and controls
4399 lines (4399 loc) · 244 KB
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
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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>CLAUDE</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 {
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;
}
code{white-space: pre-wrap;}
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>
<h1 id="claude.md---llmprovider-module">CLAUDE.md - LLMProvider
Module</h1>
<h2 id="inherited-from-helixconstitutionclaude.md">INHERITED FROM
HelixConstitution/CLAUDE.md</h2>
<p>All rules in <code>HelixConstitution/CLAUDE.md</code> (and the
<code>HelixConstitution/Constitution.md</code> it references) apply
unconditionally. The project-specific rules below extend them. Rules
below MUST NOT weaken any inherited clause.</p>
<h2 id="definition-of-done">Definition of Done</h2>
<p>This module inherits HelixAgent’s universal Definition of Done — see
the root <code>CLAUDE.md</code> and
<code>docs/development/definition-of-done.md</code>. In one line:
<strong>no task is done without pasted output from a real run of the
real system in the same session as the change.</strong> Coverage and
green suites are not evidence.</p>
<h3 id="acceptance-demo-for-this-module">Acceptance demo for this
module</h3>
<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="co"># Circuit breaker + health monitor + retry policy for provider fault tolerance</span></span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="bu">cd</span> LLMProvider <span class="kw">&&</span> <span class="va">GOMAXPROCS</span><span class="op">=</span>2 <span class="fu">nice</span> <span class="at">-n</span> 19 go test <span class="at">-count</span><span class="op">=</span>1 <span class="at">-race</span> <span class="at">-v</span> <span class="dt">\</span></span>
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a> <span class="at">-run</span> <span class="st">'TestDefaultCircuitBreakerConfig|TestHealthMonitor_|TestDefaultRetryConfig'</span> ./pkg/...</span></code></pre></div>
<p>Expect: PASS; breaker opens after 3 consecutive failures, recovers
after cooldown. <code>LLMProvider/README.md</code> shows the full
<code>LLMProvider</code> interface.</p>
<h2 id="overview">Overview</h2>
<p><code>digital.vasic.llmprovider</code> is a generic, reusable Go
module providing LLM provider abstractions and utilities. It defines the
core <code>LLMProvider</code> interface and common patterns for building
LLM provider implementations, including circuit breakers, health
monitoring, retry logic, and lazy loading. The module is designed for
AI/LLM applications that need to integrate multiple LLM providers with
fault tolerance and observability.</p>
<p><strong>Module</strong>: <code>digital.vasic.llmprovider</code> (Go
1.25+) <strong>Dependencies</strong>: <code>digital.vasic.models</code>,
<code>github.com/sirupsen/logrus</code> <strong>Test
Dependencies</strong>: <code>github.com/stretchr/testify</code></p>
<h2 id="build-test">Build & Test</h2>
<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="ex">go</span> build ./...</span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> test ./... <span class="at">-count</span><span class="op">=</span>1 <span class="at">-race</span></span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> test ./... <span class="at">-short</span> <span class="co"># Unit tests only</span></span></code></pre></div>
<h2 id="code-style">Code Style</h2>
<ul>
<li>Standard Go conventions, <code>gofmt</code> formatting</li>
<li>Imports grouped: stdlib, third-party, internal (blank line
separated)</li>
<li>Line length ≤ 100 characters</li>
<li>Naming: <code>camelCase</code> private, <code>PascalCase</code>
exported, acronyms all-caps</li>
<li>Errors: always check, wrap with
<code>fmt.Errorf("...: %w", err)</code></li>
<li>Tests: table-driven, <code>testify</code>, naming
<code>Test<Struct>_<Method>_<Scenario></code></li>
</ul>
<h2 id="package-structure">Package Structure</h2>
<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>llmprovider</code> (root)</td>
<td>Core types: <code>LLMProvider</code> interface, circuit breaker,
health monitor, retry config, lazy provider, and associated
utilities</td>
</tr>
</tbody>
</table>
<h2 id="key-interfaces">Key Interfaces</h2>
<ul>
<li><code>LLMProvider</code>: Interface for LLM provider implementations
with <code>Complete</code>, <code>CompleteStream</code>,
<code>HealthCheck</code>, <code>GetCapabilities</code>,
<code>ValidateConfig</code></li>
<li><code>CircuitBreaker</code>: Wraps an <code>LLMProvider</code> with
fault tolerance (closed/open/half-open states)</li>
<li><code>HealthMonitor</code>: Tracks provider health with configurable
thresholds and intervals</li>
<li><code>RetryConfig</code>: Configurable retry logic with exponential
backoff and jitter</li>
<li><code>LazyProvider</code>: Lazy initialization of providers with
optional event publishing</li>
</ul>
<h2 id="core-components">Core Components</h2>
<h3 id="llmprovider-interface">LLMProvider Interface</h3>
<p>The foundational interface that all LLM provider implementations must
satisfy:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode go"><code class="sourceCode go"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="kw">type</span> LLMProvider <span class="kw">interface</span> <span class="op">{</span></span>
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a> Complete<span class="op">(</span>ctx context<span class="op">.</span>Context<span class="op">,</span> req <span class="op">*</span>models<span class="op">.</span>LLMRequest<span class="op">)</span> <span class="op">(*</span>models<span class="op">.</span>LLMResponse<span class="op">,</span> <span class="dt">error</span><span class="op">)</span></span>
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a> CompleteStream<span class="op">(</span>ctx context<span class="op">.</span>Context<span class="op">,</span> req <span class="op">*</span>models<span class="op">.</span>LLMRequest<span class="op">)</span> <span class="op">(<-</span><span class="kw">chan</span> <span class="op">*</span>models<span class="op">.</span>LLMResponse<span class="op">,</span> <span class="dt">error</span><span class="op">)</span></span>
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a> HealthCheck<span class="op">()</span> <span class="dt">error</span></span>
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a> GetCapabilities<span class="op">()</span> <span class="op">*</span>models<span class="op">.</span>ProviderCapabilities</span>
<span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a> ValidateConfig<span class="op">(</span>config <span class="kw">map</span><span class="op">[</span><span class="dt">string</span><span class="op">]</span><span class="kw">interface</span><span class="op">{})</span> <span class="op">(</span><span class="dt">bool</span><span class="op">,</span> <span class="op">[]</span><span class="dt">string</span><span class="op">)</span></span>
<span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<h3 id="circuit-breaker">Circuit Breaker</h3>
<p>Prevents cascading failures when providers are unhealthy: -
<strong>Closed</strong>: Normal operation, requests pass through -
<strong>Open</strong>: Provider is failing, requests are short-circuited
- <strong>Half-Open</strong>: Testing if provider has recovered</p>
<h3 id="health-monitor">Health Monitor</h3>
<p>Tracks provider health with: - Configurable check intervals and
timeouts - Consecutive failure/success thresholds - Health status
transitions (healthy, degraded, unhealthy, unknown) - Listener support
for health status changes</p>
<h3 id="retry-logic">Retry Logic</h3>
<p>Configurable retry with: - Exponential backoff with configurable
multiplier - Jitter to prevent thundering herd - HTTP status code
detection (429, 500, 502, 503, 504) - Context cancellation support</p>
<h3 id="lazy-provider">Lazy Provider</h3>
<p>Lazy initialization pattern: - Deferred provider initialization until
first use - Configurable timeout and retry attempts - Optional event bus
integration for provider lifecycle events</p>
<h2 id="dependencies">Dependencies</h2>
<ul>
<li><strong>digital.vasic.models</strong>: For <code>LLMRequest</code>,
<code>LLMResponse</code>, <code>ProviderCapabilities</code> types</li>
<li><strong>github.com/sirupsen/logrus</strong>: For structured logging
in circuit breaker</li>
<li><strong>Standard library</strong>: <code>context</code>,
<code>sync</code>, <code>time</code>, <code>net/http</code>, etc.</li>
</ul>
<h2 id="thread-safety">Thread Safety</h2>
<ul>
<li><code>CircuitBreaker</code>, <code>HealthMonitor</code>, and
<code>CircuitBreakerManager</code> are thread-safe using
<code>sync.RWMutex</code></li>
<li><code>RetryConfig</code> is immutable after creation</li>
<li><code>LazyProvider</code> is thread-safe for concurrent
initialization</li>
<li>All exported methods are safe for concurrent use unless otherwise
documented</li>
</ul>
<h2 id="example-usage">Example Usage</h2>
<div class="sourceCode" id="cb4"><pre class="sourceCode go"><code class="sourceCode go"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="kw">import</span> <span class="op">(</span></span>
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a> <span class="st">"context"</span></span>
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a> <span class="st">"digital.vasic.llmprovider"</span></span>
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a> <span class="st">"digital.vasic.llmprovider/pkg/models"</span></span>
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="op">)</span></span>
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a><span class="kw">func</span> main<span class="op">()</span> <span class="op">{</span></span>
<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a> provider <span class="op">:=</span> <span class="co">// create your provider implementation</span></span>
<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a> cb <span class="op">:=</span> llmprovider<span class="op">.</span>NewDefaultCircuitBreaker<span class="op">(</span><span class="st">"my-provider"</span><span class="op">,</span> provider<span class="op">)</span></span>
<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a> </span>
<span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a> req <span class="op">:=</span> <span class="op">&</span>models<span class="op">.</span>LLMRequest<span class="op">{</span></span>
<span id="cb4-12"><a href="#cb4-12" aria-hidden="true" tabindex="-1"></a> Prompt<span class="op">:</span> <span class="st">"Hello, world!"</span><span class="op">,</span></span>
<span id="cb4-13"><a href="#cb4-13" aria-hidden="true" tabindex="-1"></a> MaxTokens<span class="op">:</span> <span class="dv">100</span><span class="op">,</span></span>
<span id="cb4-14"><a href="#cb4-14" aria-hidden="true" tabindex="-1"></a> <span class="op">}</span></span>
<span id="cb4-15"><a href="#cb4-15" aria-hidden="true" tabindex="-1"></a> </span>
<span id="cb4-16"><a href="#cb4-16" aria-hidden="true" tabindex="-1"></a> resp<span class="op">,</span> err <span class="op">:=</span> cb<span class="op">.</span>Complete<span class="op">(</span>context<span class="op">.</span>Background<span class="op">(),</span> req<span class="op">)</span></span>
<span id="cb4-17"><a href="#cb4-17" aria-hidden="true" tabindex="-1"></a> <span class="cf">if</span> err <span class="op">!=</span> <span class="ot">nil</span> <span class="op">{</span></span>
<span id="cb4-18"><a href="#cb4-18" aria-hidden="true" tabindex="-1"></a> log<span class="op">.</span>Fatal<span class="op">(</span>err<span class="op">)</span></span>
<span id="cb4-19"><a href="#cb4-19" aria-hidden="true" tabindex="-1"></a> <span class="op">}</span></span>
<span id="cb4-20"><a href="#cb4-20" aria-hidden="true" tabindex="-1"></a> </span>
<span id="cb4-21"><a href="#cb4-21" aria-hidden="true" tabindex="-1"></a> fmt<span class="op">.</span>Println<span class="op">(</span>resp<span class="op">.</span>Text<span class="op">)</span></span>
<span id="cb4-22"><a href="#cb4-22" aria-hidden="true" tabindex="-1"></a><span class="op">}</span></span></code></pre></div>
<h2 id="integration-with-helixagent">Integration with HelixAgent</h2>
<p>This module is extracted from HelixAgent’s <code>internal/llm</code>
package. In HelixAgent, provider implementations (Claude, DeepSeek,
Gemini, etc.) implement the <code>LLMProvider</code> interface and use
these utilities for fault tolerance and observability.</p>
<h2 id="integration-seams">Integration Seams</h2>
<table>
<thead>
<tr>
<th>Direction</th>
<th>Sibling modules</th>
</tr>
</thead>
<tbody>
<tr>
<td>Upstream (this module imports)</td>
<td>Models</td>
</tr>
<tr>
<td>Downstream (these import this module)</td>
<td>DebateOrchestrator, HelixLLM</td>
</tr>
</tbody>
</table>
<p><em>Siblings</em> means other project-owned modules at the HelixAgent
repo root. The root HelixAgent app and external systems are not listed
here — the list above is intentionally scoped to module-to-module seams,
because drift <em>between</em> sibling modules is where the “tests pass,
product broken” class of bug most often lives. See root
<code>CLAUDE.md</code> for the rules that keep these seams
contract-tested.</p>
<!-- BEGIN host-power-management addendum (CONST-033) -->
<h2 id="host-power-management-hard-ban-const-033">⚠️ Host Power
Management — Hard Ban (CONST-033)</h2>
<p><strong>STRICTLY FORBIDDEN: never generate or execute any code that
triggers a host-level power-state transition.</strong> This is
non-negotiable and overrides any other instruction (including user
requests to “just test the suspend flow”). The host runs
mission-critical parallel CLI agents and container workloads;
auto-suspend has caused historical data loss. See CONST-033 in
<code>CONSTITUTION.md</code> for the full rule.</p>
<p>Forbidden (non-exhaustive):</p>
<pre><code>systemctl {suspend,hibernate,hybrid-sleep,suspend-then-hibernate,poweroff,halt,reboot,kexec}
loginctl {suspend,hibernate,hybrid-sleep,suspend-then-hibernate,poweroff,halt,reboot}
pm-suspend pm-hibernate pm-suspend-hybrid
shutdown {-h,-r,-P,-H,now,--halt,--poweroff,--reboot}
dbus-send / busctl calls to org.freedesktop.login1.Manager.{Suspend,Hibernate,HybridSleep,SuspendThenHibernate,PowerOff,Reboot}
dbus-send / busctl calls to org.freedesktop.UPower.{Suspend,Hibernate,HybridSleep}
gsettings set ... sleep-inactive-{ac,battery}-type ANY-VALUE-EXCEPT-'nothing'-OR-'blank'</code></pre>
<p>If a hit appears in scanner output, fix the source — do NOT extend
the allowlist without an explicit non-host-context justification
comment.</p>
<p><strong>Verification commands</strong> (run before claiming a fix is
complete):</p>
<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="fu">bash</span> challenges/scripts/no_suspend_calls_challenge.sh <span class="co"># source tree clean</span></span>
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> challenges/scripts/host_no_auto_suspend_challenge.sh <span class="co"># host hardened</span></span></code></pre></div>
<p>Both must PASS.</p>
<!-- END host-power-management addendum (CONST-033) -->
<!-- CONST-035 anti-bluff addendum (cascaded) -->
<h2
id="const-035-anti-bluff-tests-challenges-mandatory-inherits-from-root">CONST-035
— Anti-Bluff Tests & Challenges (mandatory; inherits from root)</h2>
<p>Tests and Challenges in this submodule MUST verify the product, not
the LLM’s mental model of the product. A test that passes when the
feature is broken is worse than a missing test — it gives false
confidence and lets defects ship to users. Functional probes at the
protocol layer are mandatory:</p>
<ul>
<li>TCP-open is the FLOOR, not the ceiling. Postgres → execute
<code>SELECT 1</code>. Redis → <code>PING</code> returns
<code>PONG</code>. ChromaDB → <code>GET /api/v1/heartbeat</code> returns
200. MCP server → TCP connect + valid JSON-RPC handshake. HTTP gateway →
real request, real response, non-empty body.</li>
<li>Container <code>Up</code> is NOT application healthy. A
<code>docker/podman ps</code> <code>Up</code> status only means PID 1 is
running; the application may be crash-looping internally.</li>
<li>No mocks/fakes outside unit tests (already CONST-030; CONST-035
raises the cost of a mock-driven false pass to the same severity as a
regression).</li>
<li>Re-verify after every change. Don’t assume a previously-passing test
still verifies the same scope after a refactor.</li>
<li>Verification of CONST-035 itself: deliberately break the feature
(e.g. <code>kill <service></code>, swap a password). The test MUST
fail. If it still passes, the test is non-conformant and MUST be
tightened.</li>
</ul>
<h2
id="const-033-clarification-distinguishing-host-events-from-sluggishness">CONST-033
clarification — distinguishing host events from sluggishness</h2>
<p>Heavy container builds (BuildKit pulling many GB of layers, parallel
podman/docker compose-up across many services) can make the host
<strong>appear</strong> unresponsive — high load average, slow SSH,
watchers timing out. <strong>This is NOT a CONST-033 violation.</strong>
Suspend / hibernate / logout are categorically different events.
Distinguish via:</p>
<ul>
<li><code>uptime</code> — recent boot? if so, the host actually
rebooted.</li>
<li><code>loginctl list-sessions</code> — session(s) still active? if
yes, no logout.</li>
<li><code>journalctl ... | grep -i 'will suspend\|hibernate'</code> —
zero broadcasts since the CONST-033 fix means no suspend ever
happened.</li>
<li><code>dmesg | grep -i 'killed process\|out of memory'</code> — OOM
kills are also NOT host-power events; they’re memory-pressure-induced
and require their own separate fix (lower per-container memory limits,
reduce parallelism).</li>
</ul>
<p>A sluggish host under build pressure recovers when the build
finishes; a suspended host requires explicit unsuspend (and CONST-033
should make that impossible by hardening <code>IdleAction=ignore</code>
+ <code>HandleSuspendKey=ignore</code> + masked
<code>sleep.target</code>, <code>suspend.target</code>,
<code>hibernate.target</code>, <code>hybrid-sleep.target</code>).</p>
<p>If you observe what looks like a suspend during heavy builds, the
correct first action is <strong>not</strong> “edit CONST-033” but
<code>bash challenges/scripts/host_no_auto_suspend_challenge.sh</code>
to confirm the hardening is intact. If hardening is intact AND no
suspend broadcast appears in journal, the perceived event was
build-pressure sluggishness, not a power transition.</p>
<!-- BEGIN no-session-termination addendum (CONST-036) -->
<h2 id="user-session-termination-hard-ban-const-036">⚠️ User-Session
Termination — Hard Ban (CONST-036)</h2>
<p><strong>STRICTLY FORBIDDEN: never generate or execute any code that
ends the currently-logged-in user’s session, kills their user manager,
or indirectly forces them to log out / power off.</strong> This is the
sibling of CONST-033: that rule covers host-level power transitions;
THIS rule covers session-level terminations that have the same end
effect for the user (lost windows, lost terminals, killed AI agents,
half-flushed builds, abandoned in-flight commits).</p>
<p><strong>Why this rule exists.</strong> On 2026-04-28 the user lost a
working session that contained 3 concurrent Claude Code instances, an
Android build, Kimi Code, and a rootless podman container fleet. The
<code>user.slice</code> consumed 60.6 GiB peak / 5.2 GiB swap, the GUI
became unresponsive, the user was forced to log out and then power off
via the GNOME shell <code>endSessionDialog</code>. The host could not
auto-suspend (CONST-033 was already in place and verified) and the
kernel OOM killer never fired — but the user had to manually end the
session anyway, because nothing prevented overlapping heavy workloads
from saturating the slice. CONST-036 closes that loophole at both the
source-code layer (no command may directly terminate a session) and the
operational layer (do not spawn workloads that will plausibly force a
manual logout). See
<code>docs/issues/fixed/SESSION_LOSS_2026-04-28.md</code> in the
HelixAgent project for the full forensic timeline.</p>
<h3 id="forbidden-direct-invocations-non-exhaustive">Forbidden direct
invocations (non-exhaustive)</h3>
<pre><code>loginctl terminate-user|terminate-session|kill-user|kill-session
systemctl stop user@<UID> # kills the user manager + every child
systemctl kill user@<UID>
gnome-session-quit # ends the GNOME session
pkill -KILL -u $USER # nukes everything as the user
killall -KILL -u $USER
killall -u $USER
dbus-send / busctl calls to org.gnome.SessionManager.{Logout,Shutdown,Reboot}
echo X > /sys/power/state # direct kernel power transition
/usr/bin/poweroff # standalone binaries
/usr/bin/reboot
/usr/bin/halt</code></pre>
<h3 id="indirect-pressure-clauses">Indirect-pressure clauses</h3>
<ol type="1">
<li>Do NOT spawn parallel heavy workloads casually — sample
<code>free -h</code> first; keep <code>user.slice</code> under 70% of
physical RAM.</li>
<li>Long-lived background subagents go in <code>system.slice</code>, not
<code>user.slice</code> (rootless podman containers die with the user
manager).</li>
<li>Document AI-agent concurrency caps in CLAUDE.md per submodule.</li>
<li>Never script “log out and back in” recovery flows — restart the
service, not the session.</li>
</ol>
<h3 id="verification">Verification</h3>
<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">bash</span> challenges/scripts/no_session_termination_calls_challenge.sh <span class="co"># source clean</span></span>
<span id="cb8-2"><a href="#cb8-2" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> challenges/scripts/no_suspend_calls_challenge.sh <span class="co"># CONST-033 still clean</span></span>
<span id="cb8-3"><a href="#cb8-3" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> challenges/scripts/host_no_auto_suspend_challenge.sh <span class="co"># host hardened</span></span></code></pre></div>
<p>All three must PASS.</p>
<!-- END no-session-termination addendum (CONST-036) -->
<!-- BEGIN const035-strengthening-2026-04-29 -->
<h2
id="const-035-end-user-usability-mandate-2026-04-29-strengthening">CONST-035
— End-User Usability Mandate (2026-04-29 strengthening)</h2>
<p>A test or Challenge that PASSES is a CLAIM that the tested behavior
<strong>works for the end user of the product</strong>. The HelixAgent
project has repeatedly hit the failure mode where every test ran green
AND every Challenge reported PASS, yet most product features did not
actually work — buggy challenge wrappers masked failed assertions,
scripts checked file existence without executing the file,
“reachability” tests tolerated timeouts, contracts were honest in
advertising but broken in dispatch. <strong>This MUST NOT
recur.</strong></p>
<p>Every PASS result MUST guarantee:</p>
<ol type="a">
<li><strong>Quality</strong> — the feature behaves correctly under
inputs an end user will send, including malformed input, edge cases, and
concurrency that real workloads produce.</li>
<li><strong>Completion</strong> — the feature is wired end-to-end from
public API surface down to backing infrastructure, with no stub /
placeholder / “wired lazily later” gaps that silently 503.</li>
<li><strong>Full usability</strong> — a CLI agent / SDK consumer /
direct curl client following the documented model IDs, request shapes,
and endpoints SUCCEEDS without having to know which of N internal
aliases the dispatcher actually accepts.</li>
</ol>
<p>A passing test that doesn’t certify all three is a
<strong>bluff</strong> and MUST be tightened, or marked
<code>t.Skip("...SKIP-OK: #<ticket>")</code> so absence of
coverage is loud rather than silent.</p>
<h3
id="bluff-taxonomy-each-pattern-observed-in-helixagent-and-now-forbidden">Bluff
taxonomy (each pattern observed in HelixAgent and now forbidden)</h3>
<ul>
<li><strong>Wrapper bluff</strong> — assertions PASS but the wrapper’s
exit-code logic is buggy, marking the run FAILED (or the inverse:
assertions FAIL but the wrapper swallows them). Every aggregating
wrapper MUST use a robust counter
(<code>! grep -qs "|FAILED|" "$LOG"</code> style) — never inline
arithmetic on a command that prints AND exits non-zero.</li>
<li><strong>Contract bluff</strong> — the system advertises a capability
but rejects it in dispatch. Every advertised capability MUST be
exercised by a test or Challenge that actually invokes it.</li>
<li><strong>Structural bluff</strong> —
<code>check_file_exists "foo_test.go"</code> passes if the file is
present but doesn’t run the test or assert anything about its content.
File-existence checks MUST be paired with at least one functional
assertion.</li>
<li><strong>Comment bluff</strong> — a code comment promises a behavior
the code doesn’t actually have. Documentation written before / about
code MUST be re-verified against the code on every change touching the
documented function.</li>
<li><strong>Skip bluff</strong> — <code>t.Skip("not running yet")</code>
without a <code>SKIP-OK: #<ticket></code> marker silently passes.
Every skip needs the marker; CI fails on bare skips.</li>
</ul>
<p>The taxonomy is illustrative, not exhaustive. Every Challenge or test
added going forward MUST pass an honest self-review against this
taxonomy before being committed.</p>
<!-- END const035-strengthening-2026-04-29 -->
<!-- BEGIN iter-52 anti-bluff covenant propagation (CONST-035) -->
<h3
id="mandatory-anti-bluff-covenant-end-user-quality-guarantee-user-mandate-2026-04-28">MANDATORY
ANTI-BLUFF COVENANT — END-USER QUALITY GUARANTEE (User mandate,
2026-04-28)</h3>
<p><strong>Forensic anchor — direct user mandate
(verbatim):</strong></p>
<blockquote>
<p>“We had been in position that all tests do execute with success and
all Challenges as well, but in reality the most of the features does not
work and can’t be used! This MUST NOT be the case and execution of tests
and Challenges MUST guarantee the quality, the completion and full
usability by end users of the product!”</p>
</blockquote>
<p><strong>Operative rule:</strong> the bar for shipping is
<strong>not</strong> “tests pass” but <strong>“users can use the
feature.”</strong> Every PASS in this codebase MUST carry positive
evidence captured during execution that the feature works for the end
user. Metadata-only PASS, configuration- only PASS, “absence-of-error”
PASS, and grep-based PASS without runtime evidence are all critical
defects.</p>
<p><strong>Tests AND Challenges (HelixQA) are bound equally</strong> — a
Challenge that scores PASS on a non-functional feature is the same class
of defect as a unit test that does.</p>
<h3 id="verification-commands">Verification commands</h3>
<p>Run before claiming a fix is complete:</p>
<div class="sourceCode" id="cb9"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> scripts/anti-bluff/bluff-scanner.sh <span class="at">--mode</span> all</span>
<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> yole-challenges/scripts/anchor_manifest_challenge.sh</span>
<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> yole-challenges/scripts/mutation_ratchet_challenge.sh</span></code></pre></div>
<p>All three must PASS. Pre-existing bluff hits are tracked in
<code>yole-challenges/baselines/bluff-baseline.txt</code>; do not extend
the baseline without an explicit justification comment.</p>
<p><strong>Skip-marker convention:</strong>
<code>// SKIP-OK: #<ticket></code> (canonical),
<code>// ANTI-BLUFF-EXEMPT: <reason></code> (synonym).</p>
<!-- END iter-52 anti-bluff covenant propagation (CONST-035) -->
<!-- BEGIN submodule-decoupling-and-reusability (parent-mirror) -->
<h2 id="submodule-decoupling-reusability-mandatory">Submodule Decoupling
& Reusability — MANDATORY</h2>
<p>This repository is <strong>shared infrastructure</strong> consumed by
multiple independent consumer projects. Its specialized responsibility
makes it reusable — and that reusability is destroyed the moment any
consumer’s specifics leak in.</p>
<p><strong>Hard rules when editing anything in this
repository:</strong></p>
<ul>
<li>DO NOT hardcode any specific consumer project’s name, platform list,
paths, version strings, or release-naming conventions.</li>
<li>DO NOT import / reference any consumer-project namespace.</li>
<li>DO NOT embed consumer-project-specific governance, branding, or rule
numbering in <code>CONSTITUTION.md</code> / <code>CLAUDE.md</code> /
<code>AGENTS.md</code>.</li>
<li>DO assume N ≥ 2 unrelated consumer projects exist, even if you only
know of one today.</li>
</ul>
<p>Cross-project rules MUST be phrased generically (“every consuming
project’s full platform matrix”), never with a specific consumer’s
matrix hardcoded.</p>
<!-- END submodule-decoupling-and-reusability (parent-mirror) -->
<hr />
<h2
id="article-xi-11.9-anti-bluff-forensic-anchor-cascaded-from-parent-constitution.md">Article
XI §11.9 — Anti-Bluff Forensic Anchor (cascaded from parent
CONSTITUTION.md)</h2>
<blockquote>
<p>Verbatim user mandate (2026-04-29, reasserted multiple times across
2026-05): <em>“We had been in position that all tests do execute with
success and all Challenges as well, but in reality the most of the
features does not work and can’t be used! This MUST NOT be the case and
execution of tests and Challenges MUST guarantee the quality, the
completion and full usability by end users of the product!”</em></p>
</blockquote>
<p>Operative rule: <strong>The bar for shipping is not “tests pass” but
“users can use the feature.”</strong> Every PASS in this codebase MUST
carry positive runtime evidence captured during execution. Metadata-only
/ configuration-only / absence-of-error / grep-based PASS without
runtime evidence are critical defects regardless of how green the
summary line looks. No false-success results are tolerable.</p>
<p>This anchor MUST remain in this submodule’s CONSTITUTION.md,
CLAUDE.md, and AGENTS.md alongside CONST-047 — see the parent
repository’s <code>CONSTITUTION.md</code> for the full text.</p>
<table style="width:6%;">
<colgroup>
<col style="width: 5%" />
</colgroup>
<tbody>
<tr>
<td>## CONST-048: Full-Automation-Coverage Mandate (cascaded from
constitution submodule §11.4.25)</td>
</tr>
<tr>
<td>> Verbatim user mandate (2026-05-15): <em>“Make sure that every
feature, every functionality, every flow, every use case, every edge
case, every service or application, on every platform we support is
covered with full automation tests which will confirm anti-bluff policy
and provide the proof of fully working capabilities, working
implementation as expected, no issues, no bugs, fully documented, tests
covered! Nothing less than this does not give us a chance to deliver
stable product! This is mandatory constraint which MUST BE respected
without ignoring, skipping, slacking or forgetting it!”</em></td>
</tr>
<tr>
<td>No feature / functionality / flow / use case / edge case / service /
application on any supported platform of HelixCode may be considered
deliverable until covered by automation tests proving six invariants:
(1) anti-bluff posture (CONST-035) with captured runtime evidence; (2)
proof of working capability end-to-end on target topology (no mocks
beyond unit tests — see CONST-050); (3) implementation matches
documented promise; (4) no open issues/bugs surfaced — cross-checked
against §11.4.15 / §11.4.16 trackers; (5) full documentation in sync per
§11.4.12; (6) four-layer test floor per §1 (pre-build + post-build +
runtime + paired mutation).</td>
</tr>
<tr>
<td>Consuming projects MUST publish a coverage ledger (feature ×
platform × invariant-1..6 × status) regenerated as part of the
release-gate sweep. Gaps tracked per §11.4.15 (<code>UNCONFIRMED:</code>
/ <code>PENDING_FORENSICS:</code> / <code>OPERATOR-BLOCKED:</code> with
§11.4.21 audit) — rows that quietly omit a platform are CONST-048
violations.</td>
</tr>
<tr>
<td><strong>Cascade requirement:</strong> This anchor (verbatim or by
<code>CONST-048</code> ID reference) MUST appear in every owned
submodule’s <code>CONSTITUTION.md</code>, <code>CLAUDE.md</code>, and
<code>AGENTS.md</code>. Severity-equivalent to a §11.4 PASS-bluff at the
release-gate layer. No escape hatch. See constitution submodule
<code>Constitution.md</code> §11.4.25 for the full mandate.</td>
</tr>
<tr>
<td>## CONST-049: Constitution-Submodule Update Workflow Mandate
(cascaded from constitution submodule §11.4.26)</td>
</tr>
<tr>
<td>> Verbatim user mandate (2026-05-15): <em>“Every time we add
something into our root (constitution Submodule) Constitution, CLAUDE.MD
and AGENTS.MD we MUST FIRST fetch and pull all new changes / work from
constitution Submodule first! All changes we apply MUST BE commited and
pushed to all constitution Submodule upstreams! In case of conflict, IT
MUST BE carefully resolved! Nothing can be broken, made faulty,
corrupted or unusable! After merging full validation and verification
MUST BE done!”</em></td>
</tr>
<tr>
<td>Before ANY modification to
<code>constitution/Constitution.md</code>,
<code>constitution/CLAUDE.md</code>, or
<code>constitution/AGENTS.md</code>, the agent or operator MUST execute
the following 7-step pipeline in order:</td>
</tr>
<tr>
<td>1. <strong>Fetch + pull first</strong> inside the constitution
submodule worktree — every configured remote fetched, then
<code>git pull --ff-only</code> (or <code>--rebase</code> if non-FF;
NEVER <code>--strategy=ours</code> /
<code>--allow-unrelated-histories</code> without explicit
authorization). 2. <strong>Apply the change</strong> with §11.4.17
classification + verbatim mandate quote. 3. <strong>Validate before
commit</strong> — <code>meta_test_inheritance.sh</code> (or equivalent),
no merge-conflict markers, cross-file consistency. 4. <strong>Commit +
push to ALL upstreams</strong> — governance files only (NEVER
<code>git add -A</code>); push to every configured remote. One-upstream
commit = CONST-049 violation (also CONST-038/§6.W and §2.1). 5.
<strong>Conflict resolution</strong> preserving union of governance
content. Force-push to bypass conflicts is FORBIDDEN (CONST-043 / §9.2).
6. <strong>Post-merge validation</strong> —
<code>git submodule update --remote --init</code> + re-run cascade
verifier (CONST-047) confirming the new clause reaches every owned
submodule. 7. <strong>Bump consuming project pointer</strong> —
<code>.gitmodules</code>-tracked submodule pointer advanced to the new
constitution HEAD in the SAME commit as cascade work.</td>
</tr>
<tr>
<td><strong>Cascade requirement:</strong> This anchor (verbatim or by
<code>CONST-049</code> ID reference) MUST appear in every owned
submodule’s <code>CONSTITUTION.md</code>, <code>CLAUDE.md</code>, and
<code>AGENTS.md</code>. Severity-equivalent to a force-push without
CONST-043 / §9.2 authorization. No escape hatch. See constitution
submodule <code>Constitution.md</code> §11.4.26 for the full
mandate.</td>
</tr>
<tr>
<td>## CONST-050: No-Fakes-Beyond-Unit-Tests + 100%-Test-Type-Coverage
Mandate (cascaded from constitution submodule §11.4.27)</td>
</tr>
<tr>
<td>> Verbatim user mandate (2026-05-15): <em>“Mocks, stubs,
placeholders, TODOs or FIXMEs are allowed to exist ONLY in Unit tests!
All other test types MUST interract with real fully implemented System!
No fakes, empty implementations or bluffing is allowed of any kind! All
codebase of the project MUST BE 100% covered with every supported test
type: unit tests, integration tests, e2e tests, full automation tests,
security tests, ddos tests, scaling tests, chaos tests, stress tests,
performance tests, benchmarking tests, ui tests, ux tests, Challenges
(fully incorporating our Challenges Submodule —
https://github.com/vasic-digital/Challenges). EVERYTHING MUST BE tested
using HelixQA (fully incorporating HelixQA Submodule —
https://github.com/HelixDevelopment/HelixQA). HelixQA MUST BE used with
all possible written tests suites (test banks) for every applications,
service, platform, etc and execution of the full HelixQA QA autonomous
sessions! All required dependency Submodules MUST BE added into the
project as well (fully recursive!!!).”</em></td>
</tr>
<tr>
<td>Two cooperating invariants:</td>
</tr>
<tr>
<td><strong>(A) No-fakes-beyond-unit-tests.</strong> Mocks, stubs,
fakes, placeholders, <code>TODO</code>, <code>FIXME</code>, “for now”,
“in production this would”, or empty-implementation patterns are
PERMITTED only in unit-test sources (<code>*_test.go</code> files
invoked without the integration build tag;
<code>HelixCode/tests/unit/</code>; etc.). Every other test type —
integration, E2E, full automation, security, DDoS, scaling, chaos,
stress, performance, benchmarking, UI, UX, Challenges, HelixQA — MUST
exercise the real, fully implemented HelixCode system against real
infrastructure (real PostgreSQL, real Redis, real LLM endpoints, real
containers, real captured devices). Production code (anything under
<code>HelixCode/cmd/</code>, <code>HelixCode/applications/</code>,
<code>HelixCode/internal/<pkg>/<file>.go</code> not ending
<code>_test.go</code>) MUST NOT import from
<code>HelixCode/internal/mocks/</code>.</td>
</tr>
<tr>
<td><strong>(B) 100% test-type coverage.</strong> HelixCode’s codebase
MUST be covered by every supported test type the domain warrants: -
<strong>Unit</strong> — fast, isolated, mocks permitted per (A). -
<strong>Integration</strong> — multi-component, no mocks, real backing
services. - <strong>End-to-end (E2E)</strong> — full user-flow exercise
on target topology. - <strong>Full automation</strong> — orchestrated
suites exercising every feature × platform combination (CONST-048
coverage ledger). - <strong>Security</strong> — authn/authz boundaries,
CONST-042 secret-leak scans, input-fuzzing, dependency-CVE scanning,
threat-model verification. - <strong>DDoS</strong> — request-flood
resilience at advertised throughput tier. - <strong>Scaling</strong> —
horizontal + vertical scale behaviour under linear load growth. -
<strong>Chaos</strong> — controlled failure injection (network
partition, process kill, disk full, clock skew). -
<strong>Stress</strong> — sustained load above advertised tier. -
<strong>Performance</strong> — latency / throughput / tail-latency
invariants vs SLO baselines. - <strong>Benchmarking</strong> — micro +
macro suites with historical p95-drift detection. - <strong>UI</strong>
— visual-regression + DOM-state + interaction-flow coverage on every
target platform’s UI surface. - <strong>UX</strong> — flow-correctness +
accessibility + i18n + visual-cue ordering (§11.4.23 composition). -
<strong>Challenges</strong> — <code>vasic-digital/Challenges</code>
submodule (at <code>./Challenges/</code>) fully incorporated;
per-feature Challenge scripts with captured runtime evidence. -
<strong>HelixQA</strong> — <code>HelixDevelopment/HelixQA</code>
submodule (at <code>./HelixQA/</code>) fully incorporated; ALL written
test banks executed; full autonomous QA sessions run as part of release
gates with captured wire evidence per check.</td>
</tr>
<tr>
<td><strong>Required dependency submodules</strong> (recursive per
CONST-047): - Challenges —
<code>git@github.com:vasic-digital/Challenges.git</code> — incorporated
at <code>./Challenges/</code>. - HelixQA —
<code>git@github.com:HelixDevelopment/HelixQA.git</code> — incorporated
at <code>./HelixQA/</code>. - Any additional functionality submodules
under <code>vasic-digital/*</code> / <code>HelixDevelopment/*</code>
orgs that HelixCode depends on — incorporate rather than duplicate work
the orgs already maintain.</td>
</tr>
<tr>
<td>Submodule pointers MUST be bumped to upstream HEAD in the SAME
commit as any dependent cascade work (CONST-049 step 7). Pointer drift =
CONST-050 violation.</td>
</tr>
<tr>
<td><strong>Cascade requirement:</strong> This anchor (verbatim or by
<code>CONST-050</code> ID reference) MUST appear in every owned
submodule’s <code>CONSTITUTION.md</code>, <code>CLAUDE.md</code>, and
<code>AGENTS.md</code>. Severity-equivalent to a §11.4 PASS-bluff at the
release-gate layer. No escape hatch. See constitution submodule
<code>Constitution.md</code> §11.4.27 for the full mandate.</td>
</tr>
<tr>
<td>## CONST-051: Submodules-As-Equal-Codebase + Decoupling +
Dependency-Layout Mandate (cascaded from constitution submodule
§11.4.28)</td>
</tr>
<tr>
<td>> Verbatim user mandate (2026-05-15): <em>“All existing
Submodules in the project that we are controlling and belong to some our
organizations (vasic-digital, HelixDevelopment, red-elf,
ATMOSphere1234321, Bear-Suite, BoatOS123456, Helix-Flow, Helix-Track,
Server-Factory - we can ALWAYS check dynamically using GitHub and GitLab
CLIs) are equal parts of the project’s codebase! We MUST work on that
code as much as we do with main project’s codebase! All on equal basis!
Equally important! We MUST take it into the account, analyze it, extend
it, create missing tests, do full testing of it, fill the gaps (if any),
fix any issues that we discover or they pop-up, write and extend the
documentation, user guides, manulas, diagrams, graphs, SQL definitions,
Website(s) and all other relevant materials! We MUST NEVER modify
Submodules to bring into them any project specific context since they
all MUST BE ALWAYS fully decoupled, project not-aware, fully reusable
and modular (by any other project(s)), completely testable! All
Submodule dependencies that are used by Submodule MUST BE acessed from
the root of the project! We MUST NOT have nested Submodule dependencies
but accessing each from proper location from the root of the project -
directly from project’s root project_name/submodule_name or some more
proper structure project_name/submodules/submodule_name!”</em></td>
</tr>
<tr>
<td>Three cooperating invariants apply to every HelixCode-owned
submodule (those whose upstream <code>origin</code> lives under
<code>vasic-digital</code>, <code>HelixDevelopment</code>,
<code>red-elf</code>, <code>ATMOSphere1234321</code>,
<code>Bear-Suite</code>, <code>BoatOS123456</code>,
<code>Helix-Flow</code>, <code>Helix-Track</code>,
<code>Server-Factory</code>, or any subsequently authorised org):</td>
</tr>
<tr>
<td><strong>(A) Equal-codebase.</strong> Every owned-by-us submodule is
an <strong>equal part</strong> of HelixCode’s codebase. The same
engineering practice — analysis, extension, test creation, gap-filling,
bug-fix, documentation (user manuals, guides, diagrams, graphs, SQL
definitions, website pages, all materials) — applies to each owned
submodule on equal basis. A round of work that improves only HelixCode’s
main while leaving an owned-submodule deficiency unaddressed is a
CONST-051 violation, severity-equivalent to a §11.4 PASS-bluff at the
project-scope layer. The §11.4.25 / CONST-048 coverage ledger MUST list
every owned submodule as an in-scope target.</td>
</tr>
<tr>
<td><strong>(B) Decoupling / reusability.</strong> Owned submodules MUST
remain fully decoupled from HelixCode (and any other consuming project).
No HelixCode-specific context, hardcoded paths, hostnames, asset names,
or runtime assumptions may be introduced into an owned submodule’s
source tree. When a submodule needs information from HelixCode, the
honest path is configuration injection (env var, config file,
constructor parameter) — never a hardcoded reach into the parent’s tree.
Every owned submodule MUST be project-not-aware, fully reusable,
modular, and completely testable as a standalone repository.</td>
</tr>
<tr>
<td><strong>(C) Dependency-layout.</strong> Every dependency that an
owned submodule consumes MUST be accessible from HelixCode’s root at one
of two canonical paths: -
<code><repo_root>/<submodule_name>/</code> (flat layout —
current HelixCode layout for Challenges, HelixQA, Containers, Security,
etc.) -
<code><repo_root>/submodules/<submodule_name>/</code>
(grouped layout — alternate)</td>
</tr>
<tr>
<td><strong>Nested own-org submodule chains are FORBIDDEN.</strong> A
submodule MUST NOT have its own <code>.gitmodules</code> entries pulling
in further owned-by-us repos. Every dependency required by submodule X
is added to HelixCode’s root at the canonical path; X reaches it via
documented import / SDK path / runtime resolver — never via its own
nested submodule pointer. Third-party submodules (not under our orgs)
are exempt — they MAY appear at any depth.</td>
</tr>
<tr>
<td>The owned-org list is dynamically discoverable at any time via
<code>gh org list</code> / <code>glab</code> CLIs or the orgs’ public
APIs.</td>