@mudraforge/statutory 2.7.0 → 2.8.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [2.8.0] - 2026-10-25
+
+### Added
+- **Dual-Act Statutory Crosswalk Engine (`crosswalk`)**:
+  - Implemented `crosswalkStatute()` in core library and exposed via `npx @mudraforge/statutory crosswalk <section> [--credit <date>] [--payment <date>] [--date <date>] [--json]`.
+  - Bridges provisions across the *Income-tax Act, 1961* and *Income-tax Act, 2025* (taking effect 1 April 2026).
+  - Enforces statutory withholding crystallization rule: tax withholding liability attaches on the earlier of credit in books or payment disbursement.
+  - Cites statutory savings authority under Section 536 of Income-tax Act, 2025 read with Section 6 of General Clauses Act, 1897.
+  - Correctly evaluates Section 206C(1H) seller TCS statutory sunset and formal omission w.e.f. 1 April 2025.
+  - Supports bidirectional crosswalks (both forward from 1961 Act and backward from 2025 Act).
+- **Semantic Regulatory Diff & Amendment Tracker (`diff`)**:
+  - Implemented `getStatutoryDiff()` and exposed via `npx @mudraforge/statutory diff [--section <sec>] [--since <date>] [--domain <domain>] [--json]`.
+  - Compiles structured semantic regulatory changelogs across all 5 statutory domains.
+  - Tracks key legislative amendments: Section 194H rate cut (5% to 2% w.e.f. 2024-10-01), Section 206C(1H) sunset omission, Rule 48(4) e-invoicing ₹5 Cr threshold, Section 16(2)(aa) GSTR-2B mandatory matching, Section 43B(h) MSME disallowance, and Section 393 2025 Act transition.
+- **StatutoryClient Parity**:
+  - Added `client.crosswalk()`, `client.diff()`, `client.verify()`, and `client.doctor()` methods to `StatutoryClient`.
+- **Cryptographic Substrate Verifier (`verify`)**:
+  - Implemented `verifyLocalSubstrate()` in core library and exposed via `npx @mudraforge/statutory verify [path]`.
+  - Cryptographically verifies local file-level SHA-256 hashes against `manifest.json` (Integrity) and validates root Merkle digests against immutable release roots / Ed25519 signatures (Authenticity).
+  - Enforces mandatory statutory baseline policy checks (`194Q`, `194J`, `17(5)`, `MSMED-15-16`, `393`).
+- **Diagnostic Environment Doctor (`doctor`)**:
+  - Implemented `runStatutoryDoctor()` in core library and exposed via `npx @mudraforge/statutory doctor [--offline]`.
+  - Diagnoses Node.js runtime (`>= v18`), OS platform, environment variables, local OKF filesystem health, and optional Cloudflare Anycast edge round-trip latency.
+  - Fully supports air-gapped / isolated VPC environments via `--offline` / `-o` without failing local health guarantees.
+- **Global Machine-Readable Output (`--json`)**:
+  - Added `--json` / `-j` flag support across all CLI commands (`verify`, `doctor`, `lookup`, `list`, `browse`, `decode-id`, `check-update`).
+  - Emits clean, parseable JSON directly to `stdout` (suppressing banners, spinners, and update prompts) for CI/CD automation and `jq` scripting.
+- **MudraForge Custom Exit Code Contract**:
+  - Established standardized exit codes: `0` (Success), `1` (Usage/Syntax error), `2` (Integrity/Security failure), `3` (Statutory policy violation).
+- **Documentation & Release Alignment**:
+  - Unified package, manifest, and publication versions at `v2.8.0`.
+  - Extracted formal audit ledger into `docs/PROVENANCE.md` and streamlined main `README.md` for fast developer onboarding.
+
+---
+
 ## [2.7.0] - 2026-10-25
 
 ### Added

package/README.md

@@ -36,37 +36,21 @@ console.log(statute.statute.title); // MSMED statutory payment timelines & compo
 
 ---
 
-### Plain-English Orientation
+## Overview
 
-`@mudraforge/statutory` provides an open, machine-readable statutory knowledge layer for Indian and cross-border financial workflows, grounding compliance rules in primary legislation rather than probabilistic LLM guesswork. It serves software developers building financial applications, corporate finance operations teams seeking auditable withholding and delayed-payment rules, and autonomous AI agents requiring deterministic reference boundaries. The statutory commons acts as an open, inspectable reference substrate, while MudraForge's broader Adesha initiative governs downstream transactional execution, human authorization, and enterprise ledger writebacks. Developers can proceed directly to [Installation & Quick Start](#quick-start-free-tier), while finance leaders, controllers, and tax practitioners can inspect the indexed statutes, cumulative thresholds, and executive circulars in [docs/CATALOG.md](./docs/CATALOG.md).
+`@mudraforge/statutory` is an offline, zero-dependency statutory knowledge substrate for Indian and cross-border financial compliance (Direct Tax, GST, MSME, Corporate M&A, International Tax). It grounds withholding rates, cumulative thresholds, and filing timelines in primary legislation and circulars rather than ungrounded LLM text generation.
 
-> **Statutory Dual-Act Temporal Boundary**: The *Income-tax Act, 2025* takes statutory effect on 1 April 2026. Relevant earlier tax years and prior transactions continue to be governed by the *Income-tax Act, 1961* under legislative transitional savings provisions (including Section 536(2) of the 2025 Act). This package explicitly models both legislative eras with date-bound temporal state machine evaluation.
+* **Deterministic Knowledge**: Provides structured, offline rule definitions (`okf/**/section.json`) and ISO Mod-36 identifier decoding without outbound network calls.
+* **Dual-Act Temporal Boundary**: Explicitly models both the *Income-tax Act, 1961* and the *Income-tax Act, 2025* (effective 1 April 2026), evaluating date-bound transitional savings rules automatically.
+* **Separation of Concerns**: This open-source commons provides declarative statutory truth; downstream transactional execution, payment authorization, and bank disbursements belong to the governed execution layer (Adesha).
 
----
-
-## Published Release & Provenance Ledger
-
-| Item | Value |
-|---|---|
-| **Package Release** | **`v2.4.2`** (Public Beta) |
-| **Knowledge Specification** | **Google Open Knowledge Format (OKF v0.2) + MudraForge Statutory Schema Extension** |
-| **Regulatory Snapshot** | **CBDT / CBIC / MCA / MSME Baseline: October 2026** |
-| **Corpus Quality Card** | 100% Citation Resolution (15/15 URLs) in [`docs/CORPUS_QUALITY.md`](./docs/CORPUS_QUALITY.md) |
-| **Architecture Decision Records** | 6 Normative ADRs documented in [`docs/ARCHITECTURE_DECISIONS.md`](./docs/ARCHITECTURE_DECISIONS.md) |
-| **Vendor Conformance Suite** | 12/12 Passing Fixture Tests in [`conformance/`](./conformance/) |
-| **End-to-End Execution Trace** | Audited 7-stage AP lifecycle in [`examples/`](./examples/) (`npm run example:trace`) |
-| **Enterprise Assurance Preview** | Formal TLA+ & mutation defenses in [`docs/ADESHA_ASSURANCE_OVERVIEW.md`](./docs/ADESHA_ASSURANCE_OVERVIEW.md) |
-| **Integrity Root** | SHA-256 root manifest in [`okf/manifest.json`](./okf/manifest.json) (reproducible byte-level non-tampering proof) |
-| **Temporal Framework** | Dual-Act Bridge: *Income-tax Act, 1961* & *Income-tax Act, 2025* |
-| **Verification Gate** | 100% Pass across cumulative thresholds, legislative sunsets, and excess math |
-
-> **Note on Cryptographic Scope**: The SHA-256 root hash in `okf/manifest.json` provides mathematical verification of **byte-level integrity** (ensuring local files have not been corrupted, altered, or partially written). A hash certifies that bytes match the published release; it does not by itself constitute legal or statutory authority. Epistemic authority is established strictly via the primary gazette citations, CBDT/CBIC executive circulars, and independent ground-truth tests.
+> For cryptographic root digests, normative specifications, and formal assurance artifacts, see [docs/PROVENANCE.md](./docs/PROVENANCE.md).
 
 ---
 
 ## Table of Contents
 
-- [Plain-English Orientation](#plain-english-orientation)
+- [Overview](#overview)
 - [Quick Start (Free Tier)](#quick-start-free-tier)
   - [1. Installation via npm](#1-installation-via-npm)
   - [2. Initialize AI Agent Skill](#2-initialize-ai-agent-skill)
@@ -81,7 +65,7 @@ console.log(statute.statute.title); // MSMED statutory payment timelines & compo
 - [Structured OKF Directory Hierarchy](#structured-okf-domain-hierarchy-zero-token-discovery)
 - [Canonical Edge Synchronization](#canonical-edge-synchronization-full-statutory-universe)
 - [Enterprise Tier (Paid Cloud Execution)](#enterprise-tier-paid-cloud-execution--analysis-mode)
-  - [Edge API Endpoints & Quotas](#enterprise-edge-api-endpoints--quotas)
+  - [Edge API Endpoints & Rate Limits](#enterprise-edge-api-endpoints--rate-limits)
   - [Error Semantics & Response Codes](#error-semantics--response-codes)
 - [System Origin & Validation Baseline](#system-origin--validation-baseline)
 - [The Payment Instruction Boundary & End-to-End AP Architecture](#the-payment-instruction-boundary--end-to-end-ap-architecture)
@@ -427,6 +411,55 @@ const isActive2024 = await isStatuteActive('206C(1H)', '2024-05-01'); // true
 const isActive2025 = await isStatuteActive('206C(1H)', '2025-06-01'); // false (omitted by Finance Act, 2025)
 ```
 
+### 4. CLI Verification, Auditing & Pipeline Integration
+
+The CLI provides cryptographic provenance checking, offline integrity verification, and machine-readable JSON output for CI/CD audit pipelines:
+
+```bash
+# Run full environment, local substrate health, and edge latency diagnostics
+npx @mudraforge/statutory doctor
+
+# Force air-gapped / offline diagnostics (zero outbound network requests)
+npx @mudraforge/statutory doctor --offline
+
+# Cryptographically verify local statutory substrate integrity & origin authenticity
+npx @mudraforge/statutory verify
+
+# Dual-act 1961 <-> 2025 statutory crosswalk (earlier of credit vs payment)
+npx @mudraforge/statutory crosswalk 194Q --credit 2026-03-25 --payment 2026-04-10
+
+# Reverse crosswalk from 2025 Act provision
+npx @mudraforge/statutory crosswalk 393 --date 2025-08-01
+
+# Query semantic regulatory changelog and amendment tracker
+npx @mudraforge/statutory diff --section 194H
+npx @mudraforge/statutory diff --since 2025-01-01
+npx @mudraforge/statutory diff --domain indirect_tax_gst
+
+# Output machine-parseable JSON for CI/CD or jq integration
+npx @mudraforge/statutory crosswalk 194Q --credit 2026-03-25 --payment 2026-04-10 --json
+npx @mudraforge/statutory diff --section 194H --json
+npx @mudraforge/statutory verify --json
+npx @mudraforge/statutory doctor --json --offline
+
+# Query section in pure JSON format
+npx @mudraforge/statutory lookup 194Q --json
+
+# Decode and validate PAN / GSTIN offline with ISO Mod-36 checksum
+npx @mudraforge/statutory decode-id 27AAPFU0939F1ZV --json
+```
+
+#### Custom MudraForge Exit Code Contract
+Calling pipelines and CI/CD audit steps can inspect `$?` directly:
+
+| Exit Code | Classification | Meaning |
+|---|---|---|
+| `0` | `SUCCESS` | Substrate verified authentic, intact, and all baseline provisions present. |
+| `1` | `USAGE_OR_OPERATIONAL_ERROR` | Invalid CLI arguments, unknown command, or syntax error. |
+| `2` | `INTEGRITY_OR_SECURITY_VIOLATION` | Cryptographic signature failure, unpinned root hash, file tampering, or revoked key. |
+| `3` | `STATUTORY_POLICY_VIOLATION` | Statutory policy failure (e.g. missing mandatory baseline provision or sunset violation). |
+
+
 ---
 
 ## Enterprise Tier (Paid Cloud Execution & Analysis Mode)
@@ -453,9 +486,9 @@ console.log(result.taxableBase); // ₹70,00,000 (Calculates strictly on excess
 console.log(result.taxAmount);   // ₹7,000 (0.1% TDS on taxable base)
 ```
 
-### Enterprise Edge API Endpoints & Quotas
+### Enterprise Edge API Endpoints & Rate Limits
 
-| Endpoint | Method | Auth Required | Quota Limit | Response |
+| Endpoint | Method | Auth Required | Rate Limit (Per Client / IP) | Response |
 |---|---|---|---|---|
 | `/api/v1/statutory/sections` | `GET` | No | 180 req/min | JSON array of indexed OKF sections |
 | `/api/v1/statutory/lookup` | `GET` | No | 180 req/min | Parametric section details & temporal validity |
@@ -487,7 +520,7 @@ All error responses from `@mudraforge/statutory` and the hosted edge API return
 | `405 Method Not Allowed` | `METHOD_NOT_ALLOWED` | Non-GET request sent to read-only commons endpoints. |
 | `413 Payload Too Large` | `PAYLOAD_TOO_LARGE` | JSON request body on `/calculate` exceeds 64KB security threshold. |
 | `415 Unsupported Media` | `UNSUPPORTED_MEDIA_TYPE` | Non-JSON payload sent to calculation engine. Set `Content-Type: application/json`. |
-| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Request quota breached. Check `Retry-After` header before retrying. |
+| `429 Too Many Requests` | `RATE_LIMIT_EXCEEDED` | Rate limit threshold breached. Check `Retry-After` header before retrying. |
 
 ---
 

package/bin/cli.js

@@ -18,6 +18,11 @@ import {
     getLocalManifest,
     checkForPackageUpdate,
     decodeTaxIdentifier,
+    verifyLocalSubstrate,
+    runStatutoryDoctor,
+    crosswalkStatute,
+    getStatutoryDiff,
+    STATUTORY_EXIT_CODES,
     STATUTORY_CLIENT_VERSION,
     DEFAULT_LOCAL_OKF_DIR
 } from '../src/index.js';
@@ -25,11 +30,65 @@ import {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const args = process.argv.slice(2);
+const rawArgs = process.argv.slice(2);
+const isJsonMode = rawArgs.includes('--json') || rawArgs.includes('-j');
+const isOfflineMode = rawArgs.includes('--offline') || rawArgs.includes('-o');
+const args = rawArgs.filter(a => a !== '--json' && a !== '-j' && a !== '--offline' && a !== '-o');
 const command = args[0] ? args[0].toLowerCase() : 'help';
 
+function getNamedArg(nameList, argList) {
+    for (let i = 0; i < argList.length; i++) {
+        const item = argList[i];
+        for (const name of nameList) {
+            if (item === name && i + 1 < argList.length && !argList[i + 1].startsWith('-')) {
+                return argList[i + 1];
+            }
+            if (item.startsWith(`${name}=`)) {
+                return item.slice(name.length + 1);
+            }
+        }
+    }
+    return null;
+}
+
 async function main() {
     switch (command) {
+        case 'doctor':
+        case 'diagnose':
+            await handleDoctor();
+            break;
+
+        case 'verify':
+        case 'audit':
+        case 'check':
+            await handleVerify(args[1]);
+            break;
+
+        case 'crosswalk':
+        case 'bridge':
+        case 'transition': {
+            const section = (args[1] && !args[1].startsWith('-')) ? args[1] : getNamedArg(['--section', '-s'], rawArgs);
+            const creditDate = getNamedArg(['--credit', '-c'], rawArgs);
+            const paymentDate = getNamedArg(['--payment', '-p'], rawArgs);
+            const asOfDate = getNamedArg(['--date', '-d', '--as-of'], rawArgs);
+            if (!section) {
+                console.error('[ERROR] Please specify a section to crosswalk, e.g. npx @mudraforge/statutory crosswalk 194Q --credit 2026-03-25 --payment 2026-04-10');
+                process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+            }
+            await handleCrosswalk(section, { creditDate, paymentDate, asOfDate });
+            break;
+        }
+
+        case 'diff':
+        case 'changelog':
+        case 'amendments': {
+            const section = (args[1] && !args[1].startsWith('-')) ? args[1] : getNamedArg(['--section', '-s'], rawArgs);
+            const since = getNamedArg(['--since'], rawArgs);
+            const domain = getNamedArg(['--domain'], rawArgs);
+            await handleDiff({ section, since, domain });
+            break;
+        }
+
         case 'init-skill':
         case 'install-skill':
             await handleInitSkill(args[1]);
@@ -90,7 +149,7 @@ async function main() {
     }
 
     // Non-intrusive background npm package update notice
-    if (!['check-update', 'status', 'version'].includes(command)) {
+    if (!isJsonMode && !['check-update', 'status', 'version', 'verify', 'audit', 'check', 'crosswalk', 'bridge', 'transition', 'diff', 'changelog', 'amendments'].includes(command)) {
         try {
             const updateInfo = await checkForPackageUpdate();
             if (updateInfo && updateInfo.updateAvailable) {
@@ -103,23 +162,244 @@ async function main() {
     }
 }
 
+async function handleVerify(targetDir) {
+    try {
+        let dest = DEFAULT_LOCAL_OKF_DIR;
+        if (targetDir) {
+            dest = path.resolve(process.cwd(), targetDir);
+        }
+        const report = verifyLocalSubstrate(dest);
+        if (isJsonMode) {
+            console.log(JSON.stringify(report, null, 2));
+            process.exit(report.exitCode);
+        }
+
+        console.log('\n===========================================================================');
+        console.log(`MUDRAFORGE OPEN KNOWLEDGE FORMAT (OKF) — CRYPTOGRAPHIC VERIFIER [v${report.okfVersion || 'Unknown'}]`);
+        console.log('===========================================================================');
+
+        if (report.integrity.valid) {
+            console.log(`[OK] Integrity: ${report.integrity.totalFilesChecked} files verified against Merkle manifest.`);
+            console.log(`     Root Merkle Hash: ${report.integrity.computedRoot}`);
+        } else {
+            console.error(`[FAIL] Integrity: Mismatches: ${report.integrity.mismatches.length}, Missing: ${report.integrity.missingFiles.length}, Untracked: ${report.integrity.untrackedFiles.length}`);
+            for (const m of report.integrity.mismatches) {
+                console.error(`     • ${m.file} (Expected ${m.expected.slice(0, 10)}..., actual ${m.actual.slice(0, 10)}...)`);
+            }
+            for (const mf of report.integrity.missingFiles) {
+                console.error(`     • Missing: ${mf}`);
+            }
+        }
+
+        if (report.authenticity.valid) {
+            console.log(`[OK] Authenticity: Provenance authenticated via ${report.authenticity.method}.`);
+            if (report.authenticity.keyId) {
+                console.log(`     Signer Key ID: ${report.authenticity.keyId}`);
+            }
+        } else {
+            console.error(`[FAIL] Authenticity: Root hash "${report.integrity.computedRoot}" is neither pinned nor signed by an authorized MudraForge trust anchor.`);
+        }
+
+        if (report.baselineCheck.valid) {
+            console.log(`[OK] Statutory Policy: All mandatory baseline provisions present (${report.baselineCheck.baselineSections.join(', ')}).`);
+        } else {
+            console.error(`[FAIL] Statutory Policy: Missing mandatory baseline provisions: ${report.baselineCheck.missingBaseline.join(', ')}`);
+        }
+
+        console.log('───────────────────────────────────────────────────────────────────────────');
+        if (report.valid) {
+            console.log(`[PASS] Statutory substrate is authentic, intact, and compliant (Exit ${report.exitCode}).\n`);
+        } else {
+            console.error(`[FAIL] Verification failed with Exit Code ${report.exitCode}.\n`);
+        }
+        process.exit(report.exitCode);
+    } catch (err) {
+        if (isJsonMode) {
+            console.log(JSON.stringify({ valid: false, exitCode: STATUTORY_EXIT_CODES.USAGE_ERROR, error: err.message }, null, 2));
+        } else {
+            console.error(`[ERROR] Verification error: ${err.message}`);
+        }
+        process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+    }
+}
+
+async function handleDoctor() {
+    try {
+        const report = await runStatutoryDoctor({ offline: isOfflineMode });
+        if (isJsonMode) {
+            console.log(JSON.stringify(report, null, 2));
+            process.exit(report.exitCode);
+        }
+
+        console.log('\n===========================================================================');
+        console.log(`MUDRAFORGE STATUTORY DIAGNOSTIC DOCTOR [v${report.clientVersion}]`);
+        console.log('===========================================================================');
+
+        console.log('── 1. RUNTIME & HOST ENVIRONMENT ──');
+        console.log(`Node.js:           ${report.runtime.nodeVersion} ${report.runtime.isSupportedNode ? '(Supported: v18+)' : '[UNSUPPORTED]'}`);
+        console.log(`Platform:          ${report.runtime.platform} (${report.runtime.arch})`);
+        console.log(`Environment:       ${report.runtime.environment}${report.runtime.isCI ? ' (CI Active)' : ''}`);
+        console.log(`API Key Config:    ${report.runtime.hasApiKey ? 'CONFIGURED (Enterprise Tier Enabled)' : 'NOT_CONFIGURED (Free Commons Mode)'}`);
+
+        console.log('\n── 2. LOCAL OKF SUBSTRATE HEALTH ──');
+        if (report.substrate.valid) {
+            console.log(`Directory:         ${DEFAULT_LOCAL_OKF_DIR}`);
+            console.log(`Manifest Version:  v${report.substrate.okfVersion} (Published: ${report.substrate.publishedAt})`);
+            console.log(`Files Checked:     ${report.substrate.integrity.totalFilesChecked} (0 mismatches, 0 missing, 0 untracked)`);
+            console.log(`Root Merkle Hash:  ${report.substrate.integrity.computedRoot}`);
+            console.log(`Integrity:         PASS`);
+            console.log(`Provenance:        AUTHENTIC (${report.substrate.authenticity.method})`);
+            console.log(`Statutory Policy:  PASS (All ${report.substrate.baselineCheck.baselineSections.length} mandatory baselines present)`);
+        } else {
+            console.error(`Substrate:         FAILED (Exit Code ${report.substrate.exitCode})`);
+            if (report.substrate.error) console.error(`Error:             ${report.substrate.error}`);
+            if (!report.substrate.integrity.valid) {
+                console.error(`Integrity Failure: ${report.substrate.integrity.mismatches.length} mismatch(es), ${report.substrate.integrity.missingFiles.length} missing files.`);
+            }
+            if (!report.substrate.authenticity.valid) {
+                console.error(`Authenticity:      Root hash not authenticated.`);
+            }
+            if (!report.substrate.baselineCheck.valid) {
+                console.error(`Missing Baselines: ${report.substrate.baselineCheck.missingBaseline.join(', ')}`);
+            }
+        }
+
+        console.log('\n── 3. CLOUDFLARE ANYCAST EDGE CONNECTIVITY ──');
+        console.log(`Endpoint:          ${report.edge.baseUrl}`);
+        if (report.edge.status === 'REACHABLE') {
+            console.log(`Status:            REACHABLE (Latency: ${report.edge.latencyMs}ms)`);
+        } else if (report.edge.status === 'SKIPPED_AIR_GAPPED') {
+            console.log(`Status:            SKIPPED (Air-Gapped / Offline Flag Enabled)`);
+        } else {
+            console.log(`Status:            ${report.edge.status} (Offline-first local mode operative)`);
+        }
+        console.log(`Advisory:          ${report.edge.advisory}`);
+
+        console.log('───────────────────────────────────────────────────────────────────────────');
+        if (report.healthy) {
+            console.log(`[PASS] All diagnostic checks passed with zero defects (Exit 0).\n`);
+        } else {
+            console.error(`[FAIL] Diagnostic doctor flagged health violations (Exit ${report.exitCode}).\n`);
+        }
+        process.exit(report.exitCode);
+    } catch (err) {
+        if (isJsonMode) {
+            console.log(JSON.stringify({ healthy: false, exitCode: STATUTORY_EXIT_CODES.USAGE_ERROR, error: err.message }, null, 2));
+        } else {
+            console.error(`[ERROR] Doctor diagnostic error: ${err.message}`);
+        }
+        process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+    }
+}
+
+async function handleCrosswalk(section, options) {
+    try {
+        const result = crosswalkStatute(section, options);
+        if (isJsonMode) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(0);
+        }
+
+        console.log('\n===========================================================================');
+        console.log('MUDRAFORGE DUAL-ACT STATUTORY CROSSWALK (1961 ACT <-> 2025 ACT)');
+        console.log('===========================================================================');
+        console.log(`Query Section:       ${result.querySection}`);
+        console.log(`Governing Statute:   ${result.governingAct}`);
+        console.log(`Applicable Section:  ${result.applicableSection}`);
+        console.log(`Temporal Status:     ${result.temporalStatus}`);
+
+        console.log('\n── TEMPORAL CRYSTALLIZATION (EARLIER OF CREDIT OR PAYMENT) ──');
+        if (result.creditDate) console.log(`Credit in Books:     ${result.creditDate}`);
+        if (result.paymentDate) console.log(`Payment Rail:        ${result.paymentDate}`);
+        console.log(`Trigger Date:        ${result.triggerDate}`);
+        console.log(`Trigger Event:       ${result.triggerReason}`);
+        console.log(`Event Context:       ${result.triggerDescription}`);
+
+        console.log('\n── STATUTORY BRIDGE & DUAL-ACT MAPPING ──');
+        console.log(`Predecessor (1961):  ${result.crosswalk.predecessor.statutorySection} (${result.crosswalk.predecessor.title})`);
+        console.log(`                     Rate: ${result.crosswalk.predecessor.standardRate} | Challan: ${result.crosswalk.predecessor.challan} | Return: ${result.crosswalk.predecessor.returnForm}`);
+        console.log(`Successor (2025):    ${result.crosswalk.successor.statutorySection} (Effective ${result.crosswalk.successor.effectiveDate})`);
+        console.log(`                     Rate: ${result.crosswalk.successor.standardRate} | Return: ${result.crosswalk.successor.returnForm}`);
+
+        console.log('\n── STATUTORY SAVINGS & LEGAL GROUNDING ──');
+        console.log(`Primary Authority:   ${result.crosswalk.savingsAuthority.statute}`);
+        console.log(`Subsidiary Principle: ${result.crosswalk.savingsAuthority.subsidiary}`);
+        console.log(`Legal Analysis:      ${result.legalAnalysis}`);
+
+        console.log('───────────────────────────────────────────────────────────────────────────');
+        console.log('[PASS] Statutory crosswalk resolved successfully (Exit 0).\n');
+        process.exit(0);
+    } catch (err) {
+        if (isJsonMode) {
+            console.log(JSON.stringify({ status: 'ERROR', exitCode: STATUTORY_EXIT_CODES.USAGE_ERROR, error: err.message }, null, 2));
+        } else {
+            console.error(`[ERROR] Crosswalk failure: ${err.message}`);
+        }
+        process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+    }
+}
+
+async function handleDiff(options) {
+    try {
+        const result = getStatutoryDiff(options);
+        if (isJsonMode) {
+            console.log(JSON.stringify(result, null, 2));
+            process.exit(0);
+        }
+
+        console.log('\n===========================================================================');
+        console.log('MUDRAFORGE STATUTORY REGULATORY CHANGELOG & AMENDMENT TRACKER');
+        console.log('===========================================================================');
+        console.log(`Filter Section:      ${result.filterSection || 'ALL SECTIONS'}`);
+        console.log(`Filter Since:        ${result.filterSince || 'ALL TIME'}`);
+        console.log(`Filter Domain:       ${result.filterDomain || 'ALL DOMAINS'}`);
+        console.log(`Total Amendments:    ${result.totalAmendments}`);
+
+        if (result.amendments.length === 0) {
+            console.log('\n[NOTICE] No statutory amendments matched the specified query filters.');
+        } else {
+            for (const am of result.amendments) {
+                console.log(`\n── [${am.id}] ${am.sectionCode} (${am.domain}) ──`);
+                console.log(`Title:               ${am.title}`);
+                console.log(`Effective Date:      ${am.effectiveDate} (${am.amendmentType})`);
+                console.log(`Governing Statute:   ${am.statute}`);
+                console.log(`Enacted By:          ${am.legalAuthority}`);
+                console.log(`Previous Baseline:   ${am.previousValue}`);
+                console.log(`Amended Baseline:    ${am.amendedValue}`);
+                console.log(`Summary:             ${am.changeSummary}`);
+                console.log(`Statutory Impact:    ${am.statutoryImpact}`);
+            }
+        }
+
+        console.log('───────────────────────────────────────────────────────────────────────────');
+        console.log(`[PASS] Statutory diff completed successfully (${result.totalAmendments} amendment(s) found) (Exit 0).\n`);
+        process.exit(0);
+    } catch (err) {
+        if (isJsonMode) {
+            console.log(JSON.stringify({ status: 'ERROR', exitCode: STATUTORY_EXIT_CODES.USAGE_ERROR, error: err.message }, null, 2));
+        } else {
+            console.error(`[ERROR] Statutory diff failure: ${err.message}`);
+        }
+        process.exit(STATUTORY_EXIT_CODES.USAGE_ERROR);
+    }
+}
+
 async function handleCheckUpdate() {
     try {
-        console.log('\n[INFO] Checking npm package version against registry.npmjs.org...');
+        let pkgUpdate = null;
         try {
-            const pkgUpdate = await checkForPackageUpdate({ cacheTtlMs: 0 });
-            if (pkgUpdate && pkgUpdate.updateAvailable) {
-                console.log('───────────────────────────────────────────────────────────────────────────');
-                console.log(`[WARN] New npm package version available: v${pkgUpdate.latestVersion} (installed: v${pkgUpdate.currentVersion})`);
-                console.log(`Run: npm install @mudraforge/statutory@latest`);
-                console.log('───────────────────────────────────────────────────────────────────────────');
-            } else if (pkgUpdate) {
-                console.log(`[OK] npm package code is up to date (v${pkgUpdate.currentVersion}).`);
-            }
+            pkgUpdate = await checkForPackageUpdate({ cacheTtlMs: 0 });
         } catch (_) {}
 
-        console.log('\n[INFO] Checking OKF knowledge substrate status against Cloudflare edge...');
         const status = await checkUpdates();
+
+        if (isJsonMode) {
+            console.log(JSON.stringify({
+                packageUpdate: pkgUpdate,
+                substrateStatus: status
+            }, null, 2));
+            process.exit(0);
+        }
         console.log('───────────────────────────────────────────────────────────────────────────');
         console.log(`Local OKF Version:   ${status.localVersion}`);
         console.log(`Latest Edge Version: ${status.latestVersion}`);
@@ -186,6 +466,18 @@ async function handleSync(targetDir) {
 async function handleBrowse() {
     const manifest = getLocalManifest();
 
+    if (isJsonMode) {
+        console.log(JSON.stringify(manifest ? {
+            okfVersion: manifest.okfVersion,
+            publishedAt: manifest.publishedAt,
+            rootHash: manifest.rootHash,
+            totalSections: manifest.totalSections,
+            domains: manifest.domains,
+            sections: manifest.sections
+        } : { okfVersion: null, sections: [] }, null, 2));
+        process.exit(0);
+    }
+
     console.log('\n===========================================================================');
     console.log(`OPEN KNOWLEDGE FORMAT (OKF) — LOCAL BROWSER [v${manifest ? manifest.okfVersion : 'Local'}]`);
     console.log('===========================================================================');
@@ -283,18 +575,28 @@ async function handleLookup(section, asOfDate) {
         let temporalStatus = 'ACTIVE';
 
         if (s) {
-            console.log(`\n[LOCAL OKF CACHE] Loaded section [${cleanSection}] from disk.`);
+            if (!isJsonMode) console.log(`\n[LOCAL OKF CACHE] Loaded section [${cleanSection}] from disk.`);
             if (asOfDate) {
                 if (asOfDate < s.effectivePeriod.validFrom) temporalStatus = 'PRE_EFFECTIVE';
                 else if (s.effectivePeriod.validTo && asOfDate > s.effectivePeriod.validTo) temporalStatus = 'SUNSET_SUPERSEDED';
             }
         } else {
-            console.log(`\n[EDGE LOOKUP] Querying MudraForge Live Commons for [${cleanSection}]${asOfDate ? ` (as-of: ${asOfDate})` : ''}...`);
+            if (!isJsonMode) console.log(`\n[EDGE LOOKUP] Querying MudraForge Live Commons for [${cleanSection}]${asOfDate ? ` (as-of: ${asOfDate})` : ''}...`);
             const remote = await lookupStatute(cleanSection, { asOfDate });
             s = remote.statute;
             temporalStatus = remote.temporalStatus;
         }
 
+        if (isJsonMode) {
+            console.log(JSON.stringify({
+                status: 'SUCCESS',
+                sectionCode: cleanSection,
+                temporalStatus,
+                statute: s
+            }, null, 2));
+            process.exit(0);
+        }
+
         console.log('───────────────────────────────────────────────────────────────────────────');
         console.log(`Section:         ${s.statutorySection} (${s.governingStatute})`);
         console.log(`Title:           ${s.title}`);
@@ -324,6 +626,14 @@ async function handleLookup(section, asOfDate) {
         }
         console.log('───────────────────────────────────────────────────────────────────────────\n');
     } catch (err) {
+        if (isJsonMode) {
+            console.error(JSON.stringify({
+                status: 'ERROR',
+                error: err.message,
+                availableSections: err.availableSections || []
+            }, null, 2));
+            process.exit(1);
+        }
         console.error(`[ERROR] Lookup failed: ${err.message}`);
         if (err.availableSections) {
             console.log(`Available sections: ${err.availableSections.join(', ')}`);
@@ -334,8 +644,13 @@ async function handleLookup(section, asOfDate) {
 
 async function handleList() {
     try {
-        console.log('\n[INFO] Fetching indexed statutory sections from MudraForge Commons...');
         const sections = await listSections();
+        if (isJsonMode) {
+            console.log(JSON.stringify({ sections, total: sections.length }, null, 2));
+            process.exit(0);
+        }
+
+        console.log('\n[INFO] Fetching indexed statutory sections from MudraForge Commons...');
         console.log('───────────────────────────────────────────────────────────────────────────');
         for (const s of sections) {
             const displayValidTo = (s.validTo === 'OPEN_ENDED' || s.validTo === '2099-12-31') ? 'In Force' : s.validTo;
@@ -343,6 +658,10 @@ async function handleList() {
         }
         console.log('───────────────────────────────────────────────────────────────────────────\n');
     } catch (err) {
+        if (isJsonMode) {
+            console.error(JSON.stringify({ status: 'ERROR', error: err.message }, null, 2));
+            process.exit(1);
+        }
         console.error(`[ERROR] Failed to list sections: ${err.message}`);
         process.exit(1);
     }
@@ -350,6 +669,11 @@ async function handleList() {
 
 function handleDecodeId(rawId) {
     const res = decodeTaxIdentifier(rawId);
+    if (isJsonMode) {
+        console.log(JSON.stringify(res, null, 2));
+        process.exit(res.isValid ? 0 : 1);
+    }
+
     console.log('\n===========================================================================');
     console.log('INDIAN TAX IDENTIFIER DECODER & OFFLINE MOD-36 VALIDATOR');
     console.log('===========================================================================');
@@ -382,6 +706,10 @@ Usage:
   npx @mudraforge/statutory <command> [options]
 
 Commands:
+  doctor [--offline]        Run full diagnostic check of runtime, substrate integrity, & edge status
+  verify [path]             Cryptographically verify OKF substrate authenticity & file integrity
+  crosswalk <section>       Dual-act 1961 <-> 2025 bridge (earlier of credit vs payment)
+  diff                      Semantic regulatory changelog (--section, --since, --domain)
   browse                    Interactively browse local OKF statutory filesystem
   lookup <section> [date]   Look up section details & temporal status (e.g. 194Q 2025-06-01)
   decode-id <pan_or_gstin>  Offline ISO Mod-36 checksum, state name, and PAN entity decoding
@@ -390,6 +718,21 @@ Commands:
   list                      List all indexed statutory sections
   init-skill [path]         Install SKILL.md into your agent workspace (defaults to .agents/skills/)
   help                      Show this help message
+
+Options:
+  --credit <YYYY-MM-DD>     Date of credit to vendor/payee account in books (used in crosswalk)
+  --payment <YYYY-MM-DD>    Date of actual payment/disbursement (used in crosswalk)
+  --since <YYYY-MM-DD>      Filter amendments taking effect on or after date (used in diff)
+  --section, -s <section>   Filter amendments by section code (used in diff)
+  --domain <domain>         Filter amendments by statutory domain (used in diff)
+  --json, -j                Emit clean, machine-parseable JSON to stdout (suppresses banners)
+  --offline, -o             Bypass outbound network checks (air-gapped / offline environment mode)
+
+Exit Code Conventions:
+  0                         Success / Verification passed
+  1                         Usage or operational error (invalid syntax / parameters)
+  2                         Cryptographic authenticity or integrity violation (mismatch/revocation)
+  3                         Statutory policy violation (e.g. missing baseline provision)
 `);
 }