@mudraforge/statutory 2.4.2 → 2.5.1

package/docs/OKF_MAINTENANCE_SOP.md

@@ -0,0 +1,286 @@
+# OKF Statutory Profile: Maintenance Standard Operating Procedure (SOP)
+
+> **Document Version**: 1.1.0  
+> **Classification**: Normative Engineering & Release Governance Standard  
+> **Target Substrate**: `@mudraforge/statutory` & Adesha Governance Runtime  
+> **Base Specification**: Open Knowledge Format (OKF) v0.2 (Upstream Google Specification)  
+> **Extension Profile**: MudraForge Statutory Knowledge Profile v0.2  
+
+---
+
+## 1. Purpose, Authority & Governance Boundary
+
+This Standard Operating Procedure (SOP) establishes the mandatory release discipline, authoring conventions, citation standards, cryptographic integrity controls, and verification protocols for the MudraForge Statutory Knowledge Substrate (`@mudraforge/statutory`).
+
+### 1.1 Release Control vs. Legal Correctness
+This SOP functions as a **reproducible release control and engineering quality discipline**, not as proof of absolute statutory correctness or judicial finality:
+- Passing all tests establishes conformance to the **tested requirements, mathematical formulas, and documented edge cases**. It does not independently prove that every legal interpretation is infallible or that government citations will remain valid indefinitely.
+- In accordance with regulatory AI governance principles—such as those articulated in the Reserve Bank of India (RBI) 2025 FREE-AI Committee Report (*Free and Responsible Exploration of AI in Finance*)—automated toolkits, deterministic validators, and algorithmic guardrails exist to support institutional risk management, auditability, and validation. They are **decision-support controls**, never legal or statutory substitutes for an enterprise's own fiduciary governance, internal financial controls, or qualified tax counsel.
+
+### 1.2 Target Failure Modes
+This SOP is enforced to systematically prevent:
+1. **Link Rot & Citation Drift**: Broken government URLs that degrade external inspectability and audit confidence.
+2. **Behavioral & Calculator Drift**: Discrepancies between deterministic code calculators, LLM prompt directives, and primary legislative truth.
+3. **Rollback, Replay & Tamper Vulnerabilities**: Malicious substitution, stale bundle replay, or unauthorized manipulation of statutory rules.
+4. **Sub-Domain Collisions**: Heuristic false matches between single-digit or composite statutory sections (e.g. Section 8, Section 9(3), Section 194C).
+
+---
+
+## 2. Upstream OKF Specification vs. MudraForge Statutory Profile
+
+To preserve architectural clarity, this standard strictly distinguishes between upstream Open Knowledge Format (OKF) conformance and MudraForge's additional statutory engineering profile:
+
+```mermaid
+flowchart TD
+    subgraph UPSTREAM["Upstream Google OKF v0.2 (Minimal & Portable)"]
+        direction TB
+        OKF_MD["Markdown Semantic Documentation"]
+        OKF_YAML["YAML Frontmatter Metadata (id, title, authority, dates)"]
+        OKF_DIR["Hierarchical Folder Structure by Regulatory Domain"]
+    end
+
+    subgraph PROFILE["MudraForge Statutory Profile (Engineering Extension)"]
+        direction TB
+        MF_JSON["section.json: Typed Machine Contracts & Formula ASTs"]
+        MF_CALC["Deterministic Calculation Engine (lib/core/statutory_calculator.js)"]
+        MF_HASH["SHA-256 Merkle Tree Integrity Manifests (okf/manifest.json)"]
+        MF_SIG["Ed25519 Release Pinning & Tamper-Evident Signatures"]
+        MF_FAIL["Fail-Closed Missing Evidence & Contradiction Gates"]
+    end
+
+    UPSTREAM -->|Inherited By| PROFILE
+```
+
+### 2.1 Upstream OKF Conformance
+Upstream Google OKF is a lightweight, portable knowledge representation designed for cross-agent interchange. It standardizes:
+- Markdown-based legal narratives with structured YAML frontmatter.
+- Hierarchical folder trees organized by regulatory jurisdiction and domain.
+- Self-contained, portable knowledge artifacts that can be ingested by any LLM or knowledge base.
+
+*Upstream OKF does NOT prescribe a specific calculation engine, machine-readable JSON schema, cryptographic release pipeline, or transactional runtime.*
+
+### 2.2 The MudraForge Statutory Profile
+The MudraForge Statutory Profile introduces additional normative engineering conventions on top of OKF to enable high-assurance financial automation:
+- **Typed Machine Contracts (`section.json`)**: Eliminates heuristic interpretation of numeric thresholds, currency values, and applicability conditions.
+- **Deterministic Computation**: All threshold comparisons, tax rates, excess math, and rounding execute through deterministic code on CPU (zero LLM token generation for numbers).
+- **Cryptographic Release Verification**: SHA-256 Merkle trees and Ed25519 digital signatures guarantee byte-level non-tampering from edge to endpoint.
+- **Fail-Closed Evidence Gates**: Rejection or quarantine of transactions when statutory evidence is incomplete, unverified, or contradictory.
+
+---
+
+## 3. Architectural Separation & Testable Guarantees
+
+Every statutory provision in the MudraForge profile maintains a strict division of responsibility across three distinct artifact types:
+
+```mermaid
+flowchart TD
+    subgraph ARTIFACTS["OKF Provision Directory: okf/<domain>/<statute_folder>/"]
+        SJ["section.json<br/>(Machine Contract)"]
+        CB["circulars/*.md<br/>(Semantic Executive Briefs)"]
+        FS["forms/*.json | forms/*.md<br/>(Filing Schemas & Templates)"]
+    end
+
+    subgraph ENGINE["Deterministic Execution Layer (CPU)"]
+        SJ --> CALC["statutory_calculator.js<br/>• Paisa Rounding & Excess Math<br/>• Cumulative Ledger Thresholds<br/>• Temporal Effective-Date Gates"]
+    end
+
+    subgraph REASONING["Adesha Governance Layer (LLM + Human)"]
+        CB --> LLM["Agent Reasoning<br/>• Context Synthesis<br/>• Exception Analysis<br/>• Discrepancy Detection"]
+        CB --> AUDIT["External Tax Counsel<br/>• Independent Verification<br/>• Audit Trails"]
+    end
+
+    subgraph WRITEBACK["Compliance Systems"]
+        FS --> ERP["ERP Integration<br/>• Form 26Q, GSTR-3B, MSME-1"]
+    end
+```
+
+### 3.1 Testable Guarantees
+Rather than making unprovable claims of "zero hallucination", the MudraForge profile operates under four testable and verifiable guarantees:
+
+1. **Deterministic Execution**: Calculations execute exclusively through deterministic code. Given identical inputs, rules, and effective dates, the resulting tax calculations, cumulative thresholds, and paisa rounding are mathematically invariant across all runs.
+2. **Versioned Applicability**: Legal applicability is evaluated against versioned rules, notified effective dates, and explicit statutory sunset boundaries (e.g. Section 206C(1H) sunset on 1 April 2025; Section 393 effective 1 April 2026).
+3. **Fail-Closed Handling of Uncertainty**: Missing, incomplete, or contradictory evidence triggers a fail-closed outcome (holding payments, flagging discrepancies, or requesting missing links) rather than manufacturing assumptions.
+4. **Independent Verification**: Test fixtures verify specified behaviors, edge cases, and arithmetic against independent statutory ground truth rather than trusting agent self-reports.
+
+### 3.2 Artifact Responsibilities
+
+| Artifact | Primary Consumer | Content Mandate | Operational Role |
+|---|---|---|---|
+| [`section.json`](file:///d:/work/packages/statutory/okf/direct_tax/tds_goods_194q/section.json) | **Deterministic Engine Runtime** | Typed numbers, effective dates, boolean applicability conditions, and threshold formulas. | Machine execution on CPU. Prevents mathematical drift, rate confusion, and arithmetic errors. |
+| `circulars/*.md` | **LLM Agents & Human Auditors** | Semantic legal context, executive interpretations, judicial precedents, and YAML frontmatter. | Cross-domain reasoning, statutory crosswalks, exception argumentation, and human auditability. |
+| `forms/*` | **Compliance & Reporting Systems** | Machine-evaluable JSON schemas and Markdown return checklists. | Return preparation, ERP writeback payloads, and statutory disclosure schedules. |
+
+---
+
+## 4. Citation & Link Integrity Protocol
+
+To prevent link rot caused by frequent government portal redesigns and CMS migrations, OKF provisions must follow the **Dual-Tier URL Standard**:
+
+### 4.1 Tier 1: Canonical Authority Landing Pages
+Direct PDF download paths on government websites frequently change or break during CMS updates. Therefore, official citation URLs must point to canonical, evergreen regulatory landing pages:
+- **CBDT / Direct Tax Circulars**: `https://www.incometaxindia.gov.in/pages/communications/circulars.aspx`
+- **CBDT Notifications**: `https://www.incometaxindia.gov.in/pages/communications/notifications.aspx`
+- **Income-tax Act Provisions**: `https://www.incometaxindia.gov.in/pages/acts/income-tax-act.aspx`
+- **CBIC / GST Circulars & Notifications**: `https://taxinformation.cbic.gov.in/`
+- **MSME Policies & Office Memorandums**: `https://dcmsme.gov.in/` or `https://msme.gov.in/`
+- **MCA Notifications & Orders**: `https://www.mca.gov.in/`
+- **RBI Master Directions**: `https://www.rbi.org.in/`
+- **Supreme Court of India**: `https://sci.gov.in/`
+- **ICAI Standards & Guidance Notes**: `https://www.icai.org/`
+- **US Internal Revenue Service (IRS)**: `https://www.irs.gov/`
+
+### 4.2 Tier 2: Legal Instrument Metadata
+In `section.json`, the legal instrument itself must be fully described so that statutory provenance is preserved even in offline or air-gapped environments:
+```json
+{
+  "authority": "Central Board of Direct Taxes (CBDT)",
+  "instrument": "Circular No. 13 of 2021 (Dated 30 June 2021)",
+  "subject": "Guidelines under section 194Q of the Income-tax Act, 1961 - Threshold calculation & advance netting",
+  "officialUrl": "https://www.incometaxindia.gov.in/pages/communications/circulars.aspx"
+}
+```
+
+### 4.3 Domain Whitelist Enforcement
+All citation URLs must belong to the regulatory domain whitelist defined in [`scripts/verify_citation_links.js`](file:///d:/work/packages/statutory/scripts/verify_citation_links.js). Citations to commercial blogs, paywalled content aggregators, or unvetted third-party websites are prohibited.
+
+### 4.4 Protocol Security & TLS Trust
+- **100% HTTPS Enforcement**: Insecure `http://` links are rejected by the linter.
+- **Government PKI Recognition**: Automated link verification recognizes leaf certificates issued by the Government of India Controller of Certifying Authorities (CCA / NIC CA).
+
+---
+
+## 5. The 10-Step Release Control Lifecycle
+
+Whenever authoring, updating, or amending a statutory provision, this 10-step quality discipline must be executed sequentially:
+
+```mermaid
+flowchart TD
+    S1["1. Legal Sourcing & Dual-Act Boundary"] --> S2["2. Author section.json"]
+    S2 --> S3["3. Author circulars/*.md"]
+    S3 --> S4["4. Author forms/* Schemas"]
+    S4 --> S5["5. Citation & Link Audit (npm run citations)"]
+    S5 --> S6["6. Linter & Schema Conformance (npm run validate)"]
+    S6 --> S7["7. Merkle Manifest Re-Gen (npm run manifest)"]
+    S7 --> S8["8. Client Pinning & Ed25519 Signing"]
+    S8 --> S9["9. Dual Regression Testing (Package + Engine)"]
+    S9 --> S10["10. SemVer Release & Distribution"]
+```
+
+### Step 1: Legal Sourcing & Dual-Act Temporal Boundary
+1. Identify primary legislation: Act name, Section number, notified effective date.
+2. Determine temporal classification:
+   - `ACTIVE`: Currently in force under current legislation.
+   - `SUNSET_SUPERSEDED`: Subject to statutory sunset (e.g. Section 206C(1H) on 1 April 2025).
+   - `FUTURE_LAW`: Enacted forward law (e.g. Income-tax Act, 2025 Section 393 on 1 April 2026).
+3. Enforce deterministic calculator isolation in `statutory_calculator.js`.
+
+### Step 2: Author `section.json` Machine Contract
+- Declare mandatory fields: `sectionId`, `sectionCode`, `aliases`, `governingStatute`, `statutorySection`, `successorStatute`, `successorSection`, `title`, `effectivePeriod`, `plainTextSummary`, `keyStatutoryThresholds`, `officialCitations`, `requiredDocumentChecklist`, `tier`, `version`.
+- Standardize all search aliases in lowercase or official legal codes (e.g. `["194q", "sec194q", "tds goods"]`).
+
+### Step 3: Author Circulars (`circulars/*.md`)
+- Enforce strict YAML frontmatter (`id`, `title`, `authority`, `date`, `statutory_section`, `valid_from`, `valid_to`, `temporal_status`, `subject`, `official_url`).
+- Provide clear executive summaries detailing commercial application, tax base unbundling rules, and statutory exceptions.
+
+### Step 4: Author Compliance Forms (`forms/*`)
+- Supply machine-evaluable JSON schemas or Markdown checklists for compliance returns and statutory disclosures.
+
+### Step 5: Citation & Link Integrity Audit
+Run the automated citation verification suite:
+```powershell
+npm run citations
+```
+To run live network probing across all endpoints:
+```powershell
+node scripts/verify_citation_links.js --live
+```
+*Pass Criteria*: 0 syntax errors, 0 unauthorized domains, 0 HTTP failures.
+
+### Step 6: Schema Conformance & Syntax Validation
+Validate structure and conformance against test fixtures:
+```powershell
+npm run validate
+npm run conformance
+```
+*Pass Criteria*: 100% schemas valid, 12/12 conformance fixtures passing, 0 defects.
+
+### Step 7: Cryptographic Merkle Manifest Re-generation
+Recompute per-file SHA-256 hashes and update the root Merkle digest:
+```powershell
+npm run manifest
+npm run manifest:check
+```
+Record the resulting root hash in release notes.
+
+### Step 8: Client Pinning & Trust Anchor Verification
+1. Add the updated root digest to `PINNED_RELEASE_ROOTS` in [`src/index.js`](file:///d:/work/packages/statutory/src/index.js).
+2. For remote edge synchronization, verify Ed25519 digital signature validation against the MudraForge Root Authority.
+
+### Step 9: Dual Regression Testing
+Execute both package unit tests and the core engine verification suite:
+```powershell
+# 1. Package Regression Suite (49 tests)
+npm run test
+
+# 2. Engine Unified Test Runner (68 suites)
+npm --prefix ../../mudraforge-sarvam test
+
+# 3. Adesha Benchmark Runner (6 scenarios)
+node ../../mudraforge-sarvam/tests/benchmarks/adesha_benchmark_challenge_01_runner.js
+```
+*Pass Criteria*: 100% passing across all 123 test suites and benchmark scenarios with 0 regressions.
+
+### Step 10: SemVer Release & Distribution
+1. Bump package version in `package.json` and synchronize `STATUTORY_CLIENT_VERSION` in `src/index.js`.
+2. Document all changes in `CHANGELOG.md`.
+3. Publish package to the public registry: `npm publish --access public`.
+4. Deploy / seed edge catalogs on Cloudflare Workers KV.
+5. Verify in a clean downstream consumer project (`scratch/fresh_public_npm_consumer`).
+
+---
+
+## 6. Anti-Drift & Security Invariants
+
+All engineers and automated agents contributing to OKF provisions must uphold five mandatory invariants:
+
+| Invariant | Operational Requirement | Verification Mechanism |
+|---|---|---|
+| **Rule 2: Stale Reference Scan** | After renaming or deprecating any provision, scan the entire codebase for stale references. | PowerShell `Get-ChildItem -Recurse \| Select-String` returns zero matches. |
+| **Rule 3: Single Execution Path** | No duplicate inline calculators. All dispatchers delegate to canonical `statutory_calculator.js`. | Unit tests confirm identical mathematical output across all entrypoints. |
+| **Rule 4: Regex User Input Escaping** | User-supplied search queries must be sanitized with `replace(/[.*+?^${}()\|[\]\\]/g, '\\$&')`. | Unit tests verify queries containing `(`, `)`, `[`, `]`, `*`. |
+| **Rule 5: No Dead Schema Parameters** | Every parameter declared in `section.json` must be evaluated by the execution runtime. | Parameter mapping audit in `statutory_commons.js`. |
+| **Rule 11: Statutory Truth Over Engine Output** | Calculations and effective dates must match independent legal ground truth, not merely agent agreement. | Parameterized test suites testing cumulative prior purchases and temporal dates. |
+
+---
+
+## 7. Verifiable Release Artifacts & Evidence Ledger
+
+Claims of test passage and release integrity are substantiated by the following reproducible artifacts:
+
+| Verification Layer | Active Release Evidence | Location / Verification Command |
+|---|---|---|
+| **Cryptographic Root** | `sha256-3f25fc3941d29de5b8befc0ddb24d1bb2632067f00b200680cf784961616424c` | `npm run manifest:check` across all 59 files |
+| **Citation Network Liveness** | 70/70 passing citations across 13 regulatory domains (0 failures) | `node scripts/verify_citation_links.js --live` |
+| **Statutory Schema Conformance** | 18/18 sections, 19 circulars, 22 forms passing OKF v0.2 linter | `npm run validate` |
+| **Package Regression** | 49/49 test suites passing with 100% reproducible precision | `npm run test` in `packages/statutory` |
+| **Engine Invariant Regression** | 68/68 test suites passing across governance runtime and TLA+ oracles | `npm test` in `mudraforge-sarvam` |
+| **Adesha Benchmark Challenge 01** | 6/6 scenarios scored (Base 100/100, Variants A-E verified) | `node mudraforge-sarvam/tests/benchmarks/adesha_benchmark_challenge_01_runner.js` |
+| **Live NPM Consumer** | Installed and verified live from registry in clean consumer | `node scratch/fresh_public_npm_consumer/test_live_npm_benchmark.js` |
+
+---
+
+## 8. Pre-Flight Maintenance Checklist
+
+Before closing any maintenance task or cutting a new release, verify that each item is completed:
+
+- [ ] All 18 statutory provisions contain complete and valid `section.json` contracts.
+- [ ] Every citation URL uses `https://` and resolves to an approved regulatory domain.
+- [ ] `npm run citations` reports 0 defects and 0 unauthorized domains.
+- [ ] `npm run validate` passes with 0 schema errors.
+- [ ] `npm run conformance` passes 12/12 fixture tests.
+- [ ] `npm run manifest:check` verifies all 59 files against SHA-256 digests.
+- [ ] `PINNED_RELEASE_ROOTS` in `src/index.js` includes the active manifest root hash.
+- [ ] Two-pass precision lookup correctly resolves single-digit sections (`8`, `9(3)`).
+- [ ] All 49 package tests and 68 engine regression suites pass with 0 failures.
+- [ ] Stale reference scan returns zero matches for deprecated names or legacy domains.
+- [ ] Version number in `package.json` exactly matches `STATUTORY_CLIENT_VERSION`.

package/docs/PILOT_EVALUATION_GUIDE.md

@@ -0,0 +1,149 @@
+# MudraForge Adesha — Proposed Accounts Payable Pilot Evaluation Guide
+## Protocol for Bounded Historical Shadow Audits
+
+> **Document Type**: Proposed Enterprise Pilot Specification  
+> **Status**: Proposed Pilot Protocol (Not evidence of an active commercial customer deployment)  
+> **Target Audience**: Chief Financial Officers (CFOs), Heads of Tax, Accounts Payable Directors, Enterprise Risk Officers  
+
+---
+
+## 1. Context & Purpose
+
+This document outlines a proposed, non-invasive evaluation protocol for enterprise finance teams seeking to assess the statutory accuracy and audit capabilities of MudraForge Adesha.
+
+A core operational challenge in corporate finance operations is ensuring consistent adherence to complex statutory withholding regimes, cumulative financial-year threshold tracking, and commercial delayed-payment regulations without disrupting active business operations. 
+
+This proposed pilot enables an organization to test MudraForge's deterministic statutory engine against **historical, customer-approved accounts payable records** in a strictly read-only, advisory setting before considering any live workflow integration.
+
+---
+
+## 2. Pilot Objective
+
+The primary objective of the proposed pilot is to evaluate historical vendor transactions against machine-readable statutory baselines to identify potential discrepancies in:
+1. **Withholding Tax (TDS) Classification**: Proper categorization under Section 194C (Contractors: 1% individual vs. 2% company), Section 194J (Technical Services 2% vs. Professional 10%), Section 194I (Rent: 2% machinery vs. 10% land/building), and Section 194H (Commission: 2% post-October 2024 vs. 5% prior).
+2. **Cumulative FY Threshold Handling**: Verifying whether cumulative vendor payments properly triggered statutory deduction gates upon crossing legal limits (e.g., Section 194Q ₹50 Lakhs excess, Section 194C ₹1 Lakh aggregate / ₹30,000 single bill).
+3. **GST Unbundling Adherence**: Checking whether withholding tax was deducted strictly on basic contract value or incorrectly calculated on gross invoice amounts including separately stated GST (CBDT Circular No. 23 of 2017).
+4. **Legislative Sunset Adherence**: Confirming that seller TCS under Section 206C(1H) was not applied to transactions post-1 April 2025.
+5. **MSME Delayed Payment Compliance**: Flagging payments to verified Micro and Small enterprises exceeding 15 days (oral) or 45 days (written agreement) under Sections 15 and 16 of the MSMED Act, 2006, along with associated Section 43B(h) disallowance risks.
+
+---
+
+## 3. Proposed Candidate Inputs & Progressive Staging
+
+To minimize operational effort for the customer's finance team, the proposed evaluation follows a staged approach:
+
+- **Stage 1 (Initial Calibration Sample — 30 to 50 Invoices)**: Begin with a targeted, representative sample of 30 to 50 historical invoices with known deduction outcomes and supporting records. This verifies column mappings, confirms ingestion formatting, and calibrates baseline rules with minimum time investment from the client.
+- **Stage 2 (Expanded Audit — 200 to 500 Invoices)**: Once the workflow, field mapping, and review protocols are established in Stage 1, the evaluation can expand to a full quarter's volume (200 to 500 records) to assess broad cumulative thresholds (such as Section 194Q and 194C cumulative annual limits).
+
+To perform the evaluation, the customer provides an export (CSV or structured tabular extract) containing the following fields:
+
+| Field Group | Required Parameters | Purpose in Evaluation |
+| :--- | :--- | :--- |
+| **Transaction Metadata** | Invoice Number, Invoice Date, Booking Date | Evaluates temporal validity and applicable legislative regime (1961 Act vs. 2025 Act). |
+| **Vendor Identity** | Vendor Legal Name, Entity Type (Individual, Firm, Co.), Vendor PAN, GSTIN | Determines applicable rate schedules (e.g. 1% vs 2% under 194C; 20% under 206AA if PAN missing). |
+| **Financial Values** | Basic Taxable Amount, CGST, SGST, IGST, Total Invoice Gross Amount | Verifies basic-value unbundling vs. gross withholding. |
+| **Statutory Classification** | Line-item expense description, historical TDS section applied, historical TDS amount deducted | Compares historical treatment against engine ground truth. |
+| **Settlement Dates** | Payment / Clearance Date, Payment Method | Measures settlement timelines against the MSMED statutory payment clock. |
+| **Enterprise Attributes** | Vendor MSME Registration Type (Micro, Small, Medium, Trader), Udyam Number (if on file) | Filters MSME delayed-payment rules (applying trader exclusion under OM 2/1(5)/2021). |
+
+---
+
+## 4. Processing Workflow & Exception Handling
+
+The evaluation runs as an offline, non-intrusive batch process:
+
+```
+[Customer AP Extract] ──► Input Validation ──► Statutory Rule Engine ──► Discrepancy Analysis ──► Human Review Gate
+                                                                                                    ↓
+                                                                                        [Advisory Audit Report]
+```
+
+### The Human-in-the-Loop Ambiguity Standard
+In real-world finance operations, certain vendor invoices present legal ambiguities that cannot be resolved from numbers alone (e.g., mixed composite contracts involving both equipment supply and installation labour).
+
+- **Explicit Fail-Closed Policy**: The evaluation engine does not guess or force an arbitrary classification on ambiguous transactions.
+- **Flagged Review Categories**: When input data lacks sufficient granularity (such as missing scope-of-work documentation or ambiguous GST itemization), the system categorizes the record as `REQUIRES_HUMAN_REVIEW` with an explicit note explaining the legal assumption required.
+
+---
+
+## 5. Pilot Deliverables
+
+At the conclusion of the evaluation, the customer receives an **Advisory Accounts Payable Discrepancy & Verification Report** comprising:
+
+1. **Executive Findings Summary**:
+   - Total records evaluated vs. records with complete statutory determinability.
+   - Aggregate count of matched historical treatments.
+   - Aggregate count of flagged statutory variances.
+2. **Detailed Discrepancy Register (Tri-Part Classification)**:
+   Findings are strictly classified into three distinct categories to avoid premature legal assumptions:
+   - **Category A — Confirmed Calculation Differences**: Mathematical or rounding discrepancies on settled statutory rates, unbundled GST arithmetic, or clearly crossed financial thresholds.
+   - **Category B — Potential Statutory Discrepancies**: Inconsistent rates or threshold treatments where all input facts (PAN, entity type, invoice date) appear complete on the face of the record.
+   - **Category C — Items Requiring External Documentation Verification**: Apparent rate differences that may be legally justified by unrecorded external documents (e.g. an Assessing Officer certificate for lower deduction under Section 197, a Section 194C(6) goods transporter ownership declaration, or an MSME trader NIC classification exclusion). The report flags these as *verification checkpoints* rather than claiming a tax error.
+3. **Statutory Audit Trail**:
+   - For every flagged variance: the exact governing statute, applicable section code, official Gazette citation, and relevant CBDT/CBIC executive circular.
+4. **Unresolved Assumptions Log**:
+   - Comprehensive inventory of records requiring internal company tax counsel determination.
+
+> **Important Commercial Notice**: The pilot report is strictly analytical and advisory. MudraForge does not guarantee that a pilot will discover historical errors, recoverable tax sums, or cash savings; the value of the evaluation is establishing an empirical baseline of compliance consistency.
+
+### What the Proposed Pilot Demonstrates vs. What It Cannot Establish
+
+| What the Pilot Can Demonstrate | What It Cannot Establish by Itself |
+| :--- | :--- |
+| The engine can process customer-supplied historical invoice extracts. | It can seamlessly ingest every ERP or arbitrary billing format without custom mapping. |
+| Calculations agree with independently verified tax outcomes on clear-cut cases. | Every statutory interpretation or tax deduction across all scenarios is legally infallible. |
+| Discrepancies and assumptions are fully traceable to primary gazette citations. | The client will necessarily achieve a specific financial saving or tax recovery. |
+| Repeat runs on the same input data produce mathematically identical results. | Production deployment readiness, real-time banking security, or live ERP integration. |
+
+---
+
+## 6. Security, Confidentiality & Data Handling
+
+> **Confidentiality Note on Historical Data**: Historical accounts payable records are not zero-risk. Invoices contain confidential supplier identities, commercial pricing structures, PANs, and banking metadata. Running locally or within customer-designated infrastructure minimizes external exposure, but strict data handling, field masking, and deletion agreements remain mandatory prerequisites before transferring any real records.
+
+To protect enterprise data, the pilot protocol defines clear operational boundaries:
+
+### Verified Baseline Capabilities
+- **Local / On-Premise Execution Option**: The core evaluation engine and statutory commons can execute locally within the customer's designated environment with zero external network connectivity.
+- **Read-Only Scope**: The evaluation accesses only historical records provided by the customer. It contains no programmatic write access to the customer's ERP, general ledger, or banking infrastructure.
+
+### Pilot Prerequisites (To Be Agreed in Writing Prior to Initiation)
+Prior to transferring any sample data or initiating evaluation scripts, the parties will establish:
+1. **Bilateral Non-Disclosure Agreement (NDA)**: Governing proprietary financial and supplier pricing data.
+2. **Customer-Side Field Masking / Anonymization**: The customer may optionally hash or mask sensitive fields (such as bank account numbers or internal vendor IDs) prior to transmission.
+3. **Data Retention & Disposal Schedule**: Agreement on secure disposal of evaluation extracts within a defined period (e.g., 30 days post-report delivery).
+4. **Environment Specification**: Mutual agreement on whether processing occurs on customer-controlled workstations or a private cloud environment.
+
+---
+
+## 7. Strict Operational Boundaries
+
+To prevent operational ambiguity, the boundaries of this proposed pilot are explicitly defined:
+
+- **No Live Ledger Mutations**: The pilot will not post journal entries, alter general ledger balances, or modify vendor records in the customer's accounting system (SAP, Zoho Books, Tally, NetSuite).
+- **No Money Movement**: The pilot does not connect to banking APIs, issue payment orders, or disburse funds.
+- **No Regulatory Filing**: The pilot does not generate or submit Form 26Q returns or TDS challans to the Income Tax Department.
+- **Not Formal Legal Advice**: Deliverables constitute technical compliance analysis and do not replace legal opinions from the customer's statutory tax auditors or legal counsel.
+
+---
+
+## 8. Success & Evaluation Criteria
+
+Before initiating a pilot, both parties agree to measurable evaluation benchmarks:
+
+| Criterion | Definition | Evaluation Metric |
+| :--- | :--- | :--- |
+| **Input Completeness** | Sufficiency of customer data to determine statutory applicability | Percentage of records with complete necessary fields ($\ge 90\%$ target) |
+| **Calculation Accuracy** | Agreement on clear-cut cases governed by settled law | $100\%$ mathematical and threshold agreement on verified records |
+| **Ambiguity Handling** | Clean separation of uncertain cases without hallucinated conclusions | $100\%$ of incomplete or composite records flagged for human review |
+| **Statutory Traceability** | Every variance cited to primary gazette or executive circular | $100\%$ citation resolution to official government sources |
+| **Audit Reproducibility** | Repeated runs across the same dataset produce identical outputs | Zero variance across repeat deterministic runs |
+
+---
+
+## 9. Initiating a Pilot Discussion
+
+To discuss a proposed historical AP evaluation, review sample schema formats, or coordinate data requirements:
+- **Email**: [hello@mudraforge.in](mailto:hello@mudraforge.in) or [support@mudraforge.in](mailto:support@mudraforge.in)
+- **Direct Founder Contact**: Mondeep Engti at [mondeepe@gmail.com](mailto:mondeepe@gmail.com)
+- **Official Documentation**: [https://mudraforge.in/docs](https://mudraforge.in/docs)

package/okf/corporate_ma_restructuring/slump_sale_50b/circulars/cbdt_notification_68_2021_rule_11uae_fmv.md

@@ -8,7 +8,7 @@ valid_from: 2021-04-01
 valid_to: OPEN_ENDED
 temporal_status: ACTIVE
 subject: Computation of Full Value of Consideration for Slump Sale under Section 50B(2)(ii)
-official_url: https://incometaxindia.gov.in/communications/notification/notification_68_2021.pdf
+official_url: https://www.incometaxindia.gov.in/pages/communications/notifications.aspx
 ---
 
 > [STATUTORY VALIDITY WINDOW & TEMPORAL STATUS]  

package/okf/corporate_ma_restructuring/slump_sale_50b/circulars/cbic_notification_12_2017_going_concern_exemption.md

@@ -8,7 +8,7 @@ valid_from: 2017-07-01
 valid_to: OPEN_ENDED
 temporal_status: ACTIVE
 subject: Services by way of transfer of a going concern, as a whole or an independent part thereof, attract 0% GST (exempt supply)
-official_url: https://cbic-gst.gov.in/pdf/central-tax-rate/notf-12-2017-cgst-rate-english.pdf
+official_url: https://taxinformation.cbic.gov.in/
 ---
 
 > [STATUTORY VALIDITY WINDOW & TEMPORAL STATUS]  

package/okf/corporate_ma_restructuring/slump_sale_50b/section.json

@@ -40,19 +40,19 @@
       "authority": "Income Tax Department, Ministry of Finance",
       "instrument": "Section 50B, Income-tax Act, 1961",
       "subject": "Special provision for computation of capital gains in case of slump sale",
-      "officialUrl": "https://incometaxindia.gov.in/acts/income-tax-act-1961/section-50b.htm"
+      "officialUrl": "https://www.incometaxindia.gov.in/pages/acts/income-tax-act.aspx"
     },
     {
       "authority": "Central Board of Direct Taxes (CBDT)",
       "instrument": "Notification No. 68/2021 (Dated 24 May 2021)",
       "subject": "Rule 11UAE: Computation of fair market value of capital assets for the purposes of section 50B",
-      "officialUrl": "https://incometaxindia.gov.in/communications/notification/notification_68_2021.pdf"
+      "officialUrl": "https://www.incometaxindia.gov.in/pages/communications/notifications.aspx"
     },
     {
       "authority": "Central Board of Indirect Taxes and Customs (CBIC)",
       "instrument": "Notification No. 12/2017-Central Tax (Rate) Entry 2",
       "subject": "Services by way of transfer of a going concern, as a whole or an independent part thereof, attract 0% GST",
-      "officialUrl": "https://cbic-gst.gov.in/pdf/central-tax-rate/notf-12-2017-cgst-rate-english.pdf"
+      "officialUrl": "https://taxinformation.cbic.gov.in/"
     }
   ],
   "requiredDocumentChecklist": [

package/okf/direct_tax/tcs_goods_206c_1h/circulars/finance_act_2025_sunset_memo.md

@@ -10,7 +10,7 @@ valid_to: 2025-03-31
 temporal_status: SUNSET_OMITTED
 sunset_effective_date: 2025-04-01
 successor_rule: Section 194Q buyer TDS applies conditionally
-official_url: https://incometaxindia.gov.in/communications/circular/circular_17_2020.pdf
+official_url: https://www.incometaxindia.gov.in/pages/communications/circulars.aspx
 ---
 
 > [TEMPORAL STATUS: SUNSET & OMITTED]  

package/okf/direct_tax/tcs_goods_206c_1h/section.json

@@ -31,13 +31,13 @@
       "authority": "Parliament of India / Ministry of Finance",
       "instrument": "Finance Act, 2025 (Section 206C(1H) Sunset Clause)",
       "subject": "Omission of Section 206C(1H) effective 1 April 2025",
-      "officialUrl": "https://incometaxindia.gov.in/communications/circular/circular_17_2020.pdf"
+      "officialUrl": "https://www.incometaxindia.gov.in/pages/communications/circulars.aspx"
     },
     {
       "authority": "Central Board of Direct Taxes (CBDT)",
       "instrument": "Circular No. 17 of 2020",
       "subject": "Guidelines for collection of tax at source under section 206C(1H)",
-      "officialUrl": "https://incometaxindia.gov.in/communications/circular/circular_17_2020.pdf"
+      "officialUrl": "https://www.incometaxindia.gov.in/pages/communications/circulars.aspx"
     }
   ],
   "requiredDocumentChecklist": [

package/okf/direct_tax/tds_commission_194h/circulars/finance_act_2024_rate_cut_memo.md

@@ -0,0 +1,29 @@
+---
+id: finance_act_2024_194h_rate_cut
+title: Finance (No. 2) Act, 2024 - Reduction of TDS Rate on Commission and Brokerage
+authority: Parliament of India / Ministry of Finance
+date: 2024-08-16
+statutory_section: Section 194H
+valid_from: 2024-10-01
+valid_to: OPEN_ENDED
+temporal_status: ACTIVE
+subject: Statutory reduction of TDS deduction rate on commission or brokerage from 5% to 2%
+official_url: https://incometaxindia.gov.in
+---
+
+> [STATUTORY VALIDITY WINDOW & TEMPORAL STATUS]  
+> **Valid From**: 1 October 2024  
+> **Valid To**: OPEN_ENDED  
+> **Temporal Status**: ACTIVE  
+> **Applicable Principle**: Tax deduction rate on commission/brokerage is 2% for payments made or credited on or after 1 October 2024 (previously 5%).  
+
+# Finance (No. 2) Act, 2024: Amendment to Section 194H
+
+## 1. Statutory Amendment
+Section 194H of the Income-tax Act, 1961 was amended by the Finance (No. 2) Act, 2024 (Act No. 15 of 2024) to reduce the rate of withholding tax on commission or brokerage:
+- Prior to 1 October 2024: 5%
+- On or after 1 October 2024: 2%
+
+## 2. Invariable Conditions
+- Threshold of ₹15,000 in aggregate per financial year remains unchanged.
+- Failure to furnish PAN continues to attract 20% deduction under Section 206AA.

package/okf/direct_tax/tds_commission_194h/forms/form_26q_quarterly_return.json

@@ -0,0 +1,30 @@
+{
+  "formId": "FORM_26Q_194H",
+  "title": "Quarterly Statement of Tax Deducted at Source on Payment of Commission or Brokerage",
+  "applicableSectionCode": "194H",
+  "tdsSectionCode": "94H",
+  "governingRule": "Income-tax Rules, 1962 (Rule 31A)",
+  "filingFrequency": "QUARTERLY",
+  "dueDates": {
+    "Q1_Apr_Jun": "July 31",
+    "Q2_Jul_Sep": "October 31",
+    "Q3_Oct_Dec": "January 31",
+    "Q4_Jan_Mar": "May 31"
+  },
+  "requiredChallanFields": [
+    "BSR_CODE_7_DIGIT",
+    "CHALLAN_TENDER_DATE",
+    "CHALLAN_SERIAL_NO_5_DIGIT",
+    "TAX_DEPOSITED_AMOUNT_INR",
+    "MAJOR_HEAD_0021_OR_0020"
+  ],
+  "deducteeRecordFields": [
+    "PAN_OF_BROKER_OR_AGENT",
+    "NAME_OF_BROKER_OR_AGENT",
+    "GROSS_COMMISSION_PAID_OR_CREDITED_INR",
+    "TDS_RATE_APPLIED_PERCENT",
+    "TAX_DEDUCTED_AMOUNT_INR",
+    "DATE_OF_DEDUCTION",
+    "REASON_FOR_LOWER_OR_NON_DEDUCTION"
+  ]
+}

package/okf/direct_tax/tds_commission_194h/section.json

@@ -0,0 +1,63 @@
+{
+  "sectionId": "ITA1961_SEC194H",
+  "sectionCode": "194H",
+  "aliases": [
+    "194H",
+    "194h",
+    "sec194h",
+    "commission tds",
+    "brokerage tds",
+    "tds on commission",
+    "brokerage"
+  ],
+  "governingStatute": "Income-tax Act, 1961 (Act No. 43 of 1961)",
+  "statutorySection": "Section 194H",
+  "successorStatute": "Income-tax Act, 2025",
+  "successorSection": "Section 393(1), Table 4, Item (i)",
+  "title": "Deduction of tax at source on commission or brokerage",
+  "effectivePeriod": {
+    "validFrom": "2001-06-01",
+    "validTo": "2026-03-31",
+    "annualReset": "Every April 1 (Cumulative Commission Resets Annually)",
+    "sunsetNotes": "Transitions to Section 393(1) Table 4 Item (i) of the Income-tax Act, 2025 effective 1 April 2026."
+  },
+  "plainTextSummary": "Any person responsible for paying any income by way of commission or brokerage to a resident is required to deduct tax at source. Statutory Rate: 2% effective 1 October 2024 as amended by Finance (No. 2) Act, 2024 (prior to 1 October 2024, the rate was 5%). Threshold: Tax is deductible only if the aggregate amount of commission or brokerage credited or paid during the financial year exceeds ₹15,000. Statutory Exclusions: Does not apply to insurance commission (covered under Section 194D) or underwriting commission. Non-PAN penalty rate under Section 206AA is 20%. Under CBDT Circular 23/2017, where GST is separately stated, TDS applies on commission excluding GST.",
+  "keyStatutoryThresholds": {
+    "annualAggregateThresholdInr": 15000,
+    "standardRatePercent": 2.0,
+    "preOct2024RatePercent": 5.0,
+    "rateChangeEffectiveDate": "2024-10-01",
+    "nonCompliantPanPenaltyRatePercent": 20.0,
+    "commissionBrokerageScope": "Includes any payment received or receivable, directly or indirectly, by a person acting on behalf of another person for services rendered (not being professional services) or in the course of buying or selling of goods or in relation to any transaction relating to any asset, valuable article or thing, not being securities.",
+    "cbdtCircular23GstExclusion": "TDS applies on basic commission amount excluding separately stated GST."
+  },
+  "officialCitations": [
+    {
+      "authority": "Parliament of India / Ministry of Finance",
+      "instrument": "Finance (No. 2) Act, 2024 (Act No. 15 of 2024) amending Section 194H",
+      "subject": "Reduction of TDS rate on commission and brokerage from 5% to 2% w.e.f. 1 October 2024",
+      "officialUrl": "https://incometaxindia.gov.in"
+    },
+    {
+      "authority": "Parliament of India / Ministry of Finance",
+      "instrument": "Income-tax Act, 2025 Section 393(1), Table 4, Item (i)",
+      "subject": "TDS on commission and brokerage under new Direct Tax Code",
+      "officialUrl": "https://incometaxindia.gov.in"
+    },
+    {
+      "authority": "Central Board of Direct Taxes (CBDT)",
+      "instrument": "Circular No. 23 of 2017",
+      "subject": "Exclusion of GST component from value of commission for tax deduction at source",
+      "officialUrl": "https://www.incometaxindia.gov.in/pages/communications/circulars.aspx"
+    }
+  ],
+  "requiredDocumentChecklist": [
+    "Brokerage / Agency Agreement establishing commercial terms and commission structure",
+    "Agent / Broker PAN verification",
+    "Cumulative Commission Ledger for current FY establishing date threshold of ₹15,000 was crossed",
+    "Broker commission billing invoice with GST separately indicated",
+    "Lower deduction certificate under Section 197 / Section 395 (if agent provides certificate)"
+  ],
+  "tier": "PUBLIC_COMMONS_FREE",
+  "version": "2.5.0"
+}