-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathCONSTITUTION.html
More file actions
3298 lines (3298 loc) · 175 KB
/
CONSTITUTION.html
File metadata and controls
3298 lines (3298 loc) · 175 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>CONSTITUTION</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="llmprovider-constitution">LLMProvider — Constitution</h1>
<blockquote>
<p><strong>Inherits from:</strong>
<code>HelixConstitution/Constitution.md</code> — all universal clauses
in that document apply unconditionally. Rules below extend or tighten
them; they MUST NOT weaken any inherited clause.</p>
</blockquote>
<blockquote>
<p><strong>Status:</strong> Active. This document is the project’s
authoritative rule set. When a rule here conflicts with
<code>CLAUDE.md</code>, <code>AGENTS.md</code>, or any guide, the
Constitution wins.</p>
</blockquote>
<h2 id="mission">Mission</h2>
<p>See README.md.</p>
<h2 id="mandatory-standards">Mandatory Standards</h2>
<ol type="1">
<li><strong>Reproducibility:</strong> every change is reproducible from
a clean clone
(<code>git clone <repo> && <project bootstrap></code>);
no hidden steps.</li>
<li><strong>Tests track behavior, not code:</strong> test what the
user-visible behavior is, not what the implementation looks like.</li>
<li><strong>No silent skips, no silent mocks above unit
tests.</strong></li>
<li><strong>Conventional Commits</strong> for all commits.</li>
<li><strong>SSH-only for git operations</strong> (<code>git@…</code>);
HTTPS prohibited.</li>
</ol>
<h2 id="numbered-rules">Numbered Rules</h2>
<!-- Rules are numbered CONST-NNN. New rules append. Removed rules
keep their number with a "**Retired:** …" line. -->
<!-- BEGIN host-power-management addendum (CONST-033) -->
<h3 id="const-033-host-power-management-is-forbidden">CONST-033 — Host
Power Management is Forbidden</h3>
<p><strong>Status:</strong> Mandatory. Non-negotiable. Applies to every
project, submodule, container entry point, build script, test,
challenge, and systemd unit shipped from this repository.</p>
<p><strong>Rule:</strong> No code in this repository may invoke a
host-level power- state transition (suspend, hibernate, hybrid-sleep,
suspend-then- hibernate, poweroff, halt, reboot, kexec) on the host
machine. This includes — but is not limited to:</p>
<ul>
<li><code>systemctl {suspend,hibernate,hybrid-sleep,suspend-then-hibernate,poweroff,halt,reboot,kexec}</code></li>
<li><code>loginctl {suspend,hibernate,hybrid-sleep,suspend-then-hibernate,poweroff,halt,reboot}</code></li>
<li><code>pm-{suspend,hibernate,suspend-hybrid}</code></li>
<li><code>shutdown {-h,-r,-P,-H,now,--halt,--poweroff,--reboot}</code></li>
<li>DBus calls to
<code>org.freedesktop.login1.Manager.{Suspend,Hibernate,HybridSleep,SuspendThenHibernate,PowerOff,Reboot}</code></li>
<li>DBus calls to
<code>org.freedesktop.UPower.{Suspend,Hibernate,HybridSleep}</code></li>
<li><code>gsettings set ... sleep-inactive-{ac,battery}-type</code> to
any value other than <code>'nothing'</code> or <code>'blank'</code></li>
</ul>
<p><strong>Why:</strong> The host runs mission-critical parallel
CLI-agent and container workloads. On 2026-04-26 18:23:43 the host was
auto- suspended by the GDM greeter’s idle policy mid-session, killing
HelixAgent and 41 dependent services. Recurring memory-pressure SIGKILLs
of <code>user@1000.service</code> (perceived as “logged out”) have the
same outcome. Auto-suspend, hibernate, and any power-state transition
are unsafe for this host.</p>
<p><strong>Defence in depth (mandatory artifacts in every
project):</strong> 1.
<code>scripts/host-power-management/install-host-suspend-guard.sh</code>
— privileged installer, manual prereq, run once per host with sudo.
Masks <code>sleep.target</code>, <code>suspend.target</code>,
<code>hibernate.target</code>, <code>hybrid-sleep.target</code>; writes
<code>AllowSuspend=no</code> drop-in; sets logind
<code>IdleAction=ignore</code> and <code>HandleLidSwitch=ignore</code>.
2.
<code>scripts/host-power-management/user_session_no_suspend_bootstrap.sh</code>
— per-user, no-sudo defensive layer. Idempotent. Safe to source from
<code>start.sh</code> / <code>setup.sh</code> /
<code>bootstrap.sh</code>. 3.
<code>scripts/host-power-management/check-no-suspend-calls.sh</code> —
static scanner. Exits non-zero on any forbidden invocation. 4.
<code>challenges/scripts/host_no_auto_suspend_challenge.sh</code> —
asserts the running host’s state matches layer-1 masking. 5.
<code>challenges/scripts/no_suspend_calls_challenge.sh</code> — wraps
the scanner as a challenge that runs in CI /
<code>run_all_challenges.sh</code>.</p>
<p><strong>Enforcement:</strong> Every project’s CI /
<code>run_all_challenges.sh</code> equivalent MUST run both challenges
(host state + source tree). A violation in either channel blocks merge.
Adding files to the scanner’s <code>EXCLUDE_PATHS</code> requires an
explicit justification comment identifying the non-host context.</p>
<p><strong>See also:</strong> <code>docs/HOST_POWER_MANAGEMENT.md</code>
for full background and runbook.</p>
<!-- END host-power-management addendum (CONST-033) -->
<h2 id="definition-of-done">Definition of Done</h2>
<p>A change is done when:</p>
<ol type="1">
<li>The code change is committed.</li>
<li>All project-level tests pass on a clean clone.</li>
<li>All challenges in <code>challenges/scripts/</code> pass on the
running host.</li>
<li>Governance docs (<code>CONSTITUTION.md</code>,
<code>AGENTS.md</code>, <code>CLAUDE.md</code>) are coherent with the
change.</li>
</ol>
<h2 id="see-also">See also</h2>
<ul>
<li><code>README.md</code> — project overview, quickstart.</li>
<li><code>AGENTS.md</code> — guidance for AI coding agents (Codex,
Cursor, etc.).</li>
<li><code>CLAUDE.md</code> — guidance specifically for Claude Code.</li>
<li><code>docs/HOST_POWER_MANAGEMENT.md</code> — CONST-033 background
and runbook.</li>
</ul>
<!-- 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 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="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="fu">bash</span> scripts/anti-bluff/bluff-scanner.sh <span class="at">--mode</span> all</span>
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="fu">bash</span> yole-challenges/scripts/anchor_manifest_challenge.sh</span>
<span id="cb1-3"><a href="#cb1-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) -->
<h3 id="submodule-decoupling-reusability-mandatory">Submodule Decoupling
& Reusability — Mandatory</h3>
<p><strong>Status:</strong> Mandatory. Non-negotiable.</p>
<p><strong>Rule:</strong> This repository is a <strong>shared
submodule</strong> consumed by multiple independent consumer projects.
Its value depends on staying <strong>fully decoupled and
reusable</strong>. No change in this repository may introduce coupling
that breaks its standalone reusability for any consumer.</p>
<p><strong>Prohibited inside this repository:</strong></p>
<ol type="1">
<li>Hardcoding any specific consumer project’s name, paths, platform
list, version strings, release-naming conventions, branding, or feature
names.</li>
<li><code>import</code> / dependency on any consumer-project namespace,
package, or build coordinate.</li>
<li>Embedding consumer-project-specific governance, rule numbering, or
release cadence into this repository’s <code>CONSTITUTION.md</code> /
<code>CLAUDE.md</code> / <code>AGENTS.md</code>.</li>
<li>Assuming this repository is consumed by a particular CLI, build
system, language toolchain version, or target architecture beyond what
its public interface documents.</li>
</ol>
<p><strong>Required inside this repository:</strong></p>
<ol type="1">
<li>All public surfaces (APIs, CLIs, configuration files, environment
variables, scripts) MUST be expressed in terms of THIS repository’s own
domain — not any consumer’s.</li>
<li>Governance MUST describe responsibilities and contract from THIS
repository’s perspective. Consumer projects appear as illustrative
examples at most, never as load-bearing requirements.</li>
<li>Cross-project rules adopted from a consumer (such as a
cross-platform impact mandate) MUST be phrased generically — “every
consuming project’s full platform matrix” — and never hardcode any
single consumer’s matrix.</li>
</ol>
<p><strong>Why:</strong> Repositories like this one have shipped changes
in the past where one consumer’s platform list, feature names, or rule
numbering leaked into shared-repo governance — and then collided at
merge time with another consumer’s parallel work, leaving the repository
unmergeable until manual conflict resolution stripped the
consumer-specific text back out. Decoupling is the only mechanism that
preserves this repository’s value as shared infrastructure.</p>
<p><strong>Recursive scope:</strong> any submodule this repository
consumes inherits the same decoupling+reusability rule. Third-party
upstream submodules that this repository merely vendors
(e.g. open-source tools under a <code>tools/opensource/</code> tree, if
present) are explicitly out of scope — we are not their owners.</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>
</tr>
<tr>
<td><strong>Cascade requirement:</strong> This anchor (verbatim or by
<code>CONST-051</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
codebase-completeness layer. No escape hatch. See constitution submodule
<code>Constitution.md</code> §11.4.28 for the full mandate (audit gates,
mutation pairs, workflow integration).</td>
</tr>
</tbody>
</table>
<h2 id="amendment-process">Amendment Process</h2>
<p>Constitution amendments require: 1. Written proposal with rationale
2. Challenge demonstrating the need 3. 72-hour review period 4. Approval
by project architect 5. Update to all submodule governance files</p>
<hr />
<p><em>This Constitution is the supreme law of the HelixCode project. No
code, test, or process may contradict it.</em></p>
<h2
id="const-052-lowercase-snake_case-naming-mandate-cascaded-from-constitution-submodule-11.4.29">CONST-052:
Lowercase-Snake_Case-Naming Mandate (cascaded from constitution
submodule §11.4.29)</h2>
<blockquote>
<p>Verbatim user mandate (2026-05-15): *“naming convention for
Submodules and directories (applied deep into hierarchy recursively) -
all directories and Submodules MSUT HAVE lowercase names with space
separator between the words of ’_’ character (snake-case)! All existing
Submodules and directories which are not following this rule MUST BE
renamed! However, since this will most likely break some of the
functionalities renaming we do MUST BE applied to all references to
particular Submodule or directory! … There MUST BE reasonable exceptions
for this rules - source code for programming languages or Submodules
which apply different naming convention - Android, Java, Kotlin and
others. … Upstreams directory which all of our projects and Submodules
have MUST BE renamed to the lowercase letters too, however root project
containing the install_upstreams system command (it is exported in out
paths in our .bashrc or .zshrc) MUST BE updated to fully work with both
Upstreams and upstreams directory. … NOTE: Rules lowercase / snake-case
do apply to all project files as well and references to it and from
them!“*</p>
</blockquote>
<p>Every directory, submodule, and file in HelixCode MUST use lowercase
snake_case names. Existing non-compliant names (<code>HelixCode/</code>,
<code>Challenges/</code>, <code>Containers/</code>,
<code>HelixAgent/</code>, <code>HelixQA/</code>, <code>Security/</code>,
<code>Github-Pages-Website/</code>, <code>Upstreams/</code>,
<code>Dependencies/</code>, etc.) MUST be renamed as part of the phased
migration opened by this clause. Every reference (configs, docs, links,
source-code imports, governance files) MUST be updated atomically with
the rename — reference drift after a rename is a CONST-052 violation of
equal severity to the rename itself.</p>
<p><strong>Common-sense exceptions (technology-preserving):</strong>
language-mandated case for Java/Kotlin/Android/Apple/C#/Swift INSIDE the
language root (submodule root follows our convention; subtree follows
language convention); vendor/upstream third-party submodules keep
upstream names; build artefacts (<code>node_modules</code>,
<code>__pycache__</code>, <code>.git</code>, <code>target</code>,
<code>build</code>, <code>bin</code>) keep tool-mandated names. The test
“does renaming break the technology?” trumps the rule.</p>
<p><strong><code>Upstreams/</code> → <code>upstreams/</code>
transition:</strong> the constitution submodule’s
<code>install_upstreams.sh</code> (exported via
<code>.bashrc</code>/<code>.zshrc</code>) supports BOTH
<code>Upstreams/</code> and <code>upstreams/</code> directory layouts
(commit <code>45d3678</code> of the constitution submodule); lowercase
wins when both present.</p>
<p><strong>Test coverage of renames</strong> (per CONST-050(B)): every
rename batch ships with (i) regression test verifying every reference
now resolves, (ii) full test-type matrix run post-rename, (iii)
anti-bluff wire-evidence captured.</p>
<p><strong>Phased execution</strong> per the operator’s explicit
instruction: comprehensive brainstorming → phase-divided plan →
fine-grained tasks/subtasks → every change covered by every applicable
test type. §11.4.20 subagent delegation for cross-cutting rename
sweeps.</p>
<p><strong>Cascade requirement:</strong> This anchor (verbatim or by
<code>CONST-052</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
reference-integrity layer. No escape hatch beyond the common-sense
exceptions enumerated above. See constitution submodule
<code>Constitution.md</code> §11.4.29 for the full mandate.</p>
<h2
id="const-053-.gitignore-no-versioned-build-artifacts-mandate-cascaded-from-constitution-submodule-11.4.30">CONST-053:
.gitignore + No-Versioned-Build-Artifacts Mandate (cascaded from
constitution submodule §11.4.30)</h2>
<blockquote>
<p>Verbatim user mandate (2026-05-15): <em>“every project module, every
Submodule, every servcie and apolication MUST HAVE proper .gitignore
file! We MUST NOT git version build artifacts, cache files, tmp files,
main .env file(s) or any files containing sensitive data, API keys or
token! Any build derivate which we can recreate by executing proper
mechanism for generating MUST NOT be versioned! We MUST pay attention
what is going to be commited every time we are preparing to execute
commit! If any violetion is detected it MUST be fixed before commit is
executed!”</em></p>
</blockquote>
<p>Every project module, owned-by-us submodule, service, and application
MUST ship a proper <code>.gitignore</code>.
Forbidden-from-version-control classes:</p>
<ol type="1">
<li><strong>Build artefacts</strong>: <code>/bin/</code>,
<code>/build/</code>, <code>/dist/</code>, <code>/out/</code>,
<code>target/</code>, <code>*.exe</code>, <code>*.dll</code>,
<code>*.so</code>, <code>*.dylib</code>, <code>*.a</code>,
<code>*.o</code>, <code>*.class</code>, <code>*.pyc</code>,
generator-produced files when the generator is committed.</li>
<li><strong>Cache files</strong>: <code>__pycache__/</code>,
<code>.pytest_cache/</code>, <code>.mypy_cache/</code>,
<code>.ruff_cache/</code>, <code>node_modules/</code>,
<code>.next/</code>, <code>.cache/</code>, <code>.gradle/</code>,
<code>.terraform/</code>, language-server caches.</li>
<li><strong>Temp files</strong>: <code>*.tmp</code>, <code>*.swp</code>,
<code>*~</code>, <code>.DS_Store</code>, <code>Thumbs.db</code>,
<code>*.orig</code>, <code>*.rej</code>.</li>
<li><strong>Sensitive-data files</strong>: <code>.env</code>,
<code>.env.*</code> (allow <code>.env.example</code> placeholder only —
no real secrets even as examples), <code>*.pem</code>,
<code>*.key</code>, <code>*.crt</code>, <code>id_rsa*</code>,
<code>id_ed25519*</code>, <code>.netrc</code>, <code>secrets/</code>,
<code>api_keys.sh</code>.</li>
<li><strong>Generated reports/logs</strong>: <code>*.log</code>,
<code>coverage.out</code>, <code>htmlcov/</code>, runtime captures
unless reference assets.</li>
<li><strong>OS/IDE personal state</strong>: <code>.idea/</code>,
<code>.history/</code>, <code>.vscode/</code> (except shared
settings).</li>
</ol>
<p><strong>Anti-bluff invariant</strong>: <code>.gitignore</code> line
alone is not sufficient — no file matching the forbidden patterns may be
CURRENTLY TRACKED. A tracked <code>*.log</code> despite the ignore-line
is a violation of equal severity to no ignore-line at all.</p>
<p><strong>Pre-commit attention</strong>: every commit author (human OR
agent) MUST inspect <code>git diff --staged</code> +
<code>git status</code> BEFORE executing the commit. Forbidden-class
hits abort the commit until fixed (un-stage, add to
<code>.gitignore</code>, scrub if already-tracked). Gate
<code>CM-GITIGNORE-PRECOMMIT-AUDIT</code> + paired mutation.</p>
<p><strong>Secret-leak intersection (CONST-042 / §11.4.10):</strong> a
<code>.env</code> leak is BOTH a CONST-053 and a CONST-042 violation;
rotation + post-mortem required.</p>
<p><strong>Recreatable-content test</strong>: if a documented mechanism
regenerates the file from sources, it is a build derivative and MUST be
ignored. The committed sources MUST include the generator.</p>
<p><strong>Cascade requirement:</strong> This anchor (verbatim or by
<code>CONST-053</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
repository-hygiene layer. See constitution submodule
<code>Constitution.md</code> §11.4.30 for the full mandate.</p>
<h2
id="const-054-submodule-dependency-manifest-mandate-cascaded-from-constitution-submodule-11.4.31">CONST-054:
Submodule-Dependency-Manifest Mandate (cascaded from constitution
submodule §11.4.31)</h2>
<blockquote>
<p>Verbatim user mandate (2026-05-15): <em>“We MUST HAVE mechanism for
each Submodule to determine / know what are its Submodule dependencies
so new projects or palces we are incorporate them can add these
Submodules to the project root and make them available! Suggested idea
is configuration file with expected Submodules Git ssh urls perhaps? New
project can read it, and recursively add each Submodule to the root of
the project and install / expose it to veryone.”</em></p>
</blockquote>
<p>Every owned-by-us submodule MUST ship <code>helix-deps.yaml</code> at
its root declaring its own-org dependencies. Schema:
<code>schema_version</code>,
<code>deps: [{name, ssh_url, ref, why, layout: flat|grouped}]</code>,
<code>transitive_handling.{recursive,conflict_resolution}</code>,
<code>language_specific_subtree</code>. Tooling:
<code>incorporate-submodule <ssh-url></code> adds the submodule at
the parent project’s canonical path (CONST-051(C)), reads
<code>helix-deps.yaml</code>, recurses for each declared dep, aborts on
conflicting refs, emits <code><root>/.helix-manifest.yaml</code>
audit record.</p>
<p>Anti-bluff guarantee: every manifest paired with a Challenge that
bootstraps a throwaway consuming project, runs
<code>incorporate-submodule</code>, asserts produced layout matches the
manifest, runs the submodule’s own tests against the bootstrapped
layout, captures wire evidence per §11.4.2. A manifest without this
proof is a CONST-054 violation.</p>
<p>§11.4.31 / CONST-054 is the <strong>operational complement</strong>
of CONST-051(C): nested own-org submodule chains are FORBIDDEN —
manifests are the bridge that lets consumers reconstruct the dependency
graph at the parent root.</p>
<p><strong>Cascade requirement:</strong> This anchor (verbatim or by
<code>CONST-054</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 §11.4 PASS-bluff at the
dependency-graph layer. See constitution submodule
<code>Constitution.md</code> §11.4.31 for the full mandate.</p>
<h2
id="const-055-post-constitution-pull-validation-mandate-cascaded-from-constitution-submodule-11.4.32">CONST-055:
Post-Constitution-Pull Validation Mandate (cascaded from constitution
submodule §11.4.32)</h2>
<blockquote>
<p>Verbatim user mandate (2026-05-15): <em>“Every time we fetch and pull
new changes on constitution Submodule we MUST process the whole project
and all Submodule (deep recursively) for validation and verification
taht every single rule or mandatory constraint is followed and
respected! If it is not, IT MUST BE!”</em></p>
</blockquote>
<p>Whenever a project’s constitution submodule is fetched + pulled with
any content change, the project MUST run