hummbl-bibliography 1.0.0

package/.cascade/rules/hummbl-base120.md

@@ -0,0 +1,107 @@
+# HUMMBL Base120 Mental Models - STRICT USAGE
+
+## ABSOLUTE REQUIREMENTS
+
+1. **ONLY use models from the official Base120 list**
+2. **NEVER substitute generic mental models** (OODA, Hanlon's, Occam's, etc.)
+3. **ALWAYS validate model codes** match pattern: [P|IN|CO|DE|RE|SY][1-20]
+4. **When uncertain, ASK** the user rather than guessing
+
+## FORBIDDEN MODELS (These are NOT in Base120)
+
+❌ OODA Loop
+❌ Hanlon's Razor
+❌ Occam's Razor
+❌ Circle of Competence
+❌ Antifragility
+❌ Survivorship Bias
+❌ Black Swan Theory
+❌ Regression to the Mean
+❌ Map vs Territory
+
+If you reference any of these, you are HALLUCINATING.
+
+## CORRECT USAGE EXAMPLES
+
+✅ "Let's apply P1 (First Principles Framing) to break this down..."
+✅ "Using DE3 (Modularization), we can separate concerns..."
+✅ "IN2 (Premortem Analysis) suggests we should..."
+
+## BEFORE REFERENCING ANY MODEL
+
+1. Check: Is the code in format [P|IN|CO|DE|RE|SY][1-20]?
+2. Check: Does the name match the official list exactly?
+3. Check: Am I in the right transformation category?
+4. If ANY doubt → ASK USER
+
+## SELF-CHECK PROTOCOL
+
+Before outputting code/docs that reference mental models:
+- [ ] All model codes validated against official list
+- [ ] No generic/hallucinated models present
+- [ ] Model names match exactly (no paraphrasing)
+- [ ] Transformation categories correct
+
+## HUMMBL Base120 Quick Reference
+
+### P-Series (Perspective/Identity)
+P1=First Principles Framing, P2=Stakeholder Mapping, P3=Identity Stack,
+P4=Lens Shifting, P5=Empathy Mapping, P6=Point-of-View Anchoring,
+P7=Perspective Switching, P8=Narrative Framing, P9=Cultural Lens Shifting,
+P10=Context Windowing, P11=Role Perspective-Taking, P12=Temporal Framing,
+P13=Spatial Framing, P14=Reference Class Framing, P15=Assumption Surfacing,
+P16=Identity-Context Reciprocity, P17=Frame Control & Reframing,
+P18=Boundary Object Selection, P19=Sensemaking Canvases, P20=Worldview Articulation
+
+### IN-Series (Inversion)
+IN1=Subtractive Thinking, IN2=Premortem Analysis, IN3=Problem Reversal,
+IN4=Contra-Logic, IN5=Negative Space Framing, IN6=Inverse/Proof by Contradiction,
+IN7=Boundary Testing, IN8=Contrapositive Reasoning, IN9=Backward Induction,
+IN10=Red Teaming, IN11=Devil's Advocate Protocol, IN12=Failure First Design,
+IN13=Opportunity Cost Focus, IN14=Second-Order Effects (Inverted),
+IN15=Constraint Reversal, IN16=Inverse Optimization, IN17=Counterfactual Negation,
+IN18=Kill-Criteria & Stop Rules, IN19=Harm Minimization (Via Negativa),
+IN20=Antigoals & Anti-Patterns Catalog
+
+### CO-Series (Composition)
+CO1=Synergy Principle, CO2=Chunking, CO3=Functional Composition,
+CO4=Interdisciplinary Synthesis, CO5=Emergence, CO6=Gestalt Integration,
+CO7=Network Effects, CO8=Layered Abstraction, CO9=Interface Contracts,
+CO10=Pipeline Orchestration, CO11=Pattern Composition (Tiling),
+CO12=Modular Interoperability, CO13=Cross-Domain Analogy, CO14=Platformization,
+CO15=Combinatorial Design, CO16=System Integration Testing,
+CO17=Orchestration vs Choreography, CO18=Knowledge Graphing,
+CO19=Multi-Modal Integration, CO20=Holistic Integration
+
+### DE-Series (Decomposition)
+DE1=Root Cause Analysis (5 Whys), DE2=Factorization, DE3=Modularization,
+DE4=Layered Breakdown, DE5=Dimensional Reduction, DE6=Taxonomy/Classification,
+DE7=Pareto Decomposition (80/20), DE8=Work Breakdown Structure,
+DE9=Signal Separation, DE10=Abstraction Laddering, DE11=Scope Delimitation,
+DE12=Constraint Isolation, DE13=Failure Mode Analysis (FMEA),
+DE14=Variable Control & Isolation, DE15=Decision Tree Expansion,
+DE16=Hypothesis Disaggregation, DE17=Orthogonalization,
+DE18=Scenario Decomposition, DE19=Critical Path Unwinding,
+DE20=Partition-and-Conquer
+
+### RE-Series (Recursion)
+RE1=Recursive Improvement (Kaizen), RE2=Feedback Loops,
+RE3=Meta-Learning (Learn-to-Learn), RE4=Nested Narratives,
+RE5=Fractal Reasoning, RE6=Recursive Framing, RE7=Self-Referential Logic,
+RE8=Bootstrapping, RE9=Iterative Prototyping, RE10=Compounding Cycles,
+RE11=Calibration Loops, RE12=Bayesian Updating in Practice,
+RE13=Gradient Descent Heuristic, RE14=Spiral Learning,
+RE15=Convergence-Divergence Cycling, RE16=Retrospective→Prospective Loop,
+RE17=Versioning & Diff, RE18=Anti-Catastrophic Forgetting,
+RE19=Auto-Refactor, RE20=Recursive Governance (Guardrails that Learn)
+
+### SY-Series (Meta-Systems)
+SY1=Leverage Points, SY2=System Boundaries, SY3=Stocks & Flows,
+SY4=Requisite Variety, SY5=Systems Archetypes, SY6=Feedback Structure Mapping,
+SY7=Path Dependence, SY8=Homeostasis/Dynamic Equilibrium,
+SY9=Phase Transitions & Tipping Points, SY10=Causal Loop Diagrams,
+SY11=Governance Patterns, SY12=Protocol/Interface Standards,
+SY13=Incentive Architecture, SY14=Risk & Resilience Engineering,
+SY15=Multi-Scale Alignment, SY16=Ecosystem Strategy, SY17=Policy Feedbacks,
+SY18=Measurement & Telemetry, SY19=Meta-Model Selection,
+SY20=Systems-of-Systems Coordination

package/.github/CODEOWNERS

@@ -0,0 +1,17 @@
+# CODEOWNERS file — assign reviewers automatically for paths
+# Format: <path> <user-or-team>
+# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Default owners for everything
+* @hummbl-dev
+
+# Owners for sources (adjust paths if your code lives elsewhere)
+bibliography/ @hummbl-dev
+toolkit/ @hummbl-dev
+scripts/ @hummbl-dev
+docs/ @hummbl-dev
+.github/ @hummbl-dev
+
+# Owners for security-sensitive files
+/package.json @hummbl-dev
+/package-lock.json @hummbl-dev

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,24 @@
+# Bug report
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Run '...'
+3. Observe '...'
+
+**Expected behavior**
+What you expected to happen.
+
+**Screenshots or logs**
+If applicable, add screenshots or paste logs.
+
+**Environment (please complete the following information):**
+- OS: (e.g. macOS, Ubuntu, Windows)
+- Node.js version:
+- npm/yarn version:
+
+**Additional context**
+Add any other context about the problem here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,10 @@
+# Feature request
+
+**Is your feature request related to a problem? Please describe.**
+
+**Describe the solution you'd like**
+
+**Describe alternatives you've considered**
+
+**Additional context**
+Any extra information that can help.

package/.github/ISSUE_TEMPLATE/new-entry.md

@@ -0,0 +1,79 @@
+---
+name: New Bibliography Entry
+about: Propose a new entry for the HUMMBL Bibliography
+title: '[NEW] '
+labels: ['new-entry', 'needs-review']
+assignees: ''
+---
+
+## Entry Information
+
+### Entry Type
+- [ ] Book
+- [ ] Journal Article
+- [ ] Conference Paper
+- [ ] Technical Report
+- [ ] Other (specify): 
+
+### Basic Information
+
+**Title:**  
+**Author(s):**  
+**Year:**  
+**DOI/ISBN:**  
+**Publisher/Journal:**  
+
+### HUMMBL Transformation Mapping
+
+**Primary Transformation:** [Select one: P, IN, CO, DE, RE, SY]
+
+**Secondary Transformation(s):** [Optional, select 0-2: P, IN, CO, DE, RE, SY]
+
+**Mapping Rationale:**  
+<!-- Explain why you chose these transformations. What cognitive operations does this work emphasize? -->
+
+
+### Quality Tier
+
+- [ ] **T1 - Canonical** (Foundational theory, field-defining, 500+ citations)
+- [ ] **T2 - Empirical** (Peer-reviewed research, rigorous methodology)
+- [ ] **T3 - Applied** (Practitioner-focused, industry applications)
+
+**Tier Justification:**  
+<!-- Why does this work belong in the selected tier? -->
+
+
+### Gap Analysis
+
+**Does this entry help fill a current gap?** [Yes/No]
+
+If yes, which transformation(s) need coverage?  
+<!-- See docs/GAP_ANALYSIS.md for current gaps -->
+
+
+## BibTeX Entry
+
+```bibtex
+@book{AuthorYearTitle,
+  title = {},
+  author = {},
+  year = {},
+  publisher = {},
+  isbn = {},
+  abstract = {},
+  keywords = {}
+}
+```
+
+## Additional Context
+
+<!-- Any other relevant information about this entry -->
+
+**Checklist before submitting:**
+- [ ] I have read [CONTRIBUTING.md](../../docs/CONTRIBUTING.md)
+- [ ] I have reviewed [TRANSFORMATION_GUIDE.md](../../docs/TRANSFORMATION_GUIDE.md)
+- [ ] I have checked for duplicates in existing bibliography
+- [ ] BibTeX entry includes all required fields
+- [ ] Abstract is at least 50 characters
+- [ ] Keywords include HUMMBL transformation tags (e.g., `HUMMBL:SY`)
+- [ ] Citation key follows format: `AuthorYearShortTitle`

package/.github/ISSUE_TEMPLATE/quality-improvement.md

@@ -0,0 +1,71 @@
+---
+name: Quality Improvement
+about: Report an issue with an existing entry or suggest improvements
+title: '[QUALITY] '
+labels: ['quality', 'enhancement']
+assignees: ''
+---
+
+## Entry Information
+
+**Citation Key:** [e.g., Meadows2008ThinkingSystems]
+
+**Current File:** [e.g., bibliography/T1_canonical.bib]
+
+## Issue Type
+
+- [ ] Missing or incorrect metadata (DOI, ISBN, etc.)
+- [ ] Abstract needs improvement
+- [ ] HUMMBL transformation mapping incorrect
+- [ ] Tier assignment questionable
+- [ ] Duplicate entry
+- [ ] Formatting issues
+- [ ] Other (specify below)
+
+## Problem Description
+
+<!-- Describe the issue with the current entry -->
+
+
+## Proposed Solution
+
+<!-- What changes do you suggest? -->
+
+
+## Supporting Evidence
+
+<!-- Provide links, citations, or rationale for the proposed changes -->
+
+
+## Impact
+
+**Severity:**
+- [ ] Critical (blocks usage, must fix)
+- [ ] High (significantly affects quality)
+- [ ] Medium (moderate improvement)
+- [ ] Low (minor enhancement)
+
+**Affected Areas:**
+- [ ] Bibliographic accuracy
+- [ ] HUMMBL transformation mapping
+- [ ] Tier classification
+- [ ] Quality metrics
+- [ ] Other: 
+
+## Suggested BibTeX Changes
+
+```bibtex
+<!-- If applicable, provide corrected BibTeX entry -->
+```
+
+## Additional Context
+
+<!-- Any other relevant information -->
+
+---
+
+**Checklist:**
+- [ ] I have verified the issue exists in the current version
+- [ ] I have checked that this issue hasn't been reported before
+- [ ] I have consulted [QUALITY_STANDARDS.md](../../docs/QUALITY_STANDARDS.md)
+- [ ] I have provided evidence for my claims

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Summary
+Brief description of the change.
+
+## Related issues
+Closes: #
+
+## Checklist
+- [ ] My code follows the project's style guidelines
+- [ ] I have added/updated tests where applicable
+- [ ] I have added/updated documentation (README, docs/)
+- [ ] CI passes (lint, tests, audit)
+- [ ] I have requested review from CODEOWNERS where applicable
+
+## Testing
+Describe how this change was tested locally.

package/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  # Enable version updates for npm
+  - package-ecosystem: "npm"
+    directory: "/toolkit"
+    schedule:
+      interval: "weekly"
+    # Create pull requests for version updates
+    open-pull-requests-limit: 10
+    # Add labels to pull requests
+    labels:
+      - "dependencies"
+      - "security"
+    # Group updates by dependency name
+    groups:
+      npm-dependencies:
+        patterns: ["*"]

package/.github/workflows/ci.yml

@@ -0,0 +1,98 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - 'q4-2025-enhancement'
+      - 'doi-enrichment-phase2'
+      - 'feat/security-enhancements'
+      - 'fix/node-version-update'
+      - 'copilot/*'
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: write
+  actions: write
+  security-events: write
+
+jobs:
+  build-and-test:
+    name: Lint / Test / Audit (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 24]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+          cache-dependency-path: toolkit/package-lock.json
+
+      - name: Install dependencies
+        run: |
+          cd toolkit
+          if [ -f package-lock.json ]; then npm ci; else npm install; fi
+
+      - name: Lint
+        run: |
+          cd toolkit
+          if npm run 2>/dev/null | grep -q 'lint'; then npm run lint; else echo "No lint script found"; fi
+
+      - name: Run tests
+        run: |
+          cd toolkit
+          if npm run 2>/dev/null | grep -q 'test'; then npm test --if-present --silent; else echo "No test script found"; fi
+        env:
+          CI: true
+
+      - name: Build (if applicable)
+        run: |
+          cd toolkit
+          if npm run 2>/dev/null | grep -q 'build'; then npm run build --if-present; else echo "No build script found"; fi
+
+      - name: Dependency audit (fail on high)
+        run: |
+          cd toolkit
+          if [ -f package-lock.json ] || [ -f yarn.lock ]; then
+            npm audit --omit=dev --audit-level=high || (echo "Vulnerabilities found (>=high)" && exit 1)
+          else
+            echo "No lockfile found — consider adding package-lock.json or yarn.lock"
+          fi
+
+      - name: Upload test artifacts (results, coverage)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-node${{ matrix.node-version }}
+          path: |
+            toolkit/coverage
+            toolkit/test-results
+
+  codeql:
+    name: CodeQL Static Analysis
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: javascript
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Run CodeQL analysis
+        uses: github/codeql-action/analyze@v3

package/.github/workflows/doi-enrichment.yml

@@ -0,0 +1,77 @@
+name: DOI Enrichment
+
+on:
+  workflow_dispatch:  # Manual trigger only
+    inputs:
+      file:
+        description: 'Bibliography file to enrich (e.g., T1_canonical.bib, or "all")'
+        required: false
+        default: 'all'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  find-dois:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ github.head_ref }}
+      
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '24'
+        cache: 'npm'
+        cache-dependency-path: toolkit/package-lock.json
+        
+    - name: Install dependencies
+      run: |
+        cd toolkit
+        npm ci
+        
+    - name: Find missing DOIs
+      run: |
+        cd toolkit
+        npm run find-dois > ../doi-enrichment-report.txt
+        
+    - name: Create enrichment branch
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git checkout -b doi-enrichment-$(date +%Y%m%d)
+        
+    - name: Display results
+      run: |
+        cat doi-enrichment-report.txt
+        
+    - name: Create summary
+      run: |
+        echo "## DOI Enrichment Report" > doi-summary.md
+        echo "" >> doi-summary.md
+        echo "Generated on: $(date)" >> doi-summary.md
+        echo "" >> doi-summary.md
+        echo "### Results" >> doi-summary.md
+        echo "" >> doi-summary.md
+        echo "\`\`\`" >> doi-summary.md
+        cat doi-enrichment-report.txt >> doi-summary.md
+        echo "\`\`\`" >> doi-summary.md
+        echo "" >> doi-summary.md
+        echo "### Action Required" >> doi-summary.md
+        echo "" >> doi-summary.md
+        echo "Review the found DOIs above and manually add high-confidence matches to the bibliography files." >> doi-summary.md
+        echo "" >> doi-summary.md
+        echo "**Note**: This workflow does NOT automatically modify bibliography files. Manual review is required." >> doi-summary.md
+        
+    - name: Upload report
+      uses: actions/upload-artifact@v4
+      with:
+        name: doi-enrichment-report
+        path: |
+          doi-enrichment-report.txt
+          doi-summary.md
+        retention-days: 30

package/.github/workflows/security-audit.yml

@@ -0,0 +1,92 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 9 * * 1'  # Weekly on Monday at 9:00 UTC
+  workflow_dispatch:
+
+# Set the required permissions at the job level
+permissions:
+  contents: read
+  security-events: write
+  pull-requests: write
+
+jobs:
+  security-audit:
+    runs-on: ubuntu-latest
+    
+    # Ensure the job has the necessary permissions
+    permissions:
+      contents: read
+      security-events: write
+      pull-requests: write
+        
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Verify repository structure
+        run: |
+          echo "Current directory: $(pwd)"
+          echo "Contents:"
+          ls -la
+          echo "Toolkit contents:"
+          ls -la toolkit/
+      
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+          
+      - name: Install dependencies
+        working-directory: ./toolkit
+        run: |
+          echo "Installing in: $(pwd)"
+          npm ci
+      
+      - name: Run npm audit
+        id: audit
+        working-directory: ./toolkit
+        continue-on-error: true
+        run: |
+          echo "Running npm audit in: $(pwd)"
+          npm audit --json > ../audit-report.json || true
+          echo "AUDIT_REPORT<<EOF" >> $GITHUB_ENV
+          cat ../audit-report.json >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+          ls -la ..
+          
+      - name: Upload audit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: audit-report
+          path: audit-report.json
+          retention-days: 7
+          compression-level: 6
+          
+      - name: Comment on PR if vulnerabilities found
+        if: github.event_name == 'pull_request' && failure()
+        uses: actions/github-script@v7
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          script: |
+            try {
+              const { data: comment } = await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: '⚠️ **Security Audit Failed**\n\nVulnerabilities were found during the security audit. Please check the workflow run for details.'
+              });
+              console.log('Comment added successfully');
+            } catch (error) {
+              console.error('Error adding comment:', error);
+              // Don't fail the workflow if comment fails
+              core.setFailed('Failed to add comment, but continuing...');
+            }

package/.github/workflows/stats-report.yml

@@ -0,0 +1,59 @@
+name: Weekly Statistics Report
+
+on:
+  schedule:
+    # Run every Monday at 9:00 AM UTC
+    - cron: '0 9 * * 1'
+  workflow_dispatch:  # Allow manual trigger
+
+permissions:
+  contents: write
+
+jobs:
+  generate-report:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '24'
+        cache: 'npm'
+        cache-dependency-path: toolkit/package-lock.json
+        
+    - name: Install dependencies
+      run: |
+        cd toolkit
+        npm ci
+        
+    - name: Generate statistics report
+      env:
+        NO_COLOR: '1'
+        FORCE_COLOR: '0'
+      run: |
+        cd toolkit
+        REPORT="../reports/$(date +%Y-%m-%d)-stats.md"
+        echo "# Weekly Statistics Report — $(date +%Y-%m-%d)" > "$REPORT"
+        echo "" >> "$REPORT"
+        echo '```' >> "$REPORT"
+        node src/stats.js ../bibliography 2>&1 >> "$REPORT"
+        echo '```' >> "$REPORT"
+        echo "" >> "$REPORT"
+        echo "---" >> "$REPORT"
+        echo "" >> "$REPORT"
+        echo "## JSON Summary" >> "$REPORT"
+        echo "" >> "$REPORT"
+        echo '```json' >> "$REPORT"
+        node src/stats.js ../bibliography --json 2>/dev/null >> "$REPORT"
+        echo '```' >> "$REPORT"
+        
+    - name: Commit report
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git add reports/
+        git diff --staged --quiet || git commit -m "chore: weekly statistics report $(date +%Y-%m-%d)"
+        git push