Governance and Requirements Tracking

<h3 id="overview" class="position-relative d-flex align-items-center group"> Overview <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="overview" aria-haspopup="dialog" aria-label="Share link: Overview"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script>Geode’s CANARY governance system provides comprehensive requirements tracking with 1,735 markers tracking 2,190+ requirements. This evidence-based development methodology ensures traceability, automated verification, and compliance throughout the software lifecycle. <h4 id="key-features" class="position-relative d-flex align-items-center group"> Key Features <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="key-features" aria-haspopup="dialog" aria-label="Share link: Key Features"> Share link </button> </h4><ul> <li>1,735 CANARY Markers: Comprehensive requirements tracking across codebase</li> <li>Automated Verification: Continuous validation of evidence integrity</li> <li>Evidence Ledger: Machine-extracted status with freshness tracking</li> <li>Governance Pipeline: Multi-step automated checks with JSON output</li> <li>Variance Guards: Performance envelope monitoring with floor assertions</li> <li>Gap Analysis: Structured documentation synchronization</li> </ul> <h3 id="canary-system-fundamentals" class="position-relative d-flex align-items-center group"> CANARY System Fundamentals <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="canary-system-fundamentals" aria-haspopup="dialog" aria-label="Share link: CANARY System Fundamentals"> Share link </button> </h3> <h4 id="what-is-a-canary-marker" class="position-relative d-flex align-items-center group"> What is a CANARY Marker? <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="what-is-a-canary-marker" aria-haspopup="dialog" aria-label="Share link: What is a CANARY Marker?"> Share link </button> </h4>CANARY markers are structured comments in source code that link implementation to requirements, tests, and benchmarks. They provide bidirectional traceability between requirements and evidence. Format: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// CANARY: REQ=REQ-XXX; FEATURE="FeatureName"; ASPECT=AspectName; STATUS=TESTED; TEST=TestName; OWNER=team; UPDATED=2026-01-24 </code></pre></div>Components: <ul> <li>REQ: Requirement identifier (e.g., REQ-GQL-010)</li> <li>FEATURE: Feature name for grouping</li> <li>ASPECT: Specific aspect being implemented</li> <li>STATUS: Implementation status (STUB, IMPL, TESTED, BENCHED, EXEMPT, COMPLETE)</li> <li>TEST: Test name(s) for verification</li> <li>BENCH: Benchmark name(s) for performance validation</li> <li>OWNER: Responsible team/component</li> <li>UPDATED: Last modification date (YYYY-MM-DD)</li> </ul> <h4 id="status-progression" class="position-relative d-flex align-items-center group"> Status Progression <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="status-progression" aria-haspopup="dialog" aria-label="Share link: Status Progression"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-plaintext" data-lang="plaintext">STUB → IMPL → TESTED → BENCHED → COMPLETE STUB: Placeholder, not yet implemented IMPL: Implemented but not tested TESTED: Implementation + tests passing BENCHED: Tested + performance validated COMPLETE: Fully validated, production-ready EXEMPT: Special cases (external dependencies, etc.) </code></pre></div> <h4 id="current-statistics" class="position-relative d-flex align-items-center group"> Current Statistics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="current-statistics" aria-haspopup="dialog" aria-label="Share link: Current Statistics"> Share link </button> </h4>As of January 2026: <ul> <li>Total Markers: 1,735</li> <li>Total Requirements: 2,190+</li> <li>TESTED Status: 81.4%</li> <li>BENCHED Status: 6.0%</li> <li>EXEMPT Status: 7.7%</li> <li>IMPL Status: 5.7%</li> <li>Test Pass Rate: 97.4% (1644/1688 tests)</li> </ul> <h3 id="evidence-ledger" class="position-relative d-flex align-items-center group"> Evidence Ledger <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="evidence-ledger" aria-haspopup="dialog" aria-label="Share link: Evidence Ledger"> Share link </button> </h3> <h4 id="automated-generation" class="position-relative d-flex align-items-center group"> Automated Generation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="automated-generation" aria-haspopup="dialog" aria-label="Share link: Automated Generation"> Share link </button> </h4>Scanner Tool: <code>./bin/canaryscan</code> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Generate evidence ledger go build -o ./bin/canaryscan ./tools/canaryscan ./bin/canaryscan --root . --out status.json --csv status.csv </code></pre></div>Output Files: <ul> <li><code>status.json</code>: Complete evidence with metadata</li> <li><code>status.csv</code>: Tabular format for reporting</li> <li><code>GAP_ANALYSIS.md</code>: Human-readable gap summary</li> </ul> <h4 id="evidence-structure" class="position-relative d-flex align-items-center group"> Evidence Structure <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="evidence-structure" aria-haspopup="dialog" aria-label="Share link: Evidence Structure"> Share link </button> </h4>JSON Format: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "generated_at": "2026-01-24T10:30:00Z", "total_requirements": 2190, "total_tested": 1783, "total_benched": 131, "total_exempt": 169, "requirements": [ { "req_id": "REQ-GQL-010", "feature": "QueryExecution", "aspect": "BasicMatch", "status": "TESTED", "test": "TestBasicMatch", "owner": "engine", "updated": "2026-01-15", "file": "src/execution.zig", "line": 42 } ] } </code></pre></div>CSV Format: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">req_id,feature,aspect,status,test,bench,owner,updated,file,line REQ-GQL-010,QueryExecution,BasicMatch,TESTED,TestBasicMatch,,engine,2026-01-15,src/execution.zig,42 </code></pre></div> <h3 id="governance-pipeline" class="position-relative d-flex align-items-center group"> Governance Pipeline <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="governance-pipeline" aria-haspopup="dialog" aria-label="Share link: Governance Pipeline"> Share link </button> </h3> <h4 id="automated-verification" class="position-relative d-flex align-items-center group"> Automated Verification <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="automated-verification" aria-haspopup="dialog" aria-label="Share link: Automated Verification"> Share link </button> </h4>Pipeline Script: <code>scripts/governance_ci.zig</code> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Run complete governance check zig run scripts/governance_ci.zig </code></pre></div>Steps Executed: <ol> <li>Freshness: Verify NEXT.md generation date is current</li> <li>CANARY Scan: Extract and validate evidence ledger</li> <li>Variance Envelope Guard: Check performance floor assertions</li> <li>Doc Consistency: Validate README/IMPLEMENTATION_REALITY counts</li> <li>Gap Consistency: Verify GAP_ANALYSIS alignment</li> <li>Slice Validation: Check NEXT.md slice structure</li> <li>Slice-Req Crosscheck: Ensure all slices map to requirements</li> <li>Evidence Delta: Detect removed requirement IDs</li> <li>Reality Freshness: Verify IMPLEMENTATION_REALITY date</li> <li>Badge Generation: Create evidence coverage SVG</li> <li>Trend Append: Log metrics to history</li> <li>Badge Staleness: Ensure badge freshness</li> </ol> <h4 id="verification-output" class="position-relative d-flex align-items-center group"> Verification Output <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="verification-output" aria-haspopup="dialog" aria-label="Share link: Verification Output"> Share link </button> </h4>Success: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "type": "governance_summary", "status": "success", "steps": [ {"name": "freshness", "ok": true}, {"name": "canary", "ok": true}, {"name": "variance_envelope_guard", "ok": true} ] } </code></pre></div>Failure: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "type": "governance_summary", "status": "failure", "failed_step": "doc_consistency", "error": "Count mismatch: README=1735, status.json=1730" } </code></pre></div> <h3 id="variance-envelope-guards" class="position-relative d-flex align-items-center group"> Variance Envelope Guards <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="variance-envelope-guards" aria-haspopup="dialog" aria-label="Share link: Variance Envelope Guards"> Share link </button> </h3> <h4 id="purpose" class="position-relative d-flex align-items-center group"> Purpose <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="purpose" aria-haspopup="dialog" aria-label="Share link: Purpose"> Share link </button> </h4>Variance envelopes define acceptable performance variability for benchmarks. Guards prevent silent performance regressions. <h4 id="guard-script" class="position-relative d-flex align-items-center group"> Guard Script <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="guard-script" aria-haspopup="dialog" aria-label="Share link: Guard Script"> Share link </button> </h4>Command: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">zig run scripts/variance_envelope_guard.zig -- \ --status status.csv \ --readme README.md \ --min 70 \ --require-phrase </code></pre></div>Validation: <ul> <li>Counts variance envelopes in <code>status.csv</code></li> <li>Checks README contains “Variance Guards Landed: N+” phrase</li> <li>Ensures actual count >= floor (N)</li> <li>Exits with code 2 on policy violation</li> </ul> Example README Phrase: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown">Variance Guards Landed: 73+ </code></pre></div> <h4 id="envelope-definition" class="position-relative d-flex align-items-center group"> Envelope Definition <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="envelope-definition" aria-haspopup="dialog" aria-label="Share link: Envelope Definition"> Share link </button> </h4>Location: <code>docs/VARIANCE_ENVELOPES.md</code> Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown">## QueryExecution Performance Benchmark: BenchmarkBasicMatch - **Metric**: Execution time - **Baseline**: 1.5ms - **CV Threshold**: ≤0.22 (22%) - **p95/mean**: ≤2.55 - **Floor**: 0.8ms (cannot be faster, indicates mocking) - **Ceiling**: 5.0ms (regression threshold) </code></pre></div> <h3 id="requirement-tracking" class="position-relative d-flex align-items-center group"> Requirement Tracking <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="requirement-tracking" aria-haspopup="dialog" aria-label="Share link: Requirement Tracking"> Share link </button> </h3> <h4 id="requirement-id-format" class="position-relative d-flex align-items-center group"> Requirement ID Format <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="requirement-id-format" aria-haspopup="dialog" aria-label="Share link: Requirement ID Format"> Share link </button> </h4>Pattern: <code>REQ-{DOMAIN}-{NUMBER}</code> Examples: <ul> <li><code>REQ-GQL-010</code>: GQL query execution requirement</li> <li><code>REQ-AUTH-002</code>: Authentication requirement</li> <li><code>REQ-PERF-025</code>: Performance requirement</li> </ul> <h4 id="lifecycle-management" class="position-relative d-flex align-items-center group"> Lifecycle Management <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="lifecycle-management" aria-haspopup="dialog" aria-label="Share link: Lifecycle Management"> Share link </button> </h4>Creation: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// New feature: Add CANARY marker // CANARY: REQ=REQ-XXX; FEATURE="NewFeature"; ASPECT=CoreLogic; STATUS=IMPL; OWNER=team; UPDATED=2026-01-24 pub fn newFeature() void { // Implementation... } </code></pre></div>Testing: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// CANARY: REQ=REQ-XXX; FEATURE="NewFeature"; ASPECT=CoreLogic; STATUS=TESTED; TEST=TestNewFeature; OWNER=team; UPDATED=2026-01-24 test "TestNewFeature" { // Test implementation... } </code></pre></div>Benchmarking: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// CANARY: REQ=REQ-XXX; FEATURE="NewFeature"; ASPECT=Performance; STATUS=BENCHED; BENCH=BenchmarkNewFeature; OWNER=team; UPDATED=2026-01-24 benchmark "BenchmarkNewFeature" { // Benchmark implementation... } </code></pre></div> <h3 id="gap-analysis" class="position-relative d-flex align-items-center group"> Gap Analysis <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="gap-analysis" aria-haspopup="dialog" aria-label="Share link: Gap Analysis"> Share link </button> </h3> <h4 id="structure" class="position-relative d-flex align-items-center group"> Structure <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="structure" aria-haspopup="dialog" aria-label="Share link: Structure"> Share link </button> </h4>File: <code>docs/GAP_ANALYSIS.md</code> Sections: <ol> <li>Summary Table: Requirement overview by domain</li> <li>Detail Tables: Per-domain requirement breakdowns</li> <li>Gap Identification: Missing or incomplete requirements</li> <li>Status Distribution: TESTED/BENCHED/IMPL/STUB counts</li> </ol> Example Table: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown">| Domain | Total | TESTED | BENCHED | IMPL | STUB | EXEMPT | |--------|-------|--------|---------|------|------|--------| | GQL | 850 | 720 | 45 | 60 | 10 | 15 | | Auth | 120 | 110 | 5 | 3 | 0 | 2 | </code></pre></div> <h4 id="strict-verification" class="position-relative d-flex align-items-center group"> Strict Verification <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="strict-verification" aria-haspopup="dialog" aria-label="Share link: Strict Verification"> Share link </button> </h4>Command: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">./bin/canaryscan --root . \ --verify docs/GAP_ANALYSIS.md \ --strict </code></pre></div>Validation: <ul> <li>All counts in GAP_ANALYSIS match scanner output</li> <li>No requirements added/removed without documentation</li> <li>Freshness: UPDATED dates <60 days old</li> <li>No orphaned requirements (no CANARY markers)</li> </ul> <h3 id="badge-generation" class="position-relative d-flex align-items-center group"> Badge Generation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="badge-generation" aria-haspopup="dialog" aria-label="Share link: Badge Generation"> Share link </button> </h3> <h4 id="evidence-coverage-badge" class="position-relative d-flex align-items-center group"> Evidence Coverage Badge <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="evidence-coverage-badge" aria-haspopup="dialog" aria-label="Share link: Evidence Coverage Badge"> Share link </button> </h4>Generate: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">zig run scripts/generate_badges.zig -- \ --status status.csv \ --out badges/evidence.svg </code></pre></div>Badge Display (in your project README): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text">![Evidence Coverage]\(badges/evidence.svg) </code></pre></div>Note: The badge path is relative to your project root, not this documentation site. Remove the backslash before the opening parenthesis when using. Color Thresholds: <table> <thead> <tr> <th>Coverage</th> <th>Color</th> <th>Hex</th> </tr> </thead> <tbody> <tr> <td>≥99.9%</td> <td>Bright Green</td> <td>#4c1</td> </tr> <tr> <td>≥95%</td> <td>Green</td> <td>#97CA00</td> </tr> <tr> <td>≥85%</td> <td>Yellow</td> <td>#dfb317</td> </tr> <tr> <td>≥70%</td> <td>Orange</td> <td>#fe7d37</td> </tr> <tr> <td><70%</td> <td>Red</td> <td>#e05d44</td> </tr> </tbody> </table> Coverage Formula: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">coverage = (TESTED + BENCHED) / TOTAL </code></pre></div> <h4 id="trend-history" class="position-relative d-flex align-items-center group"> Trend History <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="trend-history" aria-haspopup="dialog" aria-label="Share link: Trend History"> Share link </button> </h4>Append Metrics: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">zig run scripts/governance_trend_append.zig </code></pre></div>History File: <code>badges/history.jsonl</code> Format: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">{"timestamp":"2026-01-24T10:30:00Z","total":2190,"tested":1783,"benched":131,"coverage":0.874} </code></pre></div> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3> <h4 id="writing-canary-markers" class="position-relative d-flex align-items-center group"> Writing CANARY Markers <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="writing-canary-markers" aria-haspopup="dialog" aria-label="Share link: Writing CANARY Markers"> Share link </button> </h4><ol> <li> One CANARY per Aspect: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// ✅ Good: One aspect per marker // CANARY: REQ=REQ-XXX; FEATURE="ExampleFeature"; ASPECT=CoreLogic; STATUS=IMPL; OWNER=team; UPDATED=2026-01-24 // ❌ Bad: Multiple aspects in one marker // CANARY: REQ=REQ-XXX; FEATURE="ExampleFeature"; ASPECT=CoreLogic,Validation; STATUS=IMPL; OWNER=team; UPDATED=2026-01-24 </code></pre></div></li> <li> Keep UPDATED Current: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Update date when changing implementation // CANARY: REQ=REQ-XXX; FEATURE="ExampleFeature"; ASPECT=CoreLogic; STATUS=IMPL; OWNER=team; UPDATED=2026-01-24 </code></pre></div></li> <li> Link Tests Explicitly: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// CANARY: REQ=REQ-XXX; FEATURE="ExampleFeature"; ASPECT=UnitTesting; STATUS=TESTED; TEST=TestExactName; OWNER=team; UPDATED=2026-01-24 </code></pre></div></li> <li> Progress Status Appropriately: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">STUB → IMPL (implementation added) IMPL → TESTED (tests passing) TESTED → BENCHED (performance validated) </code></pre></div></li> </ol> <h4 id="governance-workflow" class="position-relative d-flex align-items-center group"> Governance Workflow <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="governance-workflow" aria-haspopup="dialog" aria-label="Share link: Governance Workflow"> Share link </button> </h4>Daily Development: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 1. Implement feature with CANARY marker # 2. Run local tests make test # 3. Update CANARY status # STATUS=IMPL → STATUS=TESTED # 4. Verify governance zig run scripts/governance_ci.zig </code></pre></div>PR Submission: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># 1. Run full governance check make governance-check # 2. Verify no regressions ./bin/canaryscan --verify docs/GAP_ANALYSIS.md --strict # 3. Update documentation if needed # 4. Commit with evidence git commit -m "feat: Add X (REQ-Y-001 TESTED)" </code></pre></div> <h3 id="troubleshooting" class="position-relative d-flex align-items-center group"> Troubleshooting <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="troubleshooting" aria-haspopup="dialog" aria-label="Share link: Troubleshooting"> Share link </button> </h3> <h4 id="common-issues" class="position-relative d-flex align-items-center group"> Common Issues <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="common-issues" aria-haspopup="dialog" aria-label="Share link: Common Issues"> Share link </button> </h4>Issue: Governance check fails with “Count mismatch” Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Regenerate evidence ledger ./bin/canaryscan --root . --out status.json --csv status.csv # Update README/IMPLEMENTATION_REALITY with current counts # Example: Total=1735, TESTED=1420, BENCHED=102 </code></pre></div><hr> Issue: “UPDATED date stale” error Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Update CANARY marker with current date // CANARY: REQ=REQ-XXX; FEATURE="ExampleFeature"; ASPECT=CoreLogic; STATUS=IMPL; OWNER=team; UPDATED=2026-01-24 </code></pre></div><hr> Issue: Variance envelope guard fails Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check actual variance envelope count grep -r "VarianceEnvelope" src/ | grep CANARY | wc -l # Update README phrase to match # Variance Guards Landed: 73+ </code></pre></div><hr> Issue: Test name mismatch Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Ensure TEST field matches actual test name // CANARY: REQ=REQ-XXX; FEATURE="ExampleFeature"; ASPECT=UnitTesting; STATUS=TESTED; TEST=TestExactFunctionName; OWNER=team; UPDATED=2026-01-24 test "TestExactFunctionName" { // Must match exactly (case-sensitive) } </code></pre></div> <h3 id="references" class="position-relative d-flex align-items-center group"> References <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="references" aria-haspopup="dialog" aria-label="Share link: References"> Share link </button> </h3> <h4 id="documentation" class="position-relative d-flex align-items-center group"> Documentation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="documentation" aria-haspopup="dialog" aria-label="Share link: Documentation"> Share link </button> </h4><ul> <li>Governance Guide: <code>docs/GOVERNANCE.md</code></li> <li>GAP Analysis: <code>docs/GAP_ANALYSIS.md</code></li> <li>Variance Envelopes: <code>docs/VARIANCE_ENVELOPES.md</code></li> <li>Implementation Reality: <code>docs/IMPLEMENTATION_REALITY.md</code></li> </ul> <h4 id="tools" class="position-relative d-flex align-items-center group"> Tools <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="tools" aria-haspopup="dialog" aria-label="Share link: Tools"> Share link </button> </h4><ul> <li>CANARY Scanner: <code>tools/canaryscan/</code> (Go)</li> <li>Governance CI: <code>scripts/governance_ci.zig</code></li> <li>Variance Guard: <code>scripts/variance_envelope_guard.zig</code></li> <li>Badge Generator: <code>scripts/generate_badges.zig</code></li> </ul> <h4 id="make-targets" class="position-relative d-flex align-items-center group"> Make Targets <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="make-targets" aria-haspopup="dialog" aria-label="Share link: Make Targets"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">make governance-check # Complete governance pipeline make governance-badge # Generate evidence badge make governance-variance-guard # Variance envelope check make status-generate # Run CANARY scanner </code></pre></div> <h3 id="next-steps" class="position-relative d-flex align-items-center group"> Next Steps <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="next-steps" aria-haspopup="dialog" aria-label="Share link: Next Steps"> Share link </button> </h3>For New Contributors: <ul> <li><a href="/docs/contribute/" >Contributing Guide</a> - Code standards and CANARY usage</li> <li><a href="/docs/guides/testing-strategies/" >Testing Strategies</a> - Test framework overview</li> <li><a href="/docs/development/repl-advanced/" >Development Workflow</a> - Daily development practices</li> </ul> For Maintainers: <ul> <li><a href="/docs/reference/changelog/" >Release Process</a> - Version management</li> <li><a href="/docs/ops/docker-deployment/" >CI/CD Setup</a> - Automated governance checks</li> <li><a href="/docs/guides/troubleshooting/" >Documentation</a> - Gap analysis maintenance</li> </ul> <hr> Document Version: 1.0 Last Updated: January 24, 2026 Status: Production Ready Markers: 1,735 active CANARY markers Requirements: 2,190+ tracked requirements Coverage: 81.4% TESTED, 6.0% BENCHED