hummbl-bibliography 1.0.0

package/toolkit/README.md

@@ -0,0 +1,360 @@
+# HUMMBL Bibliography Toolkit
+
+A comprehensive Node.js toolkit for managing, validating, and analyzing the HUMMBL Bibliography.
+
+## 🛠️ Tools Overview
+
+| Tool | Purpose | Usage |
+|------|---------|-------|
+| `validate.js` | Validate BibTeX entries | `npm run validate` |
+| `check-duplicates.js` | Find duplicate entries | `npm run check-dups` |
+| `fix-duplicates.js` | Remove duplicates | `npm run fix-dups` |
+| `find-missing-dois.js` | Enrich with DOIs | `npm run find-dois` |
+| `stats.js` | Generate statistics | `npm run stats` |
+| `extract-keywords.js` | Extract HUMMBL keywords | `npm run keywords` |
+| `merge-entries.js` | Interactive merger | `npm run merge` |
+
+## 📦 Installation
+
+```bash
+cd toolkit
+npm install
+```
+
+## 🚀 Usage
+
+### Validation
+
+Validate all bibliography files for errors and warnings:
+
+```bash
+npm run validate
+```
+
+Output includes:
+- Missing required fields
+- Malformed DOIs/ISBNs
+- Short abstracts
+- Missing HUMMBL keywords
+
+**CI Mode** (for automation):
+```bash
+npm run validate:ci
+```
+Returns JSON output and exits with error code if validation fails.
+
+### Duplicate Detection
+
+Check for duplicate entries across all files:
+
+```bash
+npm run check-dups
+```
+
+Detects duplicates by:
+- Citation keys
+- Normalized titles
+- DOIs
+- ISBNs
+
+### Duplicate Removal
+
+Automatically remove duplicates (keeps higher tier):
+
+```bash
+npm run fix-dups
+```
+
+Creates `.backup` files before modification.
+
+**Dry run** (preview changes):
+```bash
+npm run fix-dups -- --dry-run
+```
+
+### DOI Enrichment
+
+Find missing DOIs via CrossRef API:
+
+```bash
+npm run find-dois
+```
+
+⚠️ **Note**: Rate-limited to 1 request/second. May take several minutes.
+
+Results include confidence scores for manual review.
+
+### Statistics Generation
+
+Generate comprehensive statistics:
+
+```bash
+npm run stats
+```
+
+Shows:
+- Entry counts by tier and type
+- Transformation distribution
+- Quality metrics
+- Gap analysis
+
+**JSON output** (for automation):
+```bash
+npm run stats:json
+```
+
+### Keyword Extraction
+
+Extract and display HUMMBL transformation keywords:
+
+```bash
+npm run keywords
+```
+
+Shows:
+- Entries per transformation
+- Cross-transformation analysis
+- Coverage distribution
+
+### Entry Merging
+
+Interactive tool for consolidating entries:
+
+```bash
+npm run merge
+```
+
+Provides guidance for manual merging process.
+
+## 🔧 Advanced Usage
+
+### Validate Specific File
+
+```bash
+node src/validate.js ../bibliography/T1_canonical.bib
+```
+
+### Custom Statistics
+
+```bash
+node src/stats.js ../bibliography --json | jq '.transformations'
+```
+
+### Chain Commands
+
+```bash
+npm run validate && npm run check-dups && npm run stats
+```
+
+Or use the test suite:
+```bash
+npm test
+```
+
+## 📊 Output Formats
+
+### Validation Output
+
+```
+============================================================
+  HUMMBL Bibliography Validator
+============================================================
+
+📖 Validating T1_canonical.bib...
+  Found 17 entries
+  ✓ All entries valid
+
+============================================================
+  Validation Summary
+============================================================
+
+Total Entries: 48
+Errors: 0
+Warnings: 0
+
+✨ All validations passed!
+```
+
+### Statistics Output
+
+```
+============================================================
+  HUMMBL BIBLIOGRAPHY STATISTICS
+============================================================
+
+📊 OVERVIEW
+Total Entries: 48
+
+📚 BY TIER
+  T1: 17 (35.4%) ████████
+  T2: 16 (33.3%) ████████
+  T3: 15 (31.3%) ███████
+
+🔄 HUMMBL TRANSFORMATIONS
+  SY (Synthesis    ): 20 ██████████
+  CO (Composition  ): 18 █████████
+  ...
+```
+
+### JSON Output
+
+```json
+{
+  "total": 48,
+  "byTier": {
+    "T1": 17,
+    "T2": 16,
+    "T3": 15
+  },
+  "transformations": {
+    "P": 17,
+    "IN": 15,
+    "CO": 18,
+    "DE": 12,
+    "RE": 16,
+    "SY": 20
+  },
+  "quality": {
+    "withDOI": 14,
+    "withISBN": 35,
+    "withAbstract": 48,
+    "withKeywords": 48
+  }
+}
+```
+
+## 🤖 Automation
+
+### Pre-commit Hooks
+
+Setup Git hooks to validate on commit:
+
+```bash
+npm run setup
+```
+
+This installs Husky hooks that:
+- Validate modified `.bib` files
+- Check for duplicates
+- Block commits with critical errors
+
+### CI/CD Integration
+
+The toolkit is designed for CI/CD integration:
+
+**GitHub Actions Example**:
+```yaml
+- name: Validate bibliography
+  run: |
+    cd toolkit
+    npm ci
+    npm run validate:ci
+```
+
+See `.github/workflows/` for complete examples.
+
+## 📝 Configuration
+
+### package.json
+
+All scripts are configured in `package.json`:
+
+```json
+{
+  "scripts": {
+    "validate": "node src/validate.js ../bibliography",
+    "validate:ci": "node src/validate.js ../bibliography --ci",
+    "check-dups": "node src/check-duplicates.js ../bibliography",
+    "stats": "node src/stats.js ../bibliography",
+    "stats:json": "node src/stats.js ../bibliography --json",
+    ...
+  }
+}
+```
+
+### Directory Structure
+
+```
+toolkit/
+├── src/
+│   ├── validate.js           # Validation engine
+│   ├── check-duplicates.js   # Duplicate detector
+│   ├── fix-duplicates.js     # Duplicate remover
+│   ├── find-missing-dois.js  # DOI enrichment
+│   ├── stats.js              # Statistics generator
+│   ├── extract-keywords.js   # Keyword extractor
+│   └── merge-entries.js      # Entry merger
+├── package.json              # Dependencies and scripts
+├── package-lock.json         # Locked dependencies
+└── README.md                 # This file
+```
+
+## 🧪 Testing
+
+Run the full test suite:
+
+```bash
+npm test
+```
+
+This runs:
+1. Validation on all files
+2. Duplicate detection
+
+## 🐛 Troubleshooting
+
+### "Citation-js not found"
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### "Permission denied" on scripts
+
+```bash
+chmod +x src/*.js
+```
+
+### Validation fails on valid entries
+
+Check that:
+- BibTeX syntax is correct
+- All required fields are present
+- Field names use correct casing
+
+### DOI finder times out
+
+The CrossRef API is rate-limited. The script waits 1 second between requests. For large batches, this may take time.
+
+## 📚 Dependencies
+
+- **@citation-js/core**: BibTeX parsing
+- **@citation-js/plugin-bibtex**: BibTeX format support
+- **axios**: HTTP requests for DOI enrichment
+- **chalk**: Terminal colors and formatting
+- **commander**: CLI argument parsing (future)
+
+## 🔮 Future Enhancements
+
+- [ ] Watch mode for continuous validation
+- [ ] Interactive TUI for managing entries
+- [ ] Export to multiple formats (APA, Chicago, etc.)
+- [ ] Automated relevance scoring
+- [ ] Network graph generation
+- [ ] Web dashboard
+
+## 📖 Documentation
+
+- [CONTRIBUTING.md](../docs/CONTRIBUTING.md) - Contribution guidelines
+- [QUALITY_STANDARDS.md](../docs/QUALITY_STANDARDS.md) - Entry standards
+- [TRANSFORMATION_GUIDE.md](../docs/TRANSFORMATION_GUIDE.md) - HUMMBL mapping
+
+## 📄 License
+
+MIT License - see [../LICENSE](../LICENSE)
+
+---
+
+**Maintained by**: HUMMBL Team  
+**Version**: 1.0.0

package/toolkit/docs/generated/quick-reference.md

@@ -0,0 +1,179 @@
+# HUMMBL Base120 Quick Reference
+
+**Version**: 1.0-production
+**Generated**: 2025-11-12
+**Source**: Canonical Base120 Framework
+
+---
+
+## P Series
+
+**Transform**: Frame and name what is. Anchor or shift point of view.
+
+| Code | Model Name |
+|------|-----------|
+| **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
+
+**Transform**: Reverse assumptions. Examine opposites, edges, negations.
+
+| Code | Model Name |
+|------|-----------|
+| **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
+
+**Transform**: Combine parts into coherent wholes.
+
+| Code | Model Name |
+|------|-----------|
+| **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
+
+**Transform**: Break complex systems into constituent parts.
+
+| Code | Model Name |
+|------|-----------|
+| **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
+
+**Transform**: Apply operations iteratively, with outputs becoming inputs.
+
+| Code | Model Name |
+|------|-----------|
+| **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
+
+**Transform**: Understand systems of systems, coordination, and emergent dynamics.
+
+| Code | Model Name |
+|------|-----------|
+| **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 |
+
+---
+
+**Usage Guidelines**
+
+1. **Only use models from this official list**
+2. **Reference by code**: [P|IN|CO|DE|RE|SY][1-20]
+3. **Verify against this list** before claiming a model
+4. **When uncertain, ask** rather than guessing
+