🎋 Contributing to ISMS CORE

Not all documents require the same level of standardization. Apply rigor where it matters.

--- ## 🚧 Before You Open a Pull Request

**Open an issue before you write any code or content.** Describe what you want to contribute and why, and wait for a maintainer response before starting the work. This applies to every kind of contribution — code, documentation, and especially new-language content packs — and it protects your time as much as ours: a PR built on an assumption we don't share (scope, approach, or whether we're set up to maintain it long-term) gets closed regardless of how much work went into it. A good issue states: - **What** you want to add or change, and **why** it matters to you - **How** you'd approach it (structure, tooling, scope) - Whether you'd like to **start with a small sample** before committing to the full scope PRs opened without a prior issue will be closed and the contributor asked to open one instead — not a judgment on the work, just the order we need it in. --- ## 🎯 QA Philosophy ISMS CORE applies appropriate rigor based on what matters for **reliability**, **maintainability**, and **correctness**. > *"Standardization is good. Over-standardization is cargo cult. Apply rigor where it matters."* --- ## 📋 Document Types and Quality Standards

Type	Consistency	Change Freq	QA Gate
📜 POL (Policy)	🔴 High	Low	`<!-- QA_VERIFIED -->`
📋 IMP (Implementation)	🟡 Moderate	Medium	`<!-- QA_VERIFIED -->`
🐍 SCR (Scripts)	🔴 High	Medium	`# QA_VERIFIED:`
📚 REF (Reference)	🟡 Moderate	Low	`<!-- QA_VERIFIED -->`
🏢 CTX (Context)	🟡 Moderate	Low	`<!-- QA_VERIFIED -->`
📝 FORM (Forms)	🟡 Moderate	Low	`<!-- QA_VERIFIED -->`

--- ### 📋 IMP Document Structure (UG / TG) Every IMP (Implementation) document exists as a **paired set** of two files — a User Guide and a Technical Specification. This separation gives auditors, implementers, and developers each a purpose-built document without cross-contamination. ``` IMP/ ├── ISMS-IMP-A.8.9.1-UG - Baseline Configuration Assessment.md ← For implementers └── ISMS-IMP-A.8.9.1-TG - Baseline Configuration Assessment.md ← For developers/auditors ``` #### UG — User Completion Guide **Audience:** Security analysts, control owners, assessors, compliance officers The UG is the **human-written** document that guides someone through completing an assessment workbook. It answers: *"I have this Excel file — what do I do with it?"* | Section | Purpose | |---------|---------| | Assessment Overview | What this assessment covers, why it matters, scope boundaries | | Prerequisites | What must be in place before starting (access, data, approvals) | | Workbook Structure | Sheet-by-sheet overview of the Excel workbook | | Completion Walkthrough | Step-by-step instructions for filling in each sheet | | Evidence Collection | What evidence to gather, where to store it, naming conventions | | Common Pitfalls | 8-10 `MISTAKE:` examples with corrections | | Quality Checklist | Verification items before submission | | Review & Approval | Who reviews, approval workflow, escalation | #### TG — Technical Specification **Audience:** Python developers, Excel workbook developers, QA engineers The TG is **auto-generated** from the Python generator script (`SCR/generate_*.py`). It is a human-readable translation of the generator's code — every sheet, column, data validation dropdown, color style, and formula documented in structured tables. | Section | Purpose | |---------|---------| | Workbook Overview | Document ID, output filename, total sheets, control reference | | Color Palette | All hex codes, style names, and usage descriptions | | Sheet N: *Name* | Per-sheet specification with columns, widths, validations, formulas | | Data Validation Lists | All dropdown value lists defined in the generator | **Regenerating TGs:** TG content is regenerated by the factory script whenever generators change: ```bash python3 generate_tg_from_scr.py --apply # All TGs python3 generate_tg_from_scr.py --control a.8.9 # Single control group ``` The top of each TG's technical content shows its source: ``` > Auto-generated from `generate_a89_1_baseline_configuration.py` > Re-generate with: `python3 generate_tg_from_scr.py --apply` ``` #### IMP QA Criteria (v4.5+) | Requirement | Description | |-------------|-------------| | ✅ UG/TG split | Each IMP exists as `-UG` and `-TG` file pair | | ✅ Standard header | 3-line format: bold title, subtitle (UG/TG), ISO control reference | | ✅ Control quotes | Use "should" (not "shall") per ISO 27001:2022 Annex A | | ✅ British spelling | organisation, authorised, standardised | | ✅ Standard ending | `**END OF SPECIFICATION**` + separator + quote with em-dash (—) | | ✅ QA tag | `` after bamboo tag | --- ## 🚦 QA Gates

Content is promoted to this repository **only when QA gates pass**. Each document type carries a QA marker that must be present before promotion: | Document | QA marker required | |----------|--------------------| | POL / IMP / REF / CTX / FORM | `` at end of file | | SCR (Python scripts) | `# QA_VERIFIED: YYYY-MM-DD` footer block | > **Note for maintainers:** Promotion is handled by the internal development tooling in the private `factory_claude_ai` repository (`95-isms-core-factory/promote_control.sh`). Content in this repository has already passed all QA gates before being published here. --- ## 🐍 Python Script Standards ### Required Structure ```python # ============================================================================= # DOCUMENT METADATA # ============================================================================= DOCUMENT_ID = "ISMS-IMP-A.X.X.X" WORKBOOK_NAME = "Assessment Name" CONTROL_ID = "A.X.X" CONTROL_NAME = "Control Name" CONTROL_REF = f"ISO/IEC 27001:2022 - Control {CONTROL_ID}: {CONTROL_NAME}" # Timestamps GENERATED_DATE = datetime.now().strftime("%d.%m.%Y") GENERATED_TIMESTAMP = datetime.now().strftime("%Y%m%d") # Output filename OUTPUT_FILENAME = f"{DOCUMENT_ID}_{WORKBOOK_NAME.replace(' ', '_')}_{GENERATED_TIMESTAMP}.xlsx" ``` ### Logging | ❌ Don't | ✅ Do | |----------|-------| | `print("message")` | `logger.info("message")` | ```python import logging logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s', datefmt='%Y-%m-%d %H:%M:%S' ) logger = logging.getLogger(__name__) ``` ### QA Footer ```python # ============================================================================= # QA_VERIFIED: YYYY-MM-DD # QA_STATUS: PASSED # QA_TOOL: Claude Code # CHANGES: Description of changes # ============================================================================= ``` --- ## 📂 Folder Structure Each control is self-contained with all artifact types: ``` isms-a.X.X-control-name/ ├── POL/ # 📜 Policy documents ├── IMP/ # 📋 Implementation guides (UG + TG pairs) ├── SCR/ # 🐍 Scripts (generators, normalizers, consolidators) ├── WKBK/ # 📊 Generated Excel workbooks ├── REF/ # 📚 Reference materials (if applicable) ├── CTX/ # 🏢 Context documents (if applicable) └── FORM/ # 📝 Forms and templates (if applicable) ``` --- ## 🔍 Online Research Requirement

**All IMP and SCR development MUST include online research** to verify: - ✅ Current best practices for the control - ✅ Alignment with NIST, CIS, MITRE ATT&CK frameworks - ✅ Technical accuracy of implementation guidance - ✅ Latest tool capabilities and integration patterns **Key frameworks to reference:**

--- ## ⚖️ The Engineering Principle > *"Standardization is good. Over-standardization is cargo cult. Apply rigor where it matters."* **Feynman would ask:** *"Does this variation serve a purpose?"* | Answer | Action | |--------|--------| | ✅ YES | Document why and keep it | | ❌ NO | Standardize | | ⚠️ Breaks functionality | Don't force uniformity | --- ## 🔬 Validation Process

Every control pack undergoes a structured multi-stage validation process to ensure quality and correctness. ``` ┌─────────────────────────┐ │ The ISMS Core Project │ │ (Architect / Owner) │ └────────────┬────────────┘ │ Requirements + Domain Expertise ▼ ┌─────────────────────────┐ │ Claude Code (Sonnet) │──── Implementation │ Build + Code Review │ POL, IMP, SCR, REF, CTX └────────────┬────────────┘ │ ▼ ┌─────────────────────────┐ │ ISMS Copilot X │──── Audit Review │ (Documentation + QA) │ Stage 1: adequacy, Stage 2: effectiveness └────────────┬────────────┘ │ ▼ ┌─────────────────────────┐ │ The ISMS Core Project │ │ Final Approval Gate │ └─────────────────────────┘ ``` | Contributor | Role | Focus | |-------------|------|-------| | **Claude Code (Sonnet)** | Implementation + QA | Policy writing, Python generators, code review, pattern analysis | | **ISMS Copilot X** | Documentation Audit | Stage 1 documentation adequacy, Stage 2 implementation effectiveness | | **The ISMS Core Project** | Architect + Final Gate | Methodology, domain expertise, IP ownership, approval authority | Each stage operates under **purpose-built instruction sets** authored by The ISMS Core Project — structured prompts defining scope, constraints, output format, and audit criteria. These are controlled operational documents specifying exactly what must be checked, what to ignore (e.g., placeholder dates), and how to classify findings. ### Finding Classification | Severity | Criteria | Action | |----------|----------|--------| | **Critical** | Missing control implementation, audit blocker | Must resolve before promotion | | **High** | Significant gap in evidence or coverage | Must resolve before promotion | | **Medium** | Incomplete guidance, minor inconsistency | Resolve during QA pass | | **Low** | Style, formatting, enhancement opportunity | Track for future iteration | --- ## 🤖 AI-Assisted Development

Contributor	Role
The ISMS Core Project	Methodology, architecture, domain expertise, IP ownership
Claude Code (Sonnet)	Primary implementation partner — see detailed contribution below
ISMS Copilot X	Documentation audit, adequacy review, implementation effectiveness

--- ## 🧠 Claude Code — Implementation Contribution

Claude Code (Anthropic, Sonnet model family) has been the primary implementation partner on ISMS CORE since December 31, 2025, and the collaboration is ongoing. Working in continuous pairing sessions directed by The ISMS Core Project — who authored all methodology, architectural decisions, prompt instruction sets, and multi-model orchestration — Claude Code delivered the full automation layer, wrote and refined all documentation, and built the factory infrastructure that makes this project maintainable. ### What was built

Category	Deliverable	Scale
Python Scripts	Workbook Generators	288 generator scripts — 188 (FW) + 53 (OP) + 21 (PRIV) + 16 (CLD: 12 PII + 4 Sec) + 10 (AI), plus the shared checklist engines
IMP Documents	User Guides (UG) + Technical Specifications (TG) for every assessment	472 files — 378 FW (189 UG + 189 TG: 188 packs + 1 foundation pair) + 42 PRIV + 32 CLD (16 UG + 16 TG) + 20 AI
POL Documents	Policy framework with "WITH WHAT" verification methodology	53 framework POLs + 53 operational OP-POLs
Excel Workbooks	Assessment workbooks with data validation, formulas, conditional formatting	188 (FRAMEWORK) + 53 (OPERATIONAL)
Factory Automation	Assembly, promotion, backup, sync, splitting, normalization scripts	10+ major tools
QA Infrastructure	QA gates, status dashboards, verification pipeline	53/53 controls passing

### The journey ``` December 31st 2025: Pilot Control Creation -> A.8.24 January 2026: ISMS CORE Framework -> 93 Controls Completed in 53 Control Packs February 2026: ISMS CORE Operational -> 93 Controls Completed in 53 Control Packs March 2026: ISMS CORE Privacy (ISO 27701:2025) -> 21 Control Groups Completed March 2026: ISMS CORE Cloud (ISO 27018:2025) -> 12 Control Groups Completed March 2026: ISMS CORE Platform -> Live at isms-core.com April 2026: ISMS CORE AI (ISO 42001:2023) -> 12 Control Groups Completed April 2026: FR + DE + IT Translations -> All 5 Packs Complete April 2026: Threat Intelligence Expansion -> Phases 39–49 Per-connector OpenSearch indices, ENISA EUVD, Exploit-DB, MITRE ATT&CK v20, AlienVault OTX (12th OSINT source), VirusTotal enrichment, TLP labels, Threat Exposure page, 20 OSD dashboards, EBIOS RM, notification system, security audit May 2026: User Manual Updated -> Chapter 16 (Threat Intelligence) fully rewritten ``` ### Platform The **ISMS CORE Platform** (`isms-core-platform/`) is live — a FastAPI backend with PostgreSQL, OpenSearch, Docker Compose deployment, nginx TLS, and framework correlation engine. It transforms the file-based framework into a live compliance platform: DB-driven, WebUI-editable, with evidence tracking, gap management, 29 compliance assessment modules, crosswalk mapping across 59 axes (4,671 objects), and 44 automated evidence connectors pushing live evidence into per-source OpenSearch indices.

Built with the conviction that security compliance should be engineering discipline, not checkbox theater.

---

Where bamboo antennas actually work. 🎋