multimodel-dev-os 3.1.0 → 3.2.0

package/README.md

@@ -161,6 +161,7 @@ npx multimodel-dev-os@latest handoff build
 | **v3.0.1** | Registry UX & Policy Safety Patch | ✅ Released |
 | **v3.0.2** | Registry Sync Security Hotfix | ✅ Released |
 | **v3.1.0** | Modular Source Layout + Formal Unit Tests | ✅ Released |
+| **v3.2.0** | Stable Modular Build + Package Governance | ✅ Released |
 
 
 **[Full Roadmap →](https://rizvee.github.io/multimodel-dev-os/v3-roadmap)**

package/docs/.vitepress/config.js

@@ -32,7 +32,7 @@ export default {
         'license': 'https://opensource.org/licenses/MIT',
         'url': 'https://github.com/rizvee/multimodel-dev-os',
         'downloadUrl': 'https://www.npmjs.com/package/multimodel-dev-os',
-        'softwareVersion': '3.1.0',
+        'softwareVersion': '3.2.0',
         'description': 'Portable, vendor-neutral AI Developer OS for multi-agent coding workflows.'
       })
     ]

package/docs/index.md

@@ -214,12 +214,12 @@ You use **Cursor** for autocomplete, **Claude Code** for terminal ops, **Gemini*
 
 <div class="highlight-box">
 
-### 🆕 What's New in v2.7
+### 🆕 What's New in v3.2
 
-- 🎬 **Demo Workflow Pages** — 5 copy-paste guided workflows for onboarding, adapter sync, improvement loops, handoffs, and release checks
-- 📖 **Distribution Guide** — comprehensive release, verification, and package hygiene documentation
-- 🖼️ **Visual Flow Diagrams** — SVG assets for onboarding and adapter sync flows
-- 📁 **Docs-First Examples** — 4 new example workflows with commands and expected output
+- 🏗️ **Modular Source Layout** — Pure ES modules under `src/` cleanly isolate core, CLI routing, catalog engines, and security systems.
+- 🧪 **Formal Unit Testing** — Integrated a Vitest-powered test suite executing 45 unit tests covering path safety, sandbox boundaries, and policy validation.
+- ⚙️ **Build Freshness Guard** — Automated build auditing checks to ensure the generated CLI binary is always synchronized with the source modules.
+- 🛡️ **Hardened Registry Sync** — Strict HTTPS-only URL syntax parsing and argument-isolated sub-process executors prevent shell injection vulnerabilities.
 
 </div>
 

package/docs/npm-publishing.md

@@ -12,13 +12,13 @@ Before publishing, always test the built package locally by compiling a compress
    ```bash
    npm pack
    ```
-   This creates a file named like `multimodel-dev-os-3.0.2.tgz` in your directory root.
+   This creates a file named like `multimodel-dev-os-3.2.0.tgz` in your directory root.
 
 2. **Verify bundle contents:**
    Create an empty temporary workspace, extract the tarball, and confirm that only required scaffold folders are included (no `.github/`, test configurations, or local system files):
    ```bash
    mkdir -p /tmp/package-test && cd /tmp/package-test
-   tar -xzf /path/to/multimodel-dev-os-3.0.2.tgz
+   tar -xzf /path/to/multimodel-dev-os-3.2.0.tgz
    ls -la package/
    ```
 
@@ -78,17 +78,17 @@ Execute these validation actions strictly in sequence before triggering a releas
 ## 4. Prepublish Safety Guard
 
 > [!IMPORTANT]
-> **v3.0.2 is the active stable release.** NPM publishing is live.
+> **v3.2.0 is the active stable release.** NPM publishing is live.
 
 ### Source vs. Registry Strategy
-* **GitHub main branch (Source)**: Contains the current stable `v3.0.2` codebase.
+* **GitHub main branch (Source)**: Contains the current stable `v3.2.0` codebase.
 * **npm latest (Registry)**: Pulled and installed globally or via npx.
 
 ### Prepublish Safety Guard
 To prevent accidental `npm publish` executions on developer environments, a local validation script has been added to package hooks. If you run `npm publish`, it is blocked by default.
 
 To bypass this check during approved release windows:
-1. Ensure the version in `package.json` is a valid stable major version >= 2 (e.g., v3.0.2).
+1. Ensure the version in `package.json` is a valid stable major version >= 2 (e.g., v3.2.0).
 2. Run publication with the override env variable:
    ```powershell
    # PowerShell

package/docs/package-safety.md

@@ -35,3 +35,19 @@ A security hotfix has been applied in `v3.0.2` to secure the registry synchroniz
 * **Registry URL Sanitization:** Enforces strict validation of remote registry URLs using Node's `URL` parser. URLs must use HTTPS by default. Control characters, credentials, spaces, quotes, and shell metacharacters are strictly rejected.
 * **Upgrade Guidance:** Users running `v3.0.0` or `v3.0.1` must upgrade to `v3.0.2` immediately.
 * **Safety Boundaries Preserved:** Remote registries remain disabled by default, sync operations are cache-only (never installing or running plugins), and conflict checks on sensitive files (`.env`, `.npmrc`, package configuration files) are strictly enforced.
+
+## Package Governance Policies
+
+1. **Zero Runtime Dependencies:**
+   * The runtime package is strictly zero-dependency to ensure minimal installation footprint and maximum security.
+   * All compilation, testing, and dev tools (e.g., `esbuild`, `vitest`, `vitepress`) are restricted to `devDependencies` only.
+
+2. **Open-Source Transparency:**
+   * The complete modular source files (`src/`) and testing suites (`tests/`) are intentionally included in the published NPM package, allowing for visual auditing, validation, and debugging.
+
+3. **Manual NPM Publishing Only:**
+   * Automated publishing via CI is disabled. NPM publish is performed manually by maintainers using verification guards.
+
+4. **Milestone-Based Releases:**
+   * Patch-level releases are kept internal by default for stabilization sprints (such as `v3.2.0-prep`).
+   * Public updates are batched into stable, fully-audited milestone releases (e.g., `v3.2.0`). Critical security hotfixes are the only exception.

package/docs/public/llms-full.txt

@@ -1,4 +1,4 @@
-# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v3.1.0 Stable Release)
+# MultiModel Dev OS — Comprehensive AI Assistant Discoverability Guide (v3.2.0 Stable Release)
 
 MultiModel Dev OS is a repository-level porting specification designed to align context and instructions across diverse developer tools and AI models.
 

package/docs/public/llms.txt

@@ -1,4 +1,4 @@
-# MultiModel Dev OS (v3.1.0 Stable Release)
+# MultiModel Dev OS (v3.2.0 Stable Release)
 
 Portable, vendor-neutral workspace configuration standard for multi-agent AI pair-programming workflows.
 

package/docs/public/sitemap.xml

@@ -250,4 +250,9 @@
     <changefreq>weekly</changefreq>
     <priority>0.7</priority>
   </url>
+  <url>
+    <loc>https://rizvee.github.io/multimodel-dev-os/release-policy</loc>
+    <changefreq>weekly</changefreq>
+    <priority>0.7</priority>
+  </url>
 </urlset>

package/docs/release-policy.md

@@ -34,9 +34,10 @@ No package shall be merged or released without:
 
 ---
 
-## 4. Release Channel & Staging Controls
+## 4. Release Strategy & Staging Controls
 
-MultiModel Dev OS releases new versions directly to the public NPM registry:
-*   **Stable Releases (`npx multimodel-dev-os`)**: Published to the public registry under semantic version categories (e.g. `2.0.0`, `2.0.1`).
-*   **Release Candidates**: Built and validated locally via the automated verification script (`scripts/verify.js`) before tags or packaging runs.
-*   **Staging Verification**: To test new configurations prior to publishing, package the bundle locally (`npm pack`) and run CLI checkups in clean test directories.
+To ensure developer stability and avoid package version fatigue, MultiModel Dev OS enforces the following distribution strategy:
+- **Internal Stabilization Sprints**: Patch-level work (e.g. bug fixes, refactoring, test stability, documentation formatting) is treated as internal by default and committed directly to `main` without bumping versions or publishing to npm.
+- **Batched Milestone Releases**: Public npm and GitHub releases are batched into stable milestone releases (e.g., `v3.2.0`, `v3.3.0`, `v4.0.0`).
+- **Security Hotfix Exceptions**: Critical security hotfixes (e.g., remote execution, command injection remediations) bypass the batching policy and are published immediately as public patch releases.
+- **Staging Verification**: To test new configurations prior to publishing, package the bundle locally (`npm pack`) and run CLI checkups in clean test directories (`C:\mmdo-smoke`).

package/docs/testing.md

@@ -1,4 +1,4 @@
-# MultiModel Dev OS — Testing Guide (v3.1.0+)
+# MultiModel Dev OS — Testing Guide (v3.2.0+)
 
 This document outlines the testing strategy, tools, and execution processes for MultiModel Dev OS.
 
@@ -114,10 +114,20 @@ To ensure the npm package functions flawlessly after installation, we run a loca
    ```
 3. **Install the generated tarball locally**:
    ```bash
-   npm install F:\multimodel-dev-os\multimodel-dev-os-3.1.0.tgz --no-audit --no-fund
+   npm install F:\multimodel-dev-os\multimodel-dev-os-3.2.0.tgz --no-audit --no-fund
    ```
 4. **Validate npx invocation**:
    ```bash
    npx multimodel-dev-os --help
    npx multimodel-dev-os doctor
    ```
+
+---
+
+## 6. Maintainer Guidelines
+
+For contributors and maintainers modifying the codebase:
+1. **Always edit source modules** located under `src/`. Do NOT make manual edits to `bin/multimodel-dev-os.js` directly, as it will be overwritten during compilation.
+2. **Execute the build script** via `npm run build` after completing modifications to compile the single-file binary.
+3. **Execute Vitest unit tests** (`npm test`) to ensure all core modules pass verification gates in isolation.
+4. **Execute release verification** (`npm run verify`) to run the strict verification pipeline (250+ assertions check compiled binary, folder layouts, sitemaps, etc.).

package/docs/v3-roadmap.md

@@ -7,12 +7,18 @@ This document outlines the development path, completed milestones, and future pl
 ## 1. Current Status
 
 > [!IMPORTANT]
-> **v3.1.0 is the active stable release** on the public npm registry. All features below marked ✅ are shipped and production-ready.
+> **v3.2.0 is the active stable release** on the public npm registry. All features below marked ✅ are shipped and production-ready.
 
 ---
 
 ## 2. Completed Milestones
 
+### v3.2.0 — Stable Modular Build + Package Governance ✅
+- **Build Freshness Auditing**: Integrated `check-build-fresh.js` to ensure the generated single-file CLI binary matches standard ES modules under `src/` dynamically.
+- **Hardened Package Governance**: Configured the NPM manifest (`package.json`) to include the modular source folder (`src/`) and unit test suites (`tests/unit/`) for developer auditability, while verifying the strict exclusion of sensitive and temporary files.
+- **Cross-Platform CI Pipeline**: Configured a complete multi-platform CI verification matrix on GitHub Actions covering Windows, Linux, and macOS across Node.js versions `20.x` and `22.x`.
+- **Harden Build & Verification Gates**: Applied post-build validations asserting shebang count uniqueness, warning headers, and URL shell-injection safety, while expanding integration audits to 269 assertions.
+
 ### v3.1.0 — Modular Source Layout + Formal Unit Tests ✅
 - **Modular Source Layout**: Refactored the monolithic CLI structure into isolated, clean modules under `src/` (core, registry, catalog, plugin, cli).
 - **Programmatic Compiler**: Programmed `scripts/build-cli.js` using `esbuild` to compile modules into a single zero-dependency executable (`bin/multimodel-dev-os.js`) with shebang preservation.
@@ -74,7 +80,7 @@ All releases follow this strict publishing checklist:
 
 ---
 
-## 4. Upcoming: v3.2.0 — Cryptographic Catalog Signing
+## 4. Upcoming: v3.3.0 stable candidate — Asymmetric Key Signatures
 
 *   **Asymmetric Key Signatures**: Cryptographic signature validation for remote registries using public/private key pairs.
 *   **Decentralized Trust Anchors**: Trust anchors configuration allowing teams to pin public keys of verified catalog authors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multimodel-dev-os",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "bin": {
     "multimodel-dev-os": "bin/multimodel-dev-os.js"
   },
@@ -35,12 +35,15 @@
     "!docs/.vitepress/cache/",
     "examples/",
     "bin/",
+    "src/",
+    "tests/",
     "assets/"
   ],
   "scripts": {
     "build": "node scripts/build-cli.js",
+    "check:build": "node scripts/check-build-fresh.js",
     "test": "vitest run",
-    "verify": "npm run build && npm test && node scripts/verify.js",
+    "verify": "npm run check:build && npm test && node scripts/verify.js",
     "verify:bash": "bash scripts/verify.sh",
     "test:cli": "node bin/multimodel-dev-os.js verify",
     "pack:template": "bash scripts/pack-template.sh",

package/scripts/build-cli.js

@@ -1,16 +1,58 @@
 import esbuild from 'esbuild';
+import { existsSync, chmodSync, readFileSync } from 'fs';
+
+const entryPoint = 'src/cli/main.js';
+const outfile = 'bin/multimodel-dev-os.js';
+
+if (!existsSync(entryPoint)) {
+  console.error(`[ERROR] Entrypoint file not found: ${entryPoint}`);
+  process.exit(1);
+}
 
 esbuild.build({
-  entryPoints: ['src/cli/main.js'],
+  entryPoints: [entryPoint],
   bundle: true,
   platform: 'node',
   format: 'esm',
-  outfile: 'bin/multimodel-dev-os.js',
+  outfile: outfile,
   banner: {
     js: `#!/usr/bin/env node\n// Generated from src/. Do not edit directly.\n`
   }
 }).then(() => {
-  console.log('Build succeeded.');
+  // Post-build validation & hardening
+  try {
+    const content = readFileSync(outfile, 'utf8');
+    
+    // 1. Check shebang counts
+    const shebangMatches = content.match(/^#!/g) || [];
+    const totalShebangs = (content.match(/#!/g) || []).length;
+    
+    // We expect exactly one shebang at the very top
+    if (totalShebangs !== 1 || !content.startsWith('#!/usr/bin/env node')) {
+      console.error('[ERROR] Compiled output has invalid shebang configuration.');
+      process.exit(1);
+    }
+    
+    // 2. Check warning header
+    if (!content.includes('// Generated from src/. Do not edit directly.')) {
+      console.error('[ERROR] Compiled output is missing the generation warning header.');
+      process.exit(1);
+    }
+    
+    // 3. Check for unsafe URL interpolation patterns
+    if (content.includes("mod.get('${targetUrl}'") || (content.includes('execSync(`node -e "') && content.includes('${targetUrl}'))) {
+      console.error('[ERROR] Compiled output contains unsafe registry URL interpolation!');
+      process.exit(1);
+    }
+
+    // 4. Set execution permissions (0755)
+    chmodSync(outfile, 0o755);
+    
+    console.log('Build succeeded.');
+  } catch (e) {
+    console.error('Post-build verification failed:', e.message);
+    process.exit(1);
+  }
 }).catch((err) => {
   console.error('Build failed:', err);
   process.exit(1);

package/scripts/check-build-fresh.js

@@ -0,0 +1,52 @@
+import esbuild from 'esbuild';
+import { readFileSync, unlinkSync, existsSync } from 'fs';
+
+const entryPoint = 'src/cli/main.js';
+const currentFile = 'bin/multimodel-dev-os.js';
+const tempFile = 'bin/multimodel-dev-os.tmp.js';
+
+if (!existsSync(entryPoint)) {
+  console.error(`[ERROR] Entrypoint file not found: ${entryPoint}`);
+  process.exit(1);
+}
+
+if (!existsSync(currentFile)) {
+  console.error(`[ERROR] Current build file not found: ${currentFile}`);
+  console.error('Generated CLI is stale. Run npm run build and commit bin/multimodel-dev-os.js.');
+  process.exit(1);
+}
+
+try {
+  await esbuild.build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    platform: 'node',
+    format: 'esm',
+    outfile: tempFile,
+    banner: {
+      js: `#!/usr/bin/env node\n// Generated from src/. Do not edit directly.\n`
+    }
+  });
+
+  const currentContent = readFileSync(currentFile, 'utf8');
+  const tempContent = readFileSync(tempFile, 'utf8');
+
+  // Clean up temp file immediately
+  unlinkSync(tempFile);
+
+  const normalize = str => str.replace(/\r\n/g, '\n');
+
+  if (normalize(currentContent) !== normalize(tempContent)) {
+    console.error('[ERROR] Generated CLI is stale. Run npm run build and commit bin/multimodel-dev-os.js.');
+    process.exit(1);
+  }
+
+  console.log('Generated CLI is fresh.');
+  process.exit(0);
+} catch (err) {
+  console.error('Build freshness check failed:', err);
+  if (existsSync(tempFile)) {
+    unlinkSync(tempFile);
+  }
+  process.exit(1);
+}

package/scripts/install.ps1

@@ -11,7 +11,7 @@ param(
   [switch]$Help
 )
 
-$Version = "3.1.0"
+$Version = "3.2.0"
 $RepoUrl = "https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main"
 
 if ($Help) {

package/scripts/install.sh

@@ -7,7 +7,7 @@ set -euo pipefail
 #        --all      (install all adapters)
 #        --dry-run  (show what would be created without creating)
 
-VERSION="3.1.0"
+VERSION="3.2.0"
 REPO_URL="https://raw.githubusercontent.com/rizvee/multimodel-dev-os/main"
 CAVEMAN=false
 DRY_RUN=false

package/scripts/verify.js

@@ -189,6 +189,21 @@ checkFile('scripts/pack-template.sh');
 checkFile('scripts/prepublish-guard.js');
 checkFile('bin/multimodel-dev-os.js');
 
+// --- Modular Source Files ---
+console.log('\nModular Source Files:');
+checkFile('src/cli/main.js');
+checkFile('src/cli/args.js');
+checkFile('src/cli/help.js');
+checkFile('src/core/yaml.js');
+checkFile('src/core/hashes.js');
+checkFile('src/core/policy.js');
+checkFile('src/core/security.js');
+checkFile('src/core/globals.js');
+checkFile('src/registry/validation.js');
+checkFile('src/registry/sources.js');
+checkFile('src/catalog/loader.js');
+checkFile('src/plugin/manifest.js');
+
 // --- GitHub Integration ---
 console.log('\nGitHub Workflows:');
 checkFile('.github/workflows/verify.yml');
@@ -549,7 +564,7 @@ try {
     }
   }
 
-  // Test 2: Allows version 3.1.0 with MMDO_ALLOW_PUBLISH=true
+  // Test 2: Allows version 3.2.0 with MMDO_ALLOW_PUBLISH=true
   try {
     const output = execSync('node scripts/prepublish-guard.js', { 
       cwd: projectRoot, 
@@ -557,7 +572,7 @@ try {
       encoding: 'utf8' 
     });
     if (output.includes('Prepublish guard passed')) {
-      console.log(`  ${GREEN}✓${NC} prepublish guard allows version 3.1.0 when MMDO_ALLOW_PUBLISH=true`);
+      console.log(`  ${GREEN}✓${NC} prepublish guard allows version 3.2.0 when MMDO_ALLOW_PUBLISH=true`);
       pass++;
     } else {
       console.error(`  ${RED}✗${NC} prepublish guard passed but stdout missing success indicator`);
@@ -565,7 +580,7 @@ try {
     }
   } catch (err) {
     const errText = err.stderr ? err.stderr.toString() : '';
-    console.error(`  ${RED}✗${NC} prepublish guard blocked version 3.1.0: ${errText || err.message}`);
+    console.error(`  ${RED}✗${NC} prepublish guard blocked version 3.2.0: ${errText || err.message}`);
     fail++;
   }
 
@@ -579,12 +594,12 @@ try {
     pass++;
   }
 
-  // Test 4: Package.json version is exactly 3.1.0
-  if (expectedVersion === '3.1.0') {
-    console.log(`  ${GREEN}✓${NC} package.json version is exactly 3.1.0`);
+  // Test 4: Package.json version is exactly 3.2.0
+  if (expectedVersion === '3.2.0') {
+    console.log(`  ${GREEN}✓${NC} package.json version is exactly 3.2.0`);
     pass++;
   } else {
-    console.error(`  ${RED}✗${NC} package.json version is not 3.1.0 (found ${expectedVersion})`);
+    console.error(`  ${RED}✗${NC} package.json version is not 3.2.0 (found ${expectedVersion})`);
     fail++;
   }
 } catch (e) {
@@ -592,6 +607,52 @@ try {
   fail++;
 }
 
+// --- Post-build Generated CLI Checks ---
+console.log('\nPost-build Generated CLI Checks:');
+try {
+  // 0. Check build freshness
+  try {
+    execSync('node scripts/check-build-fresh.js', { cwd: projectRoot, stdio: 'ignore' });
+    console.log(`  ${GREEN}✓${NC} generated bin matches current source layout`);
+    pass++;
+  } catch (err) {
+    console.error(`  ${RED}✗${NC} generated bin is stale! Run 'npm run build' and commit bin/multimodel-dev-os.js`);
+    fail++;
+  }
+
+  const buildPath = join(projectRoot, 'bin', 'multimodel-dev-os.js');
+  const binContent = readFileSync(buildPath, 'utf8');
+  
+  const totalShebangs = (binContent.match(/#!/g) || []).length;
+  if (binContent.startsWith('#!/usr/bin/env node') && totalShebangs === 1) {
+    console.log(`  ${GREEN}✓${NC} generated bin has exactly one shebang at the top`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} generated bin has invalid shebang layout (count: ${totalShebangs})`);
+    fail++;
+  }
+  
+  if (binContent.includes('// Generated from src/. Do not edit directly.')) {
+    console.log(`  ${GREEN}✓${NC} generated bin has warning header`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} generated bin is missing the warning header`);
+    fail++;
+  }
+  
+  const hasUnsafeSync = binContent.includes("mod.get('${targetUrl}'") || (binContent.includes('execSync(`node -e "') && binContent.includes('${targetUrl}'));
+  if (!hasUnsafeSync && binContent.includes('execFileSync(process.execPath')) {
+    console.log(`  ${GREEN}✓${NC} generated bin is free of unsafe URL interpolation and uses execFileSync`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} generated bin fails safety scan (unsafe interpolation found)`);
+    fail++;
+  }
+} catch (e) {
+  console.error(`  ${RED}✗${NC} post-build generated CLI checks failed: ${e.message}`);
+  fail++;
+}
+
 // --- v2.8.0 / v2.8.1 Dashboard & Plugin Tests ---
 console.log('\nRunning TUI Dashboard & Plugin Pre-Flight Tests...');
 
@@ -921,22 +982,77 @@ try {
   fail++;
 }
 
-// Verify npm pack dry-run shows current version dynamically
+// Verify npm pack dry-run shows current version dynamically and has clean hygiene
 try {
-  const packOutput = execSync('npm pack --dry-run', { cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-  if (packOutput.includes(`multimodel-dev-os@${expectedVersion}`) || packOutput.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || packOutput.includes(`version: ${expectedVersion}`)) {
+  const packOutput = execSync('npm pack --dry-run 2>&1', { cwd: projectRoot, encoding: 'utf8' });
+  const combinedOutput = packOutput;
+  
+  const hasVersion = combinedOutput.includes(`multimodel-dev-os@${expectedVersion}`) || combinedOutput.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || combinedOutput.includes(`version: ${expectedVersion}`);
+  if (hasVersion) {
     console.log(`  ${GREEN}✓${NC} npm pack --dry-run reports version ${expectedVersion}`);
     pass++;
   } else {
-    console.error(`  ${RED}✗${NC} npm pack --dry-run did not report ${expectedVersion} in stdout`);
+    console.error(`  ${RED}✗${NC} npm pack --dry-run did not report ${expectedVersion} in output`);
+    fail++;
+  }
+
+  // Hygiene checks
+  const lines = combinedOutput.split('\n');
+  const files = lines
+    .filter(l => l.includes('npm notice') && !l.includes('Tarball Details') && !l.includes('Tarball Filename') && !l.includes('package size:') && !l.includes('unpacked size:') && !l.includes('shasum:') && !l.includes('integrity:') && !l.includes('total files:'))
+    .map(l => {
+      const match = l.match(/npm notice\s+\d+(\.\d+)?[a-zA-Z]+\s+(.+)$/);
+      return match ? match[2].trim() : '';
+    })
+    .filter(f => f !== '');
+
+  const hasSrc = files.some(f => f.startsWith('src/'));
+  const hasTests = files.some(f => f.startsWith('tests/'));
+  
+  if (hasSrc && hasTests) {
+    console.log(`  ${GREEN}✓${NC} npm pack includes 'src/' and 'tests/' directories`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} npm pack is missing 'src/' or 'tests/' directory`);
+    fail++;
+  }
+
+  const hasBlacklisted = files.some(f => f.includes('.npmrc') || f.includes('.env') || f.includes('node_modules') || f.endsWith('.tgz') || f.includes('coverage/'));
+  if (!hasBlacklisted) {
+    console.log(`  ${GREEN}✓${NC} npm pack excludes sensitive and temporary files (.npmrc, .env, node_modules, .tgz, coverage)`);
+    pass++;
+  } else {
+    console.error(`  ${RED}✗${NC} npm pack contains blacklisted files!`);
     fail++;
   }
 } catch (e) {
   const stdErrOut = e.stderr ? e.stderr.toString() : '';
   const stdOutOut = e.stdout ? e.stdout.toString() : '';
-  if (stdErrOut.includes(`multimodel-dev-os@${expectedVersion}`) || stdErrOut.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || stdOutOut.includes(`multimodel-dev-os-${expectedVersion}.tgz`)) {
+  const combined = stdErrOut + '\n' + stdOutOut;
+  
+  const hasVersion = combined.includes(`multimodel-dev-os@${expectedVersion}`) || combined.includes(`multimodel-dev-os-${expectedVersion}.tgz`) || combined.includes(`version: ${expectedVersion}`);
+  if (hasVersion) {
     console.log(`  ${GREEN}✓${NC} npm pack --dry-run reports version ${expectedVersion}`);
     pass++;
+    
+    const hasSrc = combined.includes('src/') || combined.includes('src\\');
+    const hasTests = combined.includes('tests/') || combined.includes('tests\\');
+    if (hasSrc && hasTests) {
+      console.log(`  ${GREEN}✓${NC} npm pack includes 'src/' and 'tests/' directories`);
+      pass++;
+    } else {
+      console.error(`  ${RED}✗${NC} npm pack is missing 'src/' or 'tests/' directory`);
+      fail++;
+    }
+
+    const hasBlacklisted = combined.includes('.npmrc') || combined.includes('.env') || combined.includes('node_modules') || combined.includes('.tgz') || combined.includes('coverage/');
+    if (!hasBlacklisted) {
+      console.log(`  ${GREEN}✓${NC} npm pack excludes sensitive and temporary files`);
+      pass++;
+    } else {
+      console.error(`  ${RED}✗${NC} npm pack contains blacklisted files!`);
+      fail++;
+    }
   } else {
     console.error(`  ${RED}✗${NC} npm pack --dry-run failed or did not report ${expectedVersion}: ${e.message}`);
     fail++;

package/scripts/verify.sh

@@ -192,6 +192,8 @@ check_file "docs/cli-roadmap.md"
 check_file "docs/faq.md"
 check_file "docs/testing.md"
 check_file "docs/npm-publishing.md"
+check_file "docs/release-policy.md"
+check_file "docs/package-safety.md"
 
 # --- CLI & Packaging Pre-Flight Tests ---
 echo ""
@@ -235,6 +237,14 @@ else
   PASS=$((PASS + 1))
 fi
 
+if ! npm run check:build >/dev/null; then
+  echo -e "  ${RED}✗${NC} Generated CLI is stale. Run npm run build."
+  FAIL=$((FAIL + 1))
+else
+  echo -e "  ${GREEN}✓${NC} Generated CLI is fresh"
+  PASS=$((PASS + 1))
+fi
+
 if ! node bin/multimodel-dev-os.js init --dry-run --force >/dev/null; then
   echo -e "  ${RED}✗${NC} node bin/multimodel-dev-os.js init --dry-run failed"
   FAIL=$((FAIL + 1))