1  # Build-Test-Ground Protocol
  2  
  3  *proto-023 | Making builds traceable, testable, and provable*
  4  
  5  ---
  6  
  7  - **principle**
  8    - "Every build must ground. Build → Test → Document → Link → Prove."
  9    - "The protocol isn't built until it's proven to work."
 10  
 11  - **shape**
 12    - Build creates artifact
 13    - Test validates function
 14    - Documentation captures results
 15    - Links connect build to evidence
 16    - Proof chain enables traceability
 17    - Protocol → Manifestation → Process → Proof
 18  
 19  ---
 20  
 21  ## Core Principle
 22  
 23  > **"I need to be able to click through and say, 'Oh, we built this protocol. This protocol manifested in these forms, in these processes. These processes are proved to be working in this manner.'"**
 24  
 25  Every build creates artifacts. Those artifacts must be:
 26  1. **Tested** - Does it work?
 27  2. **Documented** - What happened when we tested it?
 28  3. **Linked** - How does this connect to what we built?
 29  4. **Traceable** - Can we navigate from concept to proof?
 30  
 31  This is the **grounding** requirement. Ideas that don't ground are ornament (A2 violation).
 32  
 33  ---
 34  
 35  ## The Grounding Chain
 36  
 37  ```
 38  CONCEPT (abstract)
 39      │
 40      ▼
 41  [[protocol-name]]
 42      │
 43      ▼
 44  MANIFESTATION (concrete)
 45      │
 46      ├──► Implementation A (code)
 47      │    └──► Test results: tests/protocol-name-test.md
 48      │
 49      ├──► Implementation B (process)
 50      │    └──► Test results: sessions/protocol-name-validation.md
 51      │
 52      └──► Implementation C (pattern)
 53           └──► Test results: patterns/protocol-name-test-record.md
 54                │
 55                ▼
 56           PROOF (evidence)
 57                └──► "This works because [evidence]"
 58  ```
 59  
 60  **Bidirectional linking enables graph walk:**
 61  - From protocol → find all manifestations
 62  - From manifestation → find test results
 63  - From test results → find evidence
 64  - From evidence → validate protocol
 65  
 66  ---
 67  
 68  ## When to Test (Trigger Conditions)
 69  
 70  ### Mandatory Triggers
 71  
 72  | Trigger | When | What to Test |
 73  |---------|------|--------------|
 74  | **New protocol documented** | Pattern file created | Does the protocol make sense? Can it be followed? |
 75  | **Protocol implemented** | Code/process/artifact created | Does it work as specified? |
 76  | **Protocol updated** | Changes to existing protocol | Does update break anything? Improve things? |
 77  | **Compression event** | Context switch, handoff | Does Phoenix state resurrect correctly? |
 78  | **Integration point** | Two systems connect | Do boundaries respect each other? |
 79  
 80  ### Optional Triggers
 81  
 82  | Trigger | When | What to Test |
 83  |---------|------|--------------|
 84  | **Axiom alignment check** | Regular review | Does implementation still align with axioms? |
 85  | **Performance question** | Speed/resource concern | Measure actual vs expected |
 86  | **User reports drift** | "This doesn't feel right" | Test against original intent |
 87  
 88  ---
 89  
 90  ## How to Test (Test Format)
 91  
 92  ### The Test Record Format
 93  
 94  Every test creates a **test record** file with this structure:
 95  
 96  ```markdown
 97  # Test Record: [Protocol/Feature Name]
 98  
 99  **Date:** YYYY-MM-DD
100  **Tester:** [Who ran the test]
101  **Version:** [What version of the thing being tested]
102  **Test Type:** [Unit | Integration | Validation | Axiom Alignment]
103  
104  ---
105  
106  ## What Was Tested
107  
108  [Description of what's being tested and why]
109  
110  **Links to:**
111  - [[protocol-name]] - The protocol this implements
112  - [[related-concept]] - Related concepts
113  - `path/to/implementation` - The actual code/artifact
114  
115  ---
116  
117  ## Test Plan
118  
119  ### Test Cases
120  
121  | ID | Test | Expected | Actual | Status | Evidence |
122  |----|------|----------|--------|--------|----------|
123  | T1 | [What you're testing] | [What should happen] | [What did happen] | PASS/FAIL | [Link to output/screenshot/log] |
124  | T2 | [Test 2] | [Expected] | [Actual] | PASS/FAIL | [Evidence] |
125  | T3 | [Test 3] | [Expected] | [Actual] | PASS/FAIL | [Evidence] |
126  
127  ---
128  
129  ## Test Execution
130  
131  ### Setup
132  ```
133  [Commands/steps to set up test environment]
134  ```
135  
136  ### Run
137  ```
138  [Commands/steps to run test]
139  ```
140  
141  ### Teardown
142  ```
143  [Commands/steps to clean up]
144  ```
145  
146  ---
147  
148  ## Results Summary
149  
150  **Overall Status:** PASS / PARTIAL / FAIL / BLOCKED
151  
152  **Passed:** [X/Y tests]
153  **Failed:** [Z tests]
154  **Blocked:** [N tests - couldn't run]
155  
156  ### What Worked
157  - [Success 1]
158  - [Success 2]
159  
160  ### What Failed
161  - [Failure 1]: [Why it failed]
162  - [Failure 2]: [Why it failed]
163  
164  ### What Was Learned
165  - [Insight 1]
166  - [Insight 2]
167  
168  ---
169  
170  ## Axiom Alignment (Required for protocols)
171  
172  | Axiom | Alignment Check | Status | Notes |
173  |-------|----------------|--------|-------|
174  | [[A0 Boundary Operation]] | Does this respect boundaries? | ✓/✗ | [How it aligns or doesn't] |
175  | [[A1 Telos of Integration]] | Does this enable connection? | ✓/✗ | [How it aligns or doesn't] |
176  | [[A2 Recognition of Life]] | Does this favor primitive over calcified? | ✓/✗ | [How it aligns or doesn't] |
177  | [[A3 Dynamic Pole Navigation]] | Does this navigate dynamically? | ✓/✗ | [How it aligns or doesn't] |
178  
179  **Free Energy (F):** [0-1 score]
180  - F < 0.10 = aligned
181  - F 0.10-0.25 = minor deviation
182  - F > 0.25 = needs attention
183  
184  ---
185  
186  ## Proof Chain
187  
188  **This test proves:**
189  - [[protocol-name]] → manifested as → `implementation-path`
190  - `implementation-path` → validated by → this test record
191  - Test shows: [key finding]
192  
193  **Graph edges created:**
194  - [[protocol-name]] --implements--> [[implementation-name]]
195  - [[implementation-name]] --tested-by--> [[this-test-record]]
196  - [[this-test-record]] --proves--> [[capability-demonstrated]]
197  
198  ---
199  
200  ## Next Actions
201  
202  - [ ] [Action 1 based on test results]
203  - [ ] [Action 2]
204  - [ ] [If failed: what needs fixing]
205  - [ ] [If passed: what's next step]
206  
207  ---
208  
209  ## Related
210  - [[protocol-name]] - the thing being tested
211  - [[previous-test-record]] - if this is a retest
212  - [[related-pattern]] - patterns this validates
213  
214  ---
215  
216  *Test completed: YYYY-MM-DD*
217  ```
218  
219  ---
220  
221  ## How to Document Results
222  
223  ### Test Record Storage
224  
225  | Artifact Type | Test Record Location |
226  |---------------|---------------------|
227  | **Protocol** | `patterns/[protocol-name]-test-record.md` |
228  | **Code implementation** | `tests/[feature-name]-test.md` |
229  | **Process validation** | `sessions/[process-name]-validation.md` |
230  | **Integration test** | `tests/integration/[systems]-test.md` |
231  | **Axiom alignment** | `docs/principles/[concept]-axiom-test.md` |
232  
233  ### Evidence Storage
234  
235  | Evidence Type | Storage Location |
236  |---------------|-----------------|
237  | **Command output** | Inline in test record (code blocks) |
238  | **Screenshots** | `tests/evidence/[test-id]-screenshot.png` |
239  | **Log files** | `tests/evidence/[test-id]-log.txt` |
240  | **Generated artifacts** | `tests/evidence/[test-id]-artifact.*` |
241  | **Performance data** | `tests/evidence/[test-id]-metrics.json` |
242  
243  ---
244  
245  ## How to Link Results to Builds
246  
247  ### Bidirectional Wiki-Links
248  
249  **In the protocol file:**
250  ```markdown
251  ## Implementations
252  
253  This protocol has been implemented as:
254  - [[implementation-name-1]] - tested in [[test-record-1]]
255  - [[implementation-name-2]] - tested in [[test-record-2]]
256  
257  ## Test Results
258  - [[test-record-1]] - PASS - proves this works for use case X
259  - [[test-record-2]] - PARTIAL - works with caveat Y
260  ```
261  
262  **In the implementation file:**
263  ```markdown
264  ## This Implements
265  - [[protocol-name]] - the protocol this follows
266  
267  ## Test Evidence
268  - [[test-record-name]] - validation of this implementation
269  - Status: PASS/PARTIAL/FAIL
270  - Evidence: [link to specific output]
271  ```
272  
273  **In the test record:**
274  ```markdown
275  ## What Was Tested
276  - [[protocol-name]] - the protocol
277  - [[implementation-name]] - the manifestation
278  
279  ## This Proves
280  - Protocol works: ✓
281  - Edge cases handled: ✓
282  - Performance acceptable: ✓
283  ```
284  
285  ### Graph Navigation Patterns
286  
287  **From Protocol to Proof:**
288  ```
289  1. Open [[protocol-name]]
290  2. See "Implementations" section
291  3. Click [[implementation-name]]
292  4. See "Test Evidence" section
293  5. Click [[test-record]]
294  6. See proof with actual evidence
295  ```
296  
297  **From Evidence to Protocol:**
298  ```
299  1. Find test-record-name.md
300  2. See "What Was Tested" section
301  3. Click [[protocol-name]]
302  4. Understand why this was built
303  5. See all other implementations
304  ```
305  
306  **Cross-Thread Discovery:**
307  ```
308  1. In session, mention "we tested X"
309  2. Link to [[test-record]]
310  3. Later sessions can click through
311  4. Find the protocol, the implementation, the proof
312  5. Full context recovered
313  ```
314  
315  ---
316  
317  ## Grounding Protocol (Protocol → Code → Test → Proof)
318  
319  ### Phase 1: Build
320  ```markdown
321  You've created a protocol/feature/implementation.
322  
323  REQUIRED OUTPUTS:
324  1. The artifact itself (code, doc, pattern)
325  2. Declaration of what this implements: [[protocol-name]]
326  3. Test plan (what will prove this works)
327  ```
328  
329  ### Phase 2: Test
330  ```markdown
331  Run the tests according to the test plan.
332  
333  REQUIRED OUTPUTS:
334  1. Test record file (using format above)
335  2. Evidence (logs, outputs, screenshots)
336  3. Status determination (PASS/PARTIAL/FAIL/BLOCKED)
337  ```
338  
339  ### Phase 3: Document
340  ```markdown
341  Create bidirectional links.
342  
343  IN THE PROTOCOL:
344  - Link to implementation
345  - Link to test record
346  - Status summary
347  
348  IN THE IMPLEMENTATION:
349  - Link back to protocol
350  - Link to test record
351  - Proof claim
352  
353  IN THE TEST RECORD:
354  - Link to protocol
355  - Link to implementation
356  - Evidence included
357  ```
358  
359  ### Phase 4: Prove
360  ```markdown
361  The proof chain is complete when:
362  
363  ✓ Protocol exists and documented
364  ✓ Implementation exists and linked
365  ✓ Test record exists and linked
366  ✓ Evidence is captured and accessible
367  ✓ Graph walk works: protocol → impl → test → proof → protocol
368  
369  USER CAN NOW:
370  1. Start at protocol
371  2. Click to implementation
372  3. Click to test record
373  4. See evidence that it works
374  5. Trust the build is grounded
375  ```
376  
377  ---
378  
379  ## Example: First Officer Protocol
380  
381  ### The Protocol
382  File: `patterns/first-officer-protocol.md`
383  
384  Contains:
385  ```markdown
386  ## Implementations
387  - [[FO-implementation-2026-01-15]] - checkpoint-based architecture
388    - Tested in [[FO-test-record-2026-01-15]]
389    - Status: OPERATIONAL
390    - Proves: Checkpoint model works, Phoenix state sufficient
391  ```
392  
393  ### The Implementation
394  File: `sessions/FO-implementation-2026-01-15.md`
395  
396  Contains:
397  ```markdown
398  ## This Implements
399  - [[first-officer-protocol]] - per-thread metacognition
400  
401  ## Test Record
402  - [[FO-test-record-2026-01-15]]
403  - Status: PASS (9/10 tests)
404  - Evidence: sessions/FO-checkpoint-output.log
405  ```
406  
407  ### The Test Record
408  File: `tests/FO-test-record-2026-01-15.md`
409  
410  Contains:
411  ```markdown
412  # Test Record: First Officer Protocol
413  
414  ## What Was Tested
415  - [[first-officer-protocol]] - The protocol
416  - [[FO-implementation-2026-01-15]] - The checkpoint-based implementation
417  
418  ## Test Plan
419  
420  | ID | Test | Expected | Actual | Status |
421  |----|------|----------|--------|--------|
422  | T1 | Spawn FO at checkpoint | FO runs, updates LIVE-COMPRESSION.md | FO ran, file updated | PASS |
423  | T2 | Detect thread branch | FO flags branch opportunity | Detected "model allocation" branch | PASS |
424  | T3 | Calculate urgency | U > 0.8 triggers bubble | U = 0.85, bubble appeared | PASS |
425  
426  ## Evidence
427  See: sessions/FO-checkpoint-output.log
428  ```
429  
430  ### The Proof
431  User can now:
432  1. Read [[first-officer-protocol]]
433  2. Click to [[FO-implementation-2026-01-15]]
434  3. Click to [[FO-test-record-2026-01-15]]
435  4. See actual evidence it works
436  5. Trust that FO is grounded, not just theory
437  
438  ---
439  
440  ## Test Against Axioms (Required)
441  
442  Every protocol test MUST include axiom alignment check.
443  
444  ### Axiom Test Format
445  
446  ```markdown
447  ## Axiom Alignment
448  
449  ### [[A0 Boundary Operation]]
450  **Question:** Does this respect boundaries?
451  **Test:** [Specific test of boundary respect]
452  **Result:** PASS/FAIL
453  **Alignment:** [How this aligns with A0]
454  **Link Created:** [[protocol-name]] --respects-boundary--> [[A0 Boundary Operation]]
455  
456  ### [[A1 Telos of Integration]]
457  **Question:** Does this enable connection?
458  **Test:** [Specific test of integration]
459  **Result:** PASS/FAIL
460  **Alignment:** [How this aligns with A1]
461  **Link Created:** [[protocol-name]] --enables-integration--> [[A1 Telos of Integration]]
462  
463  ### [[A2 Recognition of Life]]
464  **Question:** Does this favor primitive over calcified?
465  **Test:** [Specific test of life recognition]
466  **Result:** PASS/FAIL
467  **Alignment:** [How this aligns with A2]
468  **Link Created:** [[protocol-name]] --recognizes-life--> [[A2 Recognition of Life]]
469  
470  ### [[A3 Dynamic Pole Navigation]]
471  **Question:** Does this navigate dynamically?
472  **Test:** [Specific test of navigation]
473  **Result:** PASS/FAIL
474  **Alignment:** [How this aligns with A3]
475  **Link Created:** [[protocol-name]] --navigates-poles--> [[A3 Dynamic Pole Navigation]]
476  
477  ### Free Energy Calculation
478  F = (ΔA0 + ΔA1 + ΔA2 + ΔA3) / 4
479  
480  Where Δ = deviation from axiom (0 = perfect, 1 = complete violation)
481  
482  **Result:** F = [score]
483  **Status:** [ALIGNED / MINOR_DEVIATION / NEEDS_ATTENTION / CRITICAL]
484  ```
485  
486  ---
487  
488  ## Axiom-Specific Tests
489  
490  ### A0: Boundary Operation
491  
492  **What to test:**
493  - Does it respect content sovereignty?
494  - Are boundaries clearly defined?
495  - Does information cross appropriately?
496  - Is the Markov blanket structure honored?
497  
498  **Test examples:**
499  ```markdown
500  | Test | Pass Criteria | Evidence |
501  |------|---------------|----------|
502  | Content stays within boundary | No leakage to external systems | Check logs for data flow |
503  | Structure can flow | Patterns shared without content | Verify only metadata crosses |
504  | Boundary is explicit | Clear in/out/cross definition | Review code for boundary markers |
505  ```
506  
507  ### A1: Telos of Integration
508  
509  **What to test:**
510  - Does this enable connection?
511  - Does it prevent isolation?
512  - Is sovereignty maintained WITH relation?
513  - Does it support binding?
514  
515  **Test examples:**
516  ```markdown
517  | Test | Pass Criteria | Evidence |
518  |------|---------------|----------|
519  | Enables connection | Systems can integrate | Verify handoff works |
520  | Prevents isolation | No dead-end states | Check for unreachable nodes |
521  | Maintains sovereignty | No forced merging | Verify opt-in model |
522  ```
523  
524  ### A2: Recognition of Life
525  
526  **What to test:**
527  - Does it favor simple over complex?
528  - Can it detect calcification?
529  - Does it preserve motion?
530  - Does it see through ornament?
531  
532  **Test examples:**
533  ```markdown
534  | Test | Pass Criteria | Evidence |
535  |------|---------------|----------|
536  | Primitive preferred | Simple solution chosen | Code review: LOC, dependencies |
537  | Detects sclerosis | Flags accumulated cruft | Lint reports, complexity metrics |
538  | Preserves motion | Not frozen at pole | State can change |
539  ```
540  
541  ### A3: Dynamic Pole Navigation
542  
543  **What to test:**
544  - Does it acknowledge tensions as dyads?
545  - Does it navigate based on context?
546  - Does it avoid fixing at poles?
547  - Does it consider shadow pole?
548  
549  **Test examples:**
550  ```markdown
551  | Test | Pass Criteria | Evidence |
552  |------|---------------|----------|
553  | Recognizes dyad | Both poles identified | Documentation mentions tension |
554  | Context-driven | Different choice in different situation | Test cases with varying context |
555  | Avoids fixation | Can move between poles | State transitions exist |
556  ```
557  
558  ---
559  
560  ## Failures & Solutions Pattern
561  
562  ### Track What Went Wrong
563  
564  ```markdown
565  ## Failures Encountered
566  
567  ### Failure 1: [Name]
568  **What failed:** [Description]
569  **Why it failed:** [Root cause]
570  **How we detected it:** [Test that caught it]
571  **How we solved it:** [Solution]
572  **Prevention:** [How to avoid this in future]
573  **Link:** [[failure-pattern-name]] - if this is a known pattern
574  
575  ### Failure 2: [Name]
576  [Same structure]
577  ```
578  
579  ### Build Failure Library
580  
581  Create failure pattern files when same failure repeats:
582  
583  ```markdown
584  # Failure Pattern: [Name]
585  
586  **Category:** [Integration / Boundary / Performance / Logic]
587  **Frequency:** [How often this occurs]
588  **Severity:** [Critical / High / Medium / Low]
589  
590  ## Symptoms
591  - [How this manifests]
592  - [What user experiences]
593  
594  ## Root Cause
595  [Why this happens]
596  
597  ## Detection
598  [How to detect this]
599  
600  ## Solution
601  [How to fix this]
602  
603  ## Prevention
604  [How to avoid this]
605  
606  ## Related
607  - [[similar-failure-pattern]]
608  - [[protocol-this-violates]]
609  
610  ## Occurrences
611  - [[test-record-1]] - first seen
612  - [[test-record-2]] - occurred again
613  ```
614  
615  ---
616  
617  ## Operational Checklist
618  
619  ### Before You Build
620  - [ ] Is there a protocol for this? If not, should there be?
621  - [ ] What axioms does this relate to?
622  - [ ] What will prove this works?
623  
624  ### While You Build
625  - [ ] Document what protocol this implements
626  - [ ] Note design decisions (for test context)
627  - [ ] Create test plan
628  
629  ### After You Build
630  - [ ] Run tests (create test record)
631  - [ ] Capture evidence
632  - [ ] Check axiom alignment
633  - [ ] Create bidirectional links
634  - [ ] Update protocol with implementation status
635  
636  ### Verification (Graph Walk)
637  - [ ] Can navigate: protocol → implementation → test → proof
638  - [ ] Can navigate: test → implementation → protocol
639  - [ ] Evidence is accessible (not broken links)
640  - [ ] Status is clear (PASS/PARTIAL/FAIL)
641  
642  ---
643  
644  ## Integration with Existing Protocols
645  
646  ### With [[axiom-conformance-test]]
647  - Build-Test-Ground creates test records
648  - Axiom conformance is part of every test
649  - F score calculated and documented
650  - Links to axioms created
651  
652  ### With [[mandatory-phoenix-extraction]]
653  - Test that Phoenix state can resurrect
654  - Resurrection is a testable claim
655  - Evidence: "spawned new instance, gave it Phoenix state, it continued correctly"
656  
657  ### With [[first-officer-protocol]]
658  - FO can request tests
659  - FO can run test checklists
660  - FO documents test results in LIVE-COMPRESSION
661  - Test records link to session where test occurred
662  
663  ### With [[flight-protocol]]
664  - "Where are we?" includes test status
665  - Plan includes "what needs testing"
666  - Landing sequence includes "run tests"
667  
668  ---
669  
670  ## The Promise
671  
672  > **Every build becomes traceable.**
673  >
674  > You can click from concept to proof.
675  > You can verify claims with evidence.
676  > You can see what works and what doesn't.
677  > You can trust the build is grounded.
678  >
679  > Protocol → Manifestation → Process → Proof
680  > The graph makes it navigable.
681  > The tests make it real.
682  
683  ---
684  
685  ## Minimal Viable Test (MVT)
686  
687  If full test record feels heavy, use MVT:
688  
689  ```markdown
690  # MVT: [Name]
691  
692  **Tests:** [[protocol-name]]
693  **Date:** YYYY-MM-DD
694  
695  | What | Expected | Actual | Status |
696  |------|----------|--------|--------|
697  | [Test 1] | [Expected] | [Actual] | ✓/✗ |
698  | [Test 2] | [Expected] | [Actual] | ✓/✗ |
699  
700  **Result:** PASS/FAIL
701  **Evidence:** [one-line proof]
702  
703  **Axioms:** F = [score] (A0: ✓, A1: ✓, A2: ✓, A3: ✓)
704  
705  **Links:**
706  - [[protocol-name]] - what this tests
707  - [[implementation]] - what was tested
708  ```
709  
710  **Use MVT when:**
711  - Simple feature
712  - Low risk
713  - High confidence
714  - Quick validation needed
715  
716  **Use full test record when:**
717  - Complex feature
718  - High risk
719  - New pattern
720  - Integration point
721  - Axiom alignment unclear
722  
723  ---
724  
725  ## Related
726  
727  - **axioms**
728    - [[A0 Boundary Operation]] - test boundary respect
729    - [[A1 Telos of Integration]] - test connection enabling
730    - [[A2 Recognition of Life]] - test primitive vs calcified
731    - [[A3 Dynamic Pole Navigation]] - test dynamic movement
732  - **protocols**
733    - [[axiom-conformance-test]] - the conscience check for every response
734      - shape:: "Test against axioms before substantive responses."
735    - [[mandatory-phoenix-extraction]] - test that resurrection works
736      - shape:: "Extract before compression. The next instance depends on it."
737    - [[first-officer-protocol]] - FO coordinates testing
738      - shape:: "Per-thread metacognition. First Officer handles testing coordination."
739    - [[flight-protocol]] - testing is part of landing
740      - shape:: "Fly high, system retains, land with proof."
741  - **patterns**
742    - [[building-as-cognition]] - building IS a form of testing
743      - shape:: "Build to understand. Artifacts are hypotheses made concrete."
744  - **enables**
745    - Graph navigation: concept → implementation → proof
746    - Trust through evidence
747    - Failure learning
748    - Pattern library growth
749  
750  ---
751  
752  ## Test Record
753  
754  **This protocol has been tested:**
755  - [[build-test-ground-protocol-test-record]] - PASS (10/10 tests, F = 0.0125)
756    - Meta-test: protocol tested using its own format
757    - Proves: Protocol is followable, complete, aligned, and usable
758    - Evidence: Test record file itself demonstrates the protocol works
759  
760  ---
761  
762  *proto-023 | Build-Test-Ground Protocol | Making Builds Traceable*