@mudraforge/statutory 0.0.0-stage → 2.4.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to `@mudraforge/statutory` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.4.0] - 2026-10-22
+
+### Added
+- **Multi-Domain OKF v0.2 Architecture**: Reorganized statutory knowledge corpus into four foundational regulatory domains:
+  - `direct_tax` (Income-tax Act, 1961 / Income-tax Act, 2025; Section 194Q, Section 194J, Section 206C(1H) sunset)
+  - `indirect_tax_gst` (Central Goods and Services Tax Act, 2017; Section 17(5) Blocked ITC)
+  - `msme_commercial` (MSMED Act, 2006 Sections 15 & 16; delayed payments and Section 43B(h) linkage)
+  - `international_tax` (US Internal Revenue Code §§ 901 & 904; Foreign Tax Credit baskets)
+- **Executive Circulars & Compliance Forms**: Bundled 6 official executive circulars with YAML frontmatter and 8 compliance return schemas (Form 26Q, Form 16A, GSTR-2B Table 4(B), UDYAM verification, Form 67, IRS Schedule K-3).
+- **Automated OKF Validator & Linter**: Created `scripts/validate_okf.js` (`npm run validate`) enforcing schema validation, ISO date checks, `OPEN_ENDED` validity flags, and official URL checks.
+- **Cryptographic Manifest & Integrity Tooling**: Created `scripts/generate_manifest.js` calculating per-file SHA-256 hashes and a root Merkle digest (`sha256-d389...`). Added `npm run manifest:check` for tamper-evidence verification.
+- **Automated Catalog Generator**: Created `scripts/build_catalog.js` (`npm run catalog`) compiling an authoritative markdown index ([`docs/CATALOG.md`](./docs/CATALOG.md)) from the repository corpus.
+- **GitHub Actions CI Matrix**: Added `.github/workflows/ci.yml` running validation, manifest integrity check, and test suite on Ubuntu and Windows across Node.js 18.x, 20.x, and 22.x with minimal permissions (`contents: read`).
+- **Governance & Contributor Protocols**:
+  - [`CONTRIBUTING.md`](./CONTRIBUTING.md): Authoring standards for `section.json`, executive circulars, and CA review process.
+  - [`SECURITY.md`](./SECURITY.md): Responsible disclosure policy for code flaws and statutory inaccuracy triage (2-business-day acknowledgment).
+  - [`docs/DATA_LICENSING.md`](./docs/DATA_LICENSING.md): Explicit tripartite licensing separating MIT software, public domain statutes, and CC BY 4.0 structured annotations.
+  - `.github/ISSUE_TEMPLATE/`: Templates for new statute requests and legislative amendment notifications.
+  - `.github/PULL_REQUEST_TEMPLATE.md`: 7-point verification and provenance checklist.
+- **11-Suite Multi-Domain Regression Test**: Expanded `test.js` to cover all 6 provisions, boundary conditions, dead-network offline fallbacks, explicit retrieval modes, and failure cases.
+
+### Changed
+- **Explicit Retrieval Modes**: Refactored `lookupStatute()` in `src/index.js` to support explicit `mode: 'auto' | 'local' | 'edge'`. Responses return explicit `retrievalMode` (`LOCAL_SNAPSHOT` vs `EDGE_LIVE`), `isOfflineSnapshot: true`, and advisory notes to prevent stale offline data from being mistaken for real-time gazetted law.
+- **Terminal Typography**: Replaced all emojis with standards-compliant bracketed status tags (`[OK]`, `[INFO]`, `[WARN]`, `[ERROR]`, `[PASS]`) across CLI, test suites, and scripts.
+- **Temporal Alignment**: Updated temporal references to the *Income-tax Act, 2025* to reflect its effective date of 1 April 2026.
+- **Policy Alignment**: Replaced defensive maintenance wording with a grounded, transparent **Free OKF Sync and Maintenance Policy** clarifying best-effort service boundaries.
+
+### Removed
+- Deprecated legacy unversioned flat schemas in favor of domain-scoped hierarchy.

package/CONTRIBUTING.md

@@ -0,0 +1,191 @@
+# Contributing to MudraForge Statutory Substrate
+
+> **Open Knowledge Format (OKF v0.2) Contribution & Practitioner Review Guide**
+
+Thank you for your interest in contributing to `@mudraforge/statutory`. 
+
+Our mission is to build the definitive, open, machine-readable statutory knowledge substrate for Indian and cross-border commercial finance. We welcome contributions from **software engineers, AI agent builders, Chartered Accountants (CAs), CPAs, and legal compliance practitioners**.
+
+---
+
+## 1. Operating Principles & Epistemic Standards
+
+Unlike standard software libraries where code is judged primarily on execution speed, statutory knowledge repositories are judged on **statutory ground truth, temporal precision, and provenance**:
+
+1. **Official Primary Sources Only**: All statutory thresholds, rates, and rules must be sourced directly from official Union Gazettes, Central Board of Direct Taxes (CBDT), Central Board of Indirect Taxes and Customs (CBIC), Reserve Bank of India (RBI), Ministry of Corporate Affairs (MCA), or official regulatory portals. **Citations to third-party SEO blogs or unverified discussion forums are strictly rejected.**
+2. **Temporal Enforcement**: Statutory provisions must declare strict temporal boundaries (`effectivePeriod.validFrom` and `effectivePeriod.validTo` in `section.json`; `valid_from` and `valid_to` in circular YAML frontmatter, or `OPEN_ENDED` for active legislation). Sunset dates must be rigorously documented.
+3. **Fail-Closed Validation**: Every submission must pass the automated schema linter (`npm run validate`) and test suite (`npm test`) with zero defects before merge.
+
+---
+
+## 2. Structure of an OKF Statutory Provision
+
+All provisions reside under [`okf/<domain>/<provision_folder>/`](./okf/) and adhere to a 3-part layout:
+
+```
+okf/<domain>/<provision_code>/
+├── section.json                               # Core machine-readable statutory schema
+├── circulars/
+│   └── <authority>_circular_<no>_<topic>.md  # Full-text official circulars (Markdown with YAML frontmatter)
+└── forms/
+    └── <form_name>.<json|md>                  # Return schemas, verification checklists, or declarations
+```
+
+### A. Authoring `section.json`
+Every `section.json` must provide these required fields:
+
+```json
+{
+  "sectionId": "ITA1961_SEC194Q",
+  "sectionCode": "194Q",
+  "aliases": ["194Q", "194q", "goods tds", "purchase of goods"],
+  "governingStatute": "Income-tax Act, 1961 (Act No. 43 of 1961)",
+  "statutorySection": "Section 194Q",
+  "successorStatute": "Income-tax Act, 2025",
+  "successorSection": "Section 393(1), Table 8, Item (ii)",
+  "title": "Deduction of tax at source on payment of a certain sum for purchase of goods",
+  "effectivePeriod": {
+    "validFrom": "2021-07-01",
+    "validTo": "2026-03-31",
+    "annualReset": "Every April 1 (Cumulative Purchases Reset Annually)",
+    "sunsetNotes": "Transitions to Section 393(1) Table 8(ii) of the Income-tax Act, 2025 effective 1 April 2026."
+  },
+  "plainTextSummary": "Plain English summary explaining who must deduct, when, and on what base.",
+  "keyStatutoryThresholds": {
+    "buyerPriorYearTurnoverCr": 10,
+    "annualPurchaseThresholdInr": 5000000,
+    "standardDeductionRatePercent": 0.1,
+    "inoperativePanPenaltyRatePercent": 5.0,
+    "taxableBaseScope": "Tax is deductible strictly on the excess over ₹50 Lakhs, NOT on the aggregate gross turnover."
+  },
+  "officialCitations": [
+    {
+      "authority": "Central Board of Direct Taxes (CBDT)",
+      "instrument": "Circular No. 13 of 2021 (Dated 30 June 2021)",
+      "subject": "Guidelines under section 194Q - Threshold calculation & advance netting",
+      "officialUrl": "https://incometaxindia.gov.in/communications/circular/circular_13_2021.pdf"
+    }
+  ],
+  "requiredDocumentChecklist": [
+    "Valid Permanent Account Number (PAN) of Seller",
+    "Cumulative Purchase Ledger for current FY",
+    "Tax invoice with GST separately stated"
+  ],
+  "tier": "PUBLIC_COMMONS_FREE",
+  "version": "2.4.0"
+}
+```
+
+### B. Authoring Circulars (`circulars/*.md`)
+Executive circulars must include Google OKF YAML frontmatter at the top:
+
+```markdown
+---
+id: cbdt_circular_13_2021
+title: CBDT Circular No. 13 of 2021 - Guidelines under Section 194Q
+authority: Central Board of Direct Taxes (CBDT), Department of Revenue, Ministry of Finance
+date: 2021-06-30
+statutory_section: Section 194Q
+valid_from: 2021-07-01
+valid_to: 2026-03-31
+temporal_status: ACTIVE
+subject: Threshold calculation, advance payment netting, and non-resident exemption
+official_url: https://incometaxindia.gov.in/communications/circular/circular_13_2021.pdf
+---
+
+> [STATUTORY VALIDITY WINDOW & TEMPORAL STATUS]  
+> **Valid From**: 1 July 2021  
+> **Valid To**: 31 March 2026  
+> **Temporal Status**: ACTIVE  
+
+# Circular Title & Legal Guidance Body...
+```
+
+---
+
+## 3. Step-by-Step Contribution Workflow
+
+### Step 1: Fork and Clone the Repository
+```bash
+git clone https://github.com/<your-username>/mudraforge-statutory.git
+cd mudraforge-statutory
+npm install
+```
+
+### Step 2: Create a Dedicated Feature Branch
+```bash
+git checkout -b feat/add-section-194c-contractors
+```
+
+### Step 3: Implement Your Statute
+Place your files in the appropriate domain folder under `./okf/`:
+- `direct_tax/`
+- `indirect_tax_gst/`
+- `msme_commercial/`
+- `international_tax/`
+
+### Step 4: Run the Schema Linter & Validator
+We provide an automated validator that verifies all fields, dates, URLs, and frontmatter:
+```bash
+npm run validate
+```
+Ensure output finishes with: `ALL OKF SCHEMAS, CIRCULARS & FORMS PASSED VALIDATION WITH ZERO DEFECTS!`
+
+### Step 5: Run the Integration Test Suite
+```bash
+npm test
+```
+
+### Step 6: Developer Certificate of Origin (DCO 1.1) Sign-Off
+All commits must be signed off to certify that the contributor has the right to submit the code and legal annotations under the project's open licenses (MIT for code, CC BY 4.0 for OKF data).
+
+Use the `-s` or `--signoff` flag when committing:
+```bash
+git commit -s -m "feat(direct_tax): add section 194C contractor withholding"
+```
+
+By adding a `Signed-off-by:` line, you certify the following:
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+By making a contribution to this project, I certify that:
+(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
+(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license; or
+(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
+(d) I understand and agree that this project and the contribution are public and that a record of the contribution is maintained indefinitely.
+```
+
+### Step 7: Submit a Pull Request
+Push your branch to GitHub and open a Pull Request against `main`. Provide:
+1. The governing statute and section code.
+2. Official government links (Gazette, CBDT, CBIC, or RBI notifications).
+3. Any temporal effective dates or Finance Act amendments.
+
+---
+
+## 4. Starter Tasks & Good First Issues
+
+Looking to contribute? Here are recommended starter areas:
+- **Circular Updates**: Adding newly notified CBDT or CBIC circulars to existing direct tax provisions with standard YAML frontmatter.
+- **Form Schemas**: Adding JSON return schemas or GSTR-2B reconciliation templates under `okf/indirect_tax_gst/forms/`.
+- **Successor Mappings**: Adding dual-act cross-references for sections transitioning from the *Income-tax Act, 1961* to the *Income-tax Act, 2025* (taking effect 1 April 2026).
+- **Cross-Border Treaties**: Adding DTAA withholding schedules (e.g. India-US Article 12, India-Singapore Article 12) under `okf/international_tax/`.
+
+---
+
+## 5. Chartered Accountant (CA) & Legal Practitioner Empanelment
+
+If you are a Chartered Accountant (FCA/ACA), CPA, Company Secretary (CS), or tax attorney and wish to author, verify, or co-sign statutory rule packs:
+
+- Co-authored statutory packs carry official attribution in `section.json` (`reviewedBy`, `practitionerRegistrationNumber`).
+- Empanelled reviewers receive verification attribution in release notes and access to the MudraForge Enterprise Research network.
+- To join the review panel or collaborate, reach out directly to the maintainer at **`hello@mudraforge.in`** or **`mondeepe@gmail.com`**.
+
+---
+
+## 6. Security & Responsible Disclosure
+
+If you discover a vulnerability or statutory discrepancy that could lead to financial calculation errors or compliance failures, please report it privately to **`security@mudraforge.in`** or **`hello@mudraforge.in`**.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MudraForge Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.