docs(#1): establish ISO/IEC 27001-aligned developer guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,74 @@
+## Summary
+
+<!-- What changed and why? Keep this free of secrets, customer data, and undisclosed vulnerability details. -->
+
+## Linked record
+
+- Issue / change / incident:
+- Target release (if any):
+
+## Risk classification
+
+- [ ] Standard
+- [ ] High-risk — threat model and two independent approvals required
+- [ ] Emergency — incident/change approval and retrospective controls required
+
+### Security and privacy
+
+- Affected assets, trust boundaries, identities, and data classes:
+- Authentication / authorization / secrets / cryptography impact:
+- Abuse cases and controls:
+- Privacy, retention, transfer, or customer impact:
+- Residual risk or approved exception:
+
+<!-- Write "None" only after assessing the item. -->
+
+## Scope
+
+- Components and interfaces changed:
+- Deliberately out of scope:
+- Compatibility or breaking-change impact:
+- Dependencies, packages, CI actions, images, or licenses changed:
+
+## Validation evidence
+
+| Check | Command / CI job | Result |
+|---|---|---|
+| Formatting / pre-commit |  |  |
+| Lint / static / type checks |  |  |
+| Targeted tests |  |  |
+| Full tests |  |  |
+| Security / secret / dependency scans |  |  |
+| Build / package / migration |  |  |
+| Manual / integration / gateway validation |  |  |
+
+Known failures, skipped checks, or environment limitations:
+
+## Release and operations
+
+- Configuration or migration steps:
+- Deployment order and post-deployment checks:
+- Monitoring and rollback trigger:
+- Rollback or forward-fix procedure:
+- Documentation and release notes updated:
+
+## Author checklist
+
+- [ ] The change is minimal, issue-scoped, and contains no unrelated refactor or formatting.
+- [ ] I reviewed the final diff, including generated and binary files.
+- [ ] No secrets, production/customer data, personal data, or sensitive security evidence are included.
+- [ ] Server-side authorization, input validation, safe errors, and safe logging were considered.
+- [ ] Changed behavior has positive, negative, boundary, and regression tests as applicable.
+- [ ] Repository-defined checks completed on this commit; failures and skips are disclosed above.
+- [ ] Dependency and supply-chain changes were verified and pinned through the repository mechanism.
+- [ ] Migration, deployment, monitoring, compatibility, and rollback impacts are documented.
+- [ ] Documentation reflects the implemented behavior and does not overstate a control.
+- [ ] Exceptions and residual risks have a named approver, compensating control, and expiry/follow-up.
+
+## Reviewer checklist
+
+- [ ] The requirement, implementation, tests, and evidence agree.
+- [ ] Security, privacy, data, dependency, and operational impacts were reviewed.
+- [ ] The diff is focused and preserves existing contracts unless intentionally changed.
+- [ ] Required checks are current and successful on the reviewed commit.
+- [ ] Release and rollback steps are proportionate to the risk.

.github/workflows/documentation-quality.yml

@@ -0,0 +1,26 @@
+name: Documentation quality
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+minimum_pre_commit_version: "3.0.0"
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: mixed-line-ending
+        args: [--fix=lf]
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.4.0
+    hooks:
+      - id: detect-secrets
+
+  - repo: local
+    hooks:
+      - id: markdown-internal-links
+        name: validate repository-local Markdown links
+        entry: python scripts/check_markdown_links.py
+        language: system
+        files: \.md$
+        pass_filenames: false

Compliance/ISO IEC 27001 Mapping.md

@@ -0,0 +1,97 @@
+# ISO/IEC 27001:2022 Mapping
+
+## Purpose and limitation
+
+This mapping shows how the Developer Guide supports engineering-related requirements and controls in ISO/IEC 27001:2022. It is a navigation aid for the Cubewise Asia ISMS and audit evidence; it is not a Statement of Applicability, risk assessment, legal opinion, certification claim, or substitute for the licensed standards.
+
+Control applicability and implementation status MUST be determined through the organizational risk-treatment process. The ISMS owner MUST maintain the authoritative Statement of Applicability, including justification for inclusion or exclusion and the implementation status of each control.
+
+Authoritative references:
+
+- [ISO/IEC 27001:2022 — ISMS requirements](https://www.iso.org/standard/27001)
+- [ISO/IEC 27001:2022/Amd 1:2024 — Climate action changes](https://www.iso.org/standard/88435.html)
+- [ISO/IEC 27002:2022 — Information security controls](https://www.iso.org/standard/75652.html)
+- [ISO/IEC 27000 family overview](https://www.iso.org/standard/iso-iec-27000-family)
+
+## Clauses 4–10
+
+| Clause | Guide support | Example engineering evidence | ISMS dependency |
+|---|---|---|---|
+| 4 — Context | README scope, precedence, repository baseline, and this mapping | Repository scope, stakeholders, system context, customer/security requirements | Organization scope, interested parties, ISMS processes, and assessment of whether climate change is relevant under the 2024 amendment |
+| 5 — Leadership | Mandatory controls, owners, roles, segregation, and exception approval | Approved guide, repository ownership, branch protection, review records | Security policy, leadership commitment, assigned authorities |
+| 6 — Planning | Change risk classification, threat modeling, residual risk, and exceptions | Issue risk assessment, threat model, risk acceptance, remediation issue | ISMS risk method, risk register, treatment plan, objectives, Statement of Applicability |
+| 7 — Support | Repository contract, competence expectations, controlled documentation, and evidence | Onboarding/training record, current documentation, CI logs, approved tools | Resources, competence program, awareness, communication, document control |
+| 8 — Operation | Development flow, secure coding, testing, release, supplier/dependency controls | Pull requests, tests, scans, approvals, releases, deployments, rollback tests | Operational planning, outsourced-process control, formal risk-treatment operation |
+| 9 — Performance evaluation | Quality gates, monitoring evidence, review records, and baseline-failure handling | Required-check trends, defects, vulnerabilities, review and release metrics | ISMS monitoring objectives, internal audit, management review |
+| 10 — Improvement | Incident learning, regression tests, corrective actions, guide review | Root-cause record, corrective issue, updated tests/controls | Nonconformity process and continual-improvement program |
+
+The 2024 amendment adds climate-change consideration to organizational context and interested-party analysis. Engineering teams MUST implement resulting requirements when the ISMS determines they are relevant, for example resilience, hosting, supplier, capacity, continuity, or customer commitments. This guide does not make that organization-level determination.
+
+## Annex A engineering control mapping
+
+The control names below are abbreviated navigation labels. Consult the licensed standards and the Cubewise Asia Statement of Applicability for authoritative wording and applicability.
+
+| Control | Guide section | Expected evidence | Primary engineering role |
+|---|---|---|---|
+| A.5.1 Policies for information security | [README](../README.md), guide maintenance | Approved standard, review history | Engineering and ISMS owners |
+| A.5.2 Information security roles and responsibilities | [README — Roles](../README.md#roles-and-segregation-of-duties) | Ownership and reviewer records | Maintainer |
+| A.5.3 Segregation of duties | [Branch Management](../Git/Branch%20Management.md), [Development Flow](../Git/Development%20Flow.md) | Independent approvals, restricted bypass | Maintainer / Release owner |
+| A.5.7 Threat intelligence | [Secure Development — Supply chain](../Security/Secure%20Development%20Standard.md#dependencies-and-software-supply-chain) | Advisory sources, vulnerability triage | Maintainer / Security owner |
+| A.5.8 Information security in project management | [Development Flow](../Git/Development%20Flow.md) | Issue risk assessment, threat model | Product owner / Developer |
+| A.5.9 Inventory of information and associated assets | [Release Management](../Version%20Management/Release%20New%20Version.md), repository contract | Component/dependency inventory, SBOM, owners | Maintainer / Release owner |
+| A.5.10 Acceptable use of information and assets | [Engineering Standards — AI](../Engineering/Engineering%20Standards.md#ai-assisted-development), [Secrets and Data](../Security/Secrets%20and%20Data%20Handling.md) | Approved tools and handling records | Developer / Manager |
+| A.5.12–A.5.14 Classification, labelling, and transfer | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Classification, redaction, approved transfer | Information owner / Developer |
+| A.5.15–A.5.18 Access control, identity, authentication information, and access rights | [Secure Development — Authentication](../Security/Secure%20Development%20Standard.md#authentication-sessions-and-authorization) | Authn/authz tests, access reviews, least-privilege configuration | Maintainer / Security owner |
+| A.5.19–A.5.22 Supplier and ICT supply-chain security | [Secure Development — Supply chain](../Security/Secure%20Development%20Standard.md#dependencies-and-software-supply-chain) | Supplier/dependency review, lockfile, scan, remediation | Maintainer / Procurement / Security |
+| A.5.23 Cloud services | [Secure Development — CI/CD](../Security/Secure%20Development%20Standard.md#cicd-and-deployment-security), [AI and LLM](../Security/Secure%20Development%20Standard.md#ai-and-llm-features) | Approved service, region, account, access, exit/retention terms | Service owner / Security owner |
+| A.5.24–A.5.28 Incident preparation, assessment, response, learning, and evidence | [Security Policy](../SECURITY.md), exposure procedure | Private report, incident record, evidence, corrective actions | Incident owner / Developer |
+| A.5.29–A.5.30 Security during disruption and ICT readiness | [Release rollback and recovery](../Version%20Management/Release%20New%20Version.md#rollback-and-recovery), resilience controls | Recovery objectives, backups, restore/rollback test | Service / Release owner |
+| A.5.31 Legal, statutory, regulatory, and contractual requirements | README precedence, dependency and data rules | Requirement traceability, license/privacy review | Product / Legal / ISMS owner |
+| A.5.32 Intellectual property rights | [Dependencies](../Engineering/Engineering%20Standards.md#dependencies), [AI-assisted development](../Engineering/Engineering%20Standards.md#ai-assisted-development) | License review, attribution, provenance | Developer / Maintainer |
+| A.5.33 Protection of records | [README — Required evidence](../README.md#required-evidence), quality evidence | Controlled PR, CI, release, and risk records | Maintainer / ISMS owner |
+| A.5.34 Privacy and protection of PII | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Privacy impact, minimization, masking, deletion | Information / Product owner |
+| A.5.36 Compliance with policies and standards | [Quality Gates](../Engineering/Testing%20and%20Quality%20Gates.md), this mapping | CI checks, review, exceptions, audit findings | Maintainer / ISMS owner |
+| A.5.37 Documented operating procedures | Development, testing, and release procedures | Current runbooks and execution evidence | Service / Release owner |
+| A.6.3 Awareness, education, and training | README applicability and maintenance | Training/onboarding acknowledgement | Engineering manager / ISMS owner |
+| A.6.7 Remote working | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Approved device, storage, transfer, and access | Manager / User |
+| A.6.8 Information security event reporting | [Security Policy](../SECURITY.md) | Timely private report | All contributors |
+| A.8.1 User endpoint devices | Local data and secret-handling controls | Managed device and approved local storage | User / IT owner |
+| A.8.2–A.8.5 Privileged access, access restriction, source-code access, secure authentication | Authentication and CI/CD controls | Repository access, protected branches, MFA/SSO, tests | Maintainer / IT / Security |
+| A.8.6 Capacity management | [Capacity and resilience](../Security/Secure%20Development%20Standard.md#capacity-resilience-and-concurrency) | Limits, load evidence, alerts | Service owner |
+| A.8.7 Protection against malware | File, upload, dependency, and artifact controls | Malware scan and upload validation | Developer / Release owner |
+| A.8.8 Management of technical vulnerabilities | Supply-chain and vulnerability process | Inventory, scan, triage, remediation SLA/risk acceptance | Maintainer / Security owner |
+| A.8.9 Configuration management | [Engineering Standards — Configuration](../Engineering/Engineering%20Standards.md#configuration), CI/CD controls | Reviewed config, secure defaults, change history | Service owner |
+| A.8.10–A.8.12 Deletion, masking, and data leakage prevention | [Secrets and Data Handling](../Security/Secrets%20and%20Data%20Handling.md) | Retention/deletion evidence, masked data, secret scans | Information owner / Developer |
+| A.8.13–A.8.14 Backup and redundancy | Release recovery and resilience controls | Restore tests, redundancy/failover evidence | Service / Operations owner |
+| A.8.15–A.8.16 Logging and monitoring | [Secure Development — Logging](../Security/Secure%20Development%20Standard.md#logging-monitoring-and-errors) | Safe audit logs, alerts, monitored events | Service / Security owner |
+| A.8.17 Clock synchronization | [Secure Development — Logging](../Security/Secure%20Development%20Standard.md#logging-monitoring-and-errors) | Synchronized timestamps and time-source configuration | Operations / Service owner |
+| A.8.18–A.8.19 Privileged utilities and software installation | CI/CD, extension, and release controls | Restricted tools, approved packages and deployment | Maintainer / Release owner |
+| A.8.20–A.8.22 Network security and segregation | Outbound request and deployment controls | Network design, allowlists, environment separation | Architecture / Operations owner |
+| A.8.24 Use of cryptography | [Cryptography and TLS](../Security/Secure%20Development%20Standard.md#cryptography-and-tls) | Approved algorithms/services, key lifecycle, tests | Security / Service owner |
+| A.8.25 Secure development life cycle | Entire guide, especially [Development Flow](../Git/Development%20Flow.md) | End-to-end issue-to-release traceability | Engineering owner |
+| A.8.26 Application security requirements | Development risk and threat-model steps | Security acceptance criteria | Product / Security / Developer |
+| A.8.27 Secure system architecture and engineering principles | Threat modeling and secure design | Architecture decision and review | Architect / Security reviewer |
+| A.8.28 Secure coding | [Secure Development Standard](../Security/Secure%20Development%20Standard.md) | Code review and security tests | Developer / Reviewer |
+| A.8.29 Security testing in development and acceptance | [Testing and Quality Gates](../Engineering/Testing%20and%20Quality%20Gates.md) | Automated/acceptance security evidence | Developer / QA / Reviewer |
+| A.8.30 Outsourced development | Applicability, supplier, review, and evidence requirements | Contract, access, deliverable review | Engineering / Supplier owner |
+| A.8.31 Separation of development, test, and production | CI/CD and data-handling controls | Separate identities, data, configuration, approvals | Operations / Service owner |
+| A.8.32 Change management | Git, pull request, and release procedures | Issue, branch, review, checks, release record | Maintainer / Release owner |
+| A.8.33 Test information | [Testing](../Engineering/Testing%20and%20Quality%20Gates.md), [data handling](../Security/Secrets%20and%20Data%20Handling.md) | Synthetic/masked data, access and cleanup | QA / Information owner |
+| A.8.34 Protection during audit testing | Evidence and data-minimization rules | Approved audit plan, restricted evidence, cleanup | Audit / Service / Security owner |
+
+## Controls primarily outside this guide
+
+People screening and employment terms, physical security, facilities, corporate endpoint management, legal interpretation, organization-wide business continuity, internal audit, management review, and certification are primarily owned by other ISMS processes. Engineering teams MUST cooperate with those controls and retain requested evidence, but SHOULD NOT invent local substitutes or mark them complete in this repository.
+
+## Evidence review questions
+
+For each applicable control, the owner should be able to answer:
+
+1. What risk or requirement does the control address?
+2. Where is the approved procedure or technical enforcement?
+3. Who owns operation and review?
+4. What recent evidence proves the control operated?
+5. What exceptions, failures, vulnerabilities, or residual risks remain?
+6. When will effectiveness and applicability be reviewed again?
+
+A document stating that a control exists is not sufficient evidence that the control is implemented and effective.