-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathAGENTS.html
More file actions
4439 lines (4439 loc) · 240 KB
/
AGENTS.html
File metadata and controls
4439 lines (4439 loc) · 240 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>AGENTS</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="agents.md---llmprovider-module">AGENTS.md - LLMProvider
Module</h1>
<blockquote>
<p><strong>Base agent rules:</strong>
<code>HelixConstitution/AGENTS.md</code> — READ IT FIRST. All rules in
<code>HelixConstitution/AGENTS.md</code> apply unconditionally. Rules
below extend them and MUST NOT weaken any inherited clause.</p>
</blockquote>
<h2 id="module-overview">Module 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 path</strong>: <code>digital.vasic.llmprovider</code>
<strong>Go version</strong>: 1.25.3+ <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="package-responsibilities">Package Responsibilities</h2>
<table>
<colgroup>
<col style="width: 29%" />
<col style="width: 19%" />
<col style="width: 51%" />
</colgroup>
<thead>
<tr>
<th>Package</th>
<th>Path</th>
<th>Responsibility</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>llmprovider</code></td>
<td><code>./</code></td>
<td>Core types: <code>LLMProvider</code> interface, circuit breaker,
health monitor, retry config, lazy provider, and associated utilities.
This is the only package.</td>
</tr>
</tbody>
</table>
<h2 id="dependency-graph">Dependency Graph</h2>
<pre><code>digital.vasic.models
↓
digital.vasic.llmprovider
↓
github.com/sirupsen/logrus</code></pre>
<h2 id="key-files">Key Files</h2>
<table>
<colgroup>
<col style="width: 40%" />
<col style="width: 60%" />
</colgroup>
<thead>
<tr>
<th>File</th>
<th>Purpose</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>provider.go</code></td>
<td><code>LLMProvider</code> interface definition with
<code>Complete</code>, <code>CompleteStream</code>,
<code>HealthCheck</code>, <code>GetCapabilities</code>,
<code>ValidateConfig</code> methods</td>
</tr>
<tr>
<td><code>circuit_breaker.go</code></td>
<td>Circuit breaker implementation (503 lines) with
closed/open/half-open states, failure counting, timeout</td>
</tr>
<tr>
<td><code>health_monitor.go</code></td>
<td>Health monitoring (430 lines) with configurable thresholds,
intervals, status transitions</td>
</tr>
<tr>
<td><code>retry.go</code></td>
<td>Retry logic (226 lines) with exponential backoff, jitter, HTTP
status code detection</td>
</tr>
<tr>
<td><code>types.go</code></td>
<td>Empty file (types moved to models module)</td>
</tr>
<tr>
<td><code>circuit_breaker_test.go</code></td>
<td>Circuit breaker tests (585 lines)</td>
</tr>
<tr>
<td><code>health_monitor_test.go</code></td>
<td>Health monitor tests</td>
</tr>
<tr>
<td><code>retry_test.go</code></td>
<td>Retry logic tests</td>
</tr>
<tr>
<td><code>types_test.go</code></td>
<td>Empty test file</td>
</tr>
<tr>
<td><code>go.mod</code></td>
<td>Module definition and dependencies</td>
</tr>
<tr>
<td><code>CLAUDE.md</code></td>
<td>AI coding assistant instructions</td>
</tr>
<tr>
<td><code>README.md</code></td>
<td>User-facing documentation with quick start</td>
</tr>
</tbody>
</table>
<h2 id="agent-coordination-guide">Agent Coordination Guide</h2>
<h3 id="division-of-work">Division of Work</h3>
<p>When multiple agents work on this module simultaneously, divide work
by component categories:</p>
<ol type="1">
<li><strong>Interface Agent</strong> – Owns <code>LLMProvider</code>
interface definition and related methods. Changes affect all provider
implementations.</li>
<li><strong>Circuit Breaker Agent</strong> – Owns circuit breaker
implementation and <code>CircuitBreakerManager</code>. Affects fault
tolerance.</li>
<li><strong>Health Monitor Agent</strong> – Owns health monitoring,
thresholds, status transitions.</li>
<li><strong>Retry Logic Agent</strong> – Owns retry configuration,
exponential backoff, HTTP status detection.</li>
<li><strong>Lazy Provider Agent</strong> – Owns lazy initialization
pattern and deferred provider creation.</li>
</ol>
<h3 id="coordination-rules">Coordination Rules</h3>
<ul>
<li><strong><code>LLMProvider</code> interface changes</strong> require
coordination with all agents as this is the foundational interface.</li>
<li><strong>Circuit breaker behavior changes</strong> affect fault
tolerance across all providers.</li>
<li><strong>Health monitor thresholds</strong> affect provider health
detection and automatic failover.</li>
<li><strong>Retry logic changes</strong> affect error recovery and rate
limiting handling.</li>
<li><strong>Lazy provider changes</strong> affect initialization
patterns and startup performance.</li>
</ul>
<h3 id="safe-parallel-changes">Safe Parallel Changes</h3>
<p>These changes can be made simultaneously without coordination: -
Adding new methods to existing structs (if they don’t affect interface)
- Adding new configuration options with sensible defaults - Adding new
helper functions - Updating documentation - Adding new test cases -
Improving error messages or logging</p>
<h3 id="changes-requiring-coordination">Changes Requiring
Coordination</h3>
<ul>
<li>Modifying <code>LLMProvider</code> interface method signatures
(breaks all implementations)</li>
<li>Changing circuit breaker state machine logic (affects fault
tolerance)</li>
<li>Modifying health monitor status transition thresholds (affects
provider health detection)</li>
<li>Changing retry exponential backoff formula (affects error recovery
timing)</li>
<li>Modifying lazy provider initialization semantics (affects startup
behavior)</li>
</ul>
<h2 id="build-and-test-commands">Build and Test Commands</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="co"># Build all packages</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> build ./...</span>
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="co"># Run all tests with race detection</span></span>
<span id="cb2-5"><a href="#cb2-5" 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-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="co"># Run unit tests only (short mode)</span></span>
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> test ./... <span class="at">-short</span></span>
<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a><span class="co"># Run a specific test</span></span>
<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> test <span class="at">-v</span> <span class="at">-run</span> TestCircuitBreaker ./...</span>
<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a><span class="co"># Format code</span></span>
<span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a><span class="ex">gofmt</span> <span class="at">-w</span> .</span>
<span id="cb2-15"><a href="#cb2-15" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a><span class="co"># Vet code</span></span>
<span id="cb2-17"><a href="#cb2-17" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> vet ./...</span>
<span id="cb2-18"><a href="#cb2-18" aria-hidden="true" tabindex="-1"></a></span>
<span id="cb2-19"><a href="#cb2-19" aria-hidden="true" tabindex="-1"></a><span class="co"># Check dependencies</span></span>
<span id="cb2-20"><a href="#cb2-20" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> mod tidy</span>
<span id="cb2-21"><a href="#cb2-21" aria-hidden="true" tabindex="-1"></a><span class="ex">go</span> mod verify</span></code></pre></div>
<h2 id="commit-conventions">Commit Conventions</h2>
<p>Follow Conventional Commits with llmprovider scope:</p>
<pre><code>feat(llmprovider): add new method to LLMProvider interface for batch processing
feat(circuit): add configurable failure threshold to circuit breaker
feat(health): add degraded state to health monitor
feat(retry): add jitter to exponential backoff
fix(circuit): correct race condition in state transition
test(health): add edge case tests for health monitor thresholds
docs(llmprovider): update API reference for new methods
refactor(retry): extract common backoff calculation functions</code></pre>
<h2 id="thread-safety-and-concurrency">Thread Safety and
Concurrency</h2>
<ul>
<li><code>CircuitBreaker</code> uses <code>sync.RWMutex</code> for
thread-safe state management</li>
<li><code>HealthMonitor</code> uses atomic operations for status
updates</li>
<li><code>CircuitBreakerManager</code> is thread-safe for concurrent
provider management</li>
<li><code>RetryConfig</code> is immutable after creation</li>
<li><code>LazyProvider</code> uses <code>sync.Once</code> for
thread-safe lazy initialization</li>
<li>All exported methods are safe for concurrent use unless otherwise
documented</li>
</ul>
<h2 id="integration-notes">Integration Notes</h2>
<ul>
<li>This module depends on <code>digital.vasic.models</code> for
<code>LLMRequest</code>, <code>LLMResponse</code>,
<code>ProviderCapabilities</code> types</li>
<li>Provider implementations should import this module and implement the
<code>LLMProvider</code> interface</li>
<li>The module is designed for zero-dependency provider implementations
(implementations only need this module and models)</li>
<li>Circuit breaker and health monitor can be composed around any
<code>LLMProvider</code> implementation
<!-- BEGIN host-power-management addendum (CONST-033) --></li>
</ul>
<h2 id="host-power-management-hard-ban-const-033">Host Power Management
— Hard Ban (CONST-033)</h2>
<p><strong>You may NOT, under any circumstance, generate or execute code
that sends the host to suspend, hibernate, hybrid-sleep, poweroff, halt,
reboot, or any other power-state transition.</strong> This rule applies
to:</p>
<ul>
<li>Every shell command you run via the Bash tool.</li>
<li>Every script, container entry point, systemd unit, or test you write
or modify.</li>
<li>Every CLI suggestion, snippet, or example you emit.</li>
</ul>
<p><strong>Forbidden invocations</strong> (non-exhaustive — see
CONST-033 in <code>CONSTITUTION.md</code> for the full list):</p>
<ul>
<li><code>systemctl suspend|hibernate|hybrid-sleep|poweroff|halt|reboot|kexec</code></li>
<li><code>loginctl suspend|hibernate|hybrid-sleep|poweroff|halt|reboot</code></li>
<li><code>pm-suspend</code>, <code>pm-hibernate</code>,
<code>shutdown -h|-r|-P|now</code></li>
<li><code>dbus-send</code> / <code>busctl</code> calls to
<code>org.freedesktop.login1.Manager.Suspend|Hibernate|PowerOff|Reboot|HybridSleep|SuspendThenHibernate</code></li>
<li><code>gsettings set ... sleep-inactive-{ac,battery}-type</code> to
anything but <code>'nothing'</code> or <code>'blank'</code></li>
</ul>
<p>The host runs mission-critical parallel CLI agents and container
workloads. Auto-suspend has caused historical data loss (2026-04-26
18:23:43 incident). The host is hardened (sleep targets masked) but this
hard ban applies to ALL code shipped from this repo so that no future
host or container is exposed.</p>
<p><strong>Defence:</strong> every project ships
<code>scripts/host-power-management/check-no-suspend-calls.sh</code>
(static scanner) and
<code>challenges/scripts/no_suspend_calls_challenge.sh</code> (challenge
wrapper). Both MUST be wired into the project’s CI /
<code>run_all_challenges.sh</code>.</p>
<p><strong>Full background:</strong>
<code>docs/HOST_POWER_MANAGEMENT.md</code> and
<code>CONSTITUTION.md</code> (CONST-033).</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>You may NOT, under any circumstance, generate or execute code
that ends the currently-logged-in user’s desktop session, kills their
<code>user@<UID>.service</code> user manager, or indirectly forces
them to manually 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. The host could not auto-suspend (CONST-033 was 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 and the operational layer.
See <code>docs/issues/fixed/SESSION_LOSS_2026-04-28.md</code> in the
HelixAgent project.</p>
<p><strong>Forbidden direct invocations</strong> (non-exhaustive):</p>
<ul>
<li><code>loginctl terminate-user|terminate-session|kill-user|kill-session</code></li>
<li><code>systemctl stop user@<UID></code> /
<code>systemctl kill user@<UID></code></li>
<li><code>gnome-session-quit</code></li>
<li><code>pkill -KILL -u $USER</code> /
<code>killall -u $USER</code></li>
<li><code>dbus-send</code> / <code>busctl</code> calls to
<code>org.gnome.SessionManager.Logout|Shutdown|Reboot</code></li>
<li><code>echo X > /sys/power/state</code></li>
<li><code>/usr/bin/poweroff</code>, <code>/usr/bin/reboot</code>,
<code>/usr/bin/halt</code></li>
</ul>
<p><strong>Indirect-pressure clauses:</strong></p>
<ol type="1">
<li>Do not spawn parallel heavy workloads casually; check
<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>.
Rootless podman containers die with the user manager.</li>
<li>Document AI-agent concurrency caps in CLAUDE.md.</li>
<li>Never script “log out and back in” recovery flows.</li>
</ol>
<p><strong>Defence:</strong> every project ships
<code>scripts/host-power-management/check-no-session-termination-calls.sh</code>
(static scanner) and
<code>challenges/scripts/no_session_termination_calls_challenge.sh</code>
(challenge wrapper). Both MUST be wired into the project’s CI /
<code>run_all_challenges.sh</code>.</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="cb4"><pre
class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-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="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> yole-challenges/scripts/anchor_manifest_challenge.sh</span>
<span id="cb4-3"><a href="#cb4-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-for-all-ai-agents">Submodule
Decoupling & Reusability — MANDATORY for ALL AI Agents</h2>
<p><strong>Applies to ALL CLI agents (Codex, Cursor, Gemini CLI, Copilot
CLI, Claude Code, etc.) working in this repository.</strong></p>
<p>This repository is <strong>shared infrastructure</strong> consumed by
multiple independent consumer projects. The value of this repository
depends on staying fully decoupled and reusable.</p>
<p><strong>Hard rules:</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.</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>