feat: add COS™ Blockchain Compliance Tracker module

apps/cos-compliance-tracker/.env.example

@@ -0,0 +1,2 @@
+RPC_URL_SEPOLIA=https://sepolia.infura.io/v3/YOUR_PROJECT_ID
+PRIVATE_KEY=0xYOUR_PRIVATE_KEY

apps/cos-compliance-tracker/appendix/commands.md

@@ -0,0 +1,125 @@
+
+
+# Commands & Workflow Checklist — COS™ Blockchain Compliance Tracker
+
+This document outlines the reproducibility workflow for generating SHA‑256 hashes, submitting demo transactions, verifying TxIDs, and capturing screenshots.  
+▶ For the full demo walkthrough, see the [Demo Video section in README.md](../readme.md).
+
+
+---
+
+## ⚙️ Environment Reminder
+Before running demo scripts, copy `.env.example` → `.env` and add your own Infura Project ID and Sepolia PRIVATE_KEY.  
+See `README.md` or `judge_instructions.md` for details.
+
+---
+
+## 1. Generate SHA‑256 Hashes (Local Terminal)
+
+For each governance event, run:
+
+**Linux/macOS:**
+```bash
+echo "SafetyInspection: Worker safety inspection completed on site" | sha256sum
+```
+
+**Windows (Command Prompt):**
+```powershell
+echo SafetyInspection: Worker safety inspection completed on site > event.txt
+certutil -hashfile event.txt SHA256
+```
+
+**Node.js alternative (cross‑platform):**
+```bash
+node -e "const crypto=require('crypto'); const msg='SafetyInspection: Worker safety inspection completed on site'; console.log(crypto.createHash('sha256').update(msg).digest('hex'));"
+```
+
+---
+
+## 2. Submit Demo Transaction (Blockchain Demo)
+
+Run the demo script to publish a compliance note on Sepolia:
+
+```bash
+node demo.js "SafetyInspection: Worker safety inspection completed on site"
+```
+
+Expected output (note: `hash` must match Step 1):
+```json
+{
+  "event": "SafetyInspection: Worker safety inspection completed on site",
+  "hash": "f90d04055edc258a17232db4172cd206995de4fa244a017f523e83662060977f",
+  "evidence": {
+    "txid": "0x008f0fdf9c8f96b0d4ad5bbd0063723abbeda980767d02c62a95f279d737a82c",
+    "blockNumber": 9718072,
+    "blockTimestamp": 1764250824
+  },
+  "verified": true
+}
+```
+
+---
+
+## 3. Run Offline Fallback Demo (No Sepolia ETH)
+
+If you don’t have Sepolia ETH or RPC credentials, use the fallback script:
+
+```bash
+node demo_plain.js "SafetyInspection: Worker safety inspection completed on site"
+```
+
+Expected output:
+```json
+{
+  "event": "SafetyInspection: Worker safety inspection completed on site",
+  "hash": "f90d04055edc258a17232db4172cd206995de4fa244a017f523e83662060977f",
+  "verified": false,
+  "note": "Local-only demo: no transaction submitted"
+}
+```
+
+---
+
+## 4. Verify Transaction
+
+Open Sepolia Etherscan and paste the TxID from the demo output:  
+Example:  
+[https://sepolia.etherscan.io/tx/0x008f0fdf9c8f96b0d4ad5bbd0063723abbeda980767d02c62a95f279d737a82c](https://sepolia.etherscan.io/tx/0x008f0fdf9c8f96b0d4ad5bbd0063723abbeda980767d02c62a95f279d737a82c)
+
+---
+
+## 5. Capture Screenshots
+
+Save terminal output, Etherscan verification, and audit table screenshots into:
+
+```text
+appendix/screenshots.md
+```
+
+Follow the structure:
+- Local Hash Generation  
+- Blockchain Demo Transaction  
+- Sepolia Etherscan Verification  
+- Offline Fallback Demo  
+- Audit Table Entry (from audit_table.csv)  
+
+---
+
+▶ For the full demo walkthrough, see the [Demo Video section in README.md](../readme.md).
+
+
+---
+
+## ✅ Judge Checklist
+
+By following this workflow, judges can:
+- Generate and verify SHA‑256 hashes locally  
+- Run blockchain demo and confirm TxID on Sepolia  
+- Run offline fallback demo without Sepolia ETH  
+- Capture reproducibility screenshots  
+- Confirm audit table entries  
+- Follow [judge_checklist.md](appendix/judge_checklist.md) for quick verification  
+- Watch the demo video 
+
+
+---

apps/cos-compliance-tracker/appendix/jsonld_examples.md

@@ -0,0 +1,75 @@
+
+# 📄 JSON‑LD Examples — COS™ Blockchain Compliance Tracker
+
+This appendix provides structured JSON‑LD examples of compliance notes.  
+Judges can copy/paste these snippets to verify agent behavior, interoperability, and reproducibility.
+
+---
+
+## 🛡️ Safety Inspection
+
+```json
+{
+  "@context": {
+    "schema": "http://schema.org/",
+    "cos": "https://neoplan.consult/schema/cos#"
+  },
+  "@id": "cos:SafetyInspection2025-11-27",
+  "@type": "cos:ComplianceNote",
+  "schema:name": "SafetyInspection: Worker safety inspection completed on site",
+  "schema:identifier": "4be76f5ab25de6656c0c2837c7daddba53c74ea4ed59ce33f20425c185a16f82",
+  "cos:evidence": {
+    "cos:txid": "0xbcba824f947338957ca3f9afb02abb37aba9dde7750f4f2b998baedcdc69aab3",
+    "cos:blockNumber": 9718992,
+    "cos:blockTimestamp": "2025-11-27T22:56:24Z",
+    "cos:verified": true
+  },
+  "schema:publisher": {
+    "@type": "schema:Organization",
+    "schema:name": "NeoPlan Consult Pvt. Ltd."
+  }
+}
+```
+
+---
+
+## 🌱 Carbon Permit
+
+```json
+{
+  "@context": {
+    "schema": "http://schema.org/",
+    "cos": "https://neoplan.consult/schema/cos#"
+  },
+  "@id": "cos:CarbonPermit2025-11-27",
+  "@type": "cos:ComplianceNote",
+  "schema:name": "CarbonPermit: Carbon emissions permit issued",
+  "schema:identifier": "0c00031ad51ca4e4e78de1b3312e4803f34a07468be3ae755a62436abfdeee51",
+  "cos:evidence": {
+    "cos:txid": "0x0297f64d9079cb0768a76ee949baa77484eced86217c07db5f297d60f5e4e4fc",
+    "cos:blockNumber": 9719008,
+    "cos:blockTimestamp": "2025-11-27T23:06:28Z",
+    "cos:verified": true
+  },
+  "schema:publisher": {
+    "@type": "schema:Organization",
+    "schema:name": "NeoPlan Consult Pvt. Ltd."
+  }
+}
+```
+
+---
+
+## 📌 Usage Notes
+- Each JSON‑LD snippet corresponds to a governance event logged in `audit_table.csv`.  
+- Judges can verify:
+  - **SHA‑256 hash** → matches `schema:identifier`  
+  - **TxID** → verifiable on Sepolia Etherscan  
+  - **Block number & timestamp** → confirm blockchain evidence  
+- These examples demonstrate **agent behavior** (publishing, querying, verifying) in the DKG.
+
+---
+
+**End of JSON‑LD Examples**
+
+---

apps/cos-compliance-tracker/appendix/judge_checklist.md

@@ -0,0 +1,121 @@
+
+# 🧑‍⚖️ Judge Checklist — COS™ Blockchain Compliance Tracker
+
+This checklist provides a reference for verifying the reproducibility and ethics‑first commitments of the COS™ Blockchain Compliance Tracker submission.
+
+---
+
+## ✅ Setup
+The setup process involves cloning the repository, installing dependencies, and configuring environment variables.
+
+1. Clone the repository:
+```bash
+git clone https://github.com/Constructionmgmtpractitioner/dkg-engine.git
+cd dkg-engine/apps/cos-compliance-tracker
+npm install
+```
+
+2. Configure environment:
+- Copy `.env.example` to `.env`
+- Add your **Infura Project ID** and **Sepolia PRIVATE_KEY**
+```env
+RPC_URL_SEPOLIA=https://sepolia.infura.io/v3/YOUR_PROJECT_ID
+PRIVATE_KEY=0xYOUR_PRIVATE_KEY
+```
+
+⚠️ **Important:** This repository does **not** include private credentials. Judges must use their own Infura Project ID and Sepolia wallet key to reproduce the demo.
+
+---
+
+## 🚀 Demo Verification
+The demo scripts illustrate how governance events are logged and verified.
+
+Run demo script:
+```bash
+node demo.js "SafetyInspection: Worker safety inspection completed on site"
+```
+
+Outputs governance event, SHA‑256 hash, TxID, block number, and timestamp.
+
+Run additional governance events:
+```bash
+node demo.js "QualityAudit: Independent quality audit completed"
+node demo.js "EnvironmentalCheck: Environmental compliance check passed"
+```
+
+Fallback demo (plain‑text):
+```bash
+node demo_plain.js "SafetyInspection: Worker safety inspection completed on site"
+```
+
+Provides simplified outputs for universal compatibility.
+
+---
+
+## 🔍 TxID Verification
+1. Copy a TxID from the demo output or `audit_table.csv`  
+2. Paste into [Sepolia Etherscan](https://sepolia.etherscan.io/)  
+3. Confirm block number and timestamp match demo output  
+
+---
+
+## 📊 Reproducibility Workflow
+See appendix files for reproducibility assets:
+- [commands.md](appendix/commands.md) — step‑by‑step workflow  
+- [audit_table.csv](appendix/audit_table.csv) — reproducibility ledger  
+- [screenshots.md](appendix/screenshots.md) — screenshot evidence  
+- [jsonld_examples.md](appendix/jsonld_examples.md) — structured JSON‑LD compliance notes  
+- [judge_checklist.md](appendix/judge_checklist.md) — this checklist  
+
+Judges should confirm:
+- Local SHA‑256 hash matches demo outputs  
+- TxID and block details match Sepolia Etherscan verification  
+- Offline fallback demo shows reproducibility without blockchain submission  
+- Audit table entries correspond to verified transactions  
+- **JSON‑LD structured examples in `appendix/jsonld_examples.md` match audit table and Sepolia evidence**  
+- **Screenshot6.png shows JSON‑LD compliance note aligned with audit_table.csv and Sepolia verification**
+
+---
+
+## 📊 DKG Integration (Optional Advanced Verification)
+Scripts demonstrate publishing and querying compliance notes in the OriginTrail DKG.
+
+- **Publish compliance notes**
+```bash
+node src/dkg_publish.js
+```
+
+- **Query compliance notes**
+```bash
+node src/mcp_query.js
+```
+
+- **Compute reputation scores**
+```bash
+node src/reputation_score.js
+```
+
+---
+
+▶ For the full demo walkthrough, see the [Demo Video section in README.md](../readme.md).
+The demo video illustrates the flow:  
+**Governance Event → TxID → Etherscan Verification → Audit Table → JSON‑LD Note → Reputation Score → Dashboard View**
+
+---
+
+## ⚖️ Ethics‑First Commitments
+- See `/docs/ethics_statement.md` for transparency, accountability, and sustainability principles  
+- License: CC BY 4.0  
+- Reproducibility assets: `audit_table.csv`, `commands.md`, `screenshots.md`, `jsonld_examples.md`, `judge_checklist.md`  
+
+---
+
+## 📘 References
+- COS™ Working Paper (Zenodo DOI): [10.5281/zenodo.17620309](https://doi.org/10.5281/zenodo.17620309)  
+- Ethics Statement: `/docs/ethics_statement.md`  
+- Roadmap: `/docs/roadmap.md`  
+- Governance Framework: `/docs/governance_framework.md`  
+- Challenge Alignment: `/docs/challenge_alignment.md`
+
+---
+

apps/cos-compliance-tracker/appendix/screenshots.md

@@ -0,0 +1,55 @@
+
+
+# 📸 Screenshots — COS™ Blockchain Compliance Tracker
+
+This file serves as the **index of reproducibility screenshots** for hackathon judges.  
+Each screenshot provides visual evidence of the reproducibility workflow and must match outputs from demo scripts, Etherscan verification, and audit table entries.
+
+All screenshots are stored in:
+```
+apps/cos-compliance-tracker/appendix/screenshots/
+```
+
+---
+
+## 1. Local Hash Generation
+![Terminal output showing SHA-256 hash](screenshots/screenshot1.png)
+
+---
+
+## 2. Blockchain Demo Transaction
+![Terminal output showing compliance note JSON](screenshots/screenshot2.png)
+
+---
+
+## 3. Sepolia Etherscan Verification
+![Browser window showing TxID details](screenshots/screenshot3.png)
+
+---
+
+## 4. Offline Fallback Demo
+![Terminal output showing local-only compliance note](screenshots/screenshot4.png)
+
+---
+
+## 5. Audit Table Entry
+![CSV file showing reproducibility record](screenshots/screenshot5.png)
+
+---
+
+## 6. JSON‑LD Structured Compliance Note
+![VS Code window showing JSON‑LD compliance note](screenshots/screenshot6.png)
+
+
+---
+## ✅ Judge Reminder
+Judges should confirm that:
+- Local hash matches the `hash` field in demo outputs  
+- TxID and block details match Sepolia Etherscan verification  
+- Offline fallback demo shows reproducibility without blockchain submission  
+- Audit table entry corresponds to the verified transaction  
+- Screenshots are consistent with `commands.md` and `judge_checklist.md`
+
+
+---
+

apps/cos-compliance-tracker/audit_table.csv

@@ -0,0 +1,6 @@
+Event,Description,SHA256 Hash,TxID,Block Number,Block Timestamp,Verified
+SafetyInspection: Worker safety inspection completed on site,Worker safety inspection completed on site,4be76f5ab25de6656c0c2837c7daddba53c74ea4ed59ce33f20425c185a16f82,0xbcba824f947338957ca3f9afb02abb37aba9dde7750f4f2b998baedcdc69aab3,9718992,2025-11-27T22:56:24Z,true
+CarbonPermit: Carbon emissions permit issued,Carbon emissions permit issued,0c00031ad51ca4e4e78de1b3312e4803f34a07468be3ae755a62436abfdeee51,0x0297f64d9079cb0768a76ee949baa77484eced86217c07db5f297d60f5e4e4fc,9719008,2025-11-27T23:06:28Z,true
+GenderInclusion: Gender inclusion report submitted,Gender inclusion report submitted,18b6481e1d69e9e17c1a4160fc248d420f35ae646853b9ac853765169d491333,0x7e5eff437543578084076dfb2b82f6de2dc5401e8a53e607e3a3e7d1f306a9a7,9719013,2025-11-27T23:07:40Z,true
+AuditLog: Auditor compliance check completed,Auditor compliance check completed,fc6fa89062f2c9aa8d821f6aa459b6223b6af944cc65dd931770cc8396c10654,0xd9f5a084f5c59ce21a57e2007bcfa36ccdea2e98fe280a6ca74e1cde681e496e,9719015,2025-11-27T23:08:04Z,true
+SustainabilityIndex: Sustainability index updated,Sustainability index updated,ad21997a523e70e805cfa33389c7347f15e1048638b1b72f79914c7d8122a1af,0xa047db6f61b177387f0383dda4b8a05d8d18f26770b7caedeba72c4b522e06e0,9719022,2025-11-27T23:09:40Z,true