@stackwright-pro/otters 1.0.0-alpha.7 → 1.0.0-alpha.70

package/LICENSE

@@ -0,0 +1,21 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 Per Aspera LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Per Aspera LLC ("Company").
+
+RESTRICTIONS: You may not use, copy, modify, merge, publish, distribute,
+sublicense, sell, or otherwise exploit this Software or any portion thereof
+without the express prior written consent of the Company.
+
+GOVERNMENT USE: Use, duplication, or disclosure by the U.S. Government is
+subject to restrictions as set forth in FAR 52.227-19 (Commercial Computer
+Software - Restricted Rights) and DFARS 252.227-7013 (Rights in Technical
+Data and Computer Software), as applicable.
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+For licensing inquiries: legal@peraspera.com

package/README.md

@@ -118,12 +118,13 @@ When Pro otters combine with the OSS raft, these capabilities emerge:
 
 ## The Pro Otter Raft
 
-| Otter                    | Role                 | Output                                                        |
-| ------------------------ | -------------------- | ------------------------------------------------------------- |
-| 🦦🦦 **Foreman Otter**   | Project coordinator  | Orchestrates full-stack builds (delegates to unified Foreman) |
-| 🦦📡 **API Otter**       | OpenAPI discovery    | API entity types, endpoints                                   |
-| 🦦📊 **Dashboard Otter** | Live data views      | Typed API components                                          |
-| 🦦🔗 **Data Otter**      | Endpoint integration | ISR config, filters                                           |
+| Otter                                 | Role                 | Output                                                                          |
+| ------------------------------------- | -------------------- | ------------------------------------------------------------------------------- |
+| 🦦🦦 **Foreman Otter**                | Project coordinator  | Orchestrates full-stack builds (delegates to unified Foreman)                   |
+| 🦦📡 **API Otter**                    | OpenAPI discovery    | API entity types, endpoints                                                     |
+| 🦦📊 **Dashboard Otter**              | Live data views      | Typed API components                                                            |
+| 🦦🔗 **Data Otter**                   | Endpoint integration | ISR config, filters                                                             |
+| `stackwright-pro-domain-expert-otter` | Utility              | Answers specialist questions from the use case document in non-interactive mode |
 
 ---
 

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.70",
   "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "https://github.com/Per-Aspera-LLC/stackwright-pro"
   },
   "devDependencies": {
-    "vitest": "^4.0.18",
-    "zod": "^3.22.4"
+    "vitest": "^4.1.8",
+    "zod": "^4.4.3"
   },
   "exports": {
     "./src": "./src",
-    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json"
+    "./pro-foreman": "./src/stackwright-pro-foreman-otter.json",
+    "./pro-workflow": "./src/stackwright-pro-form-wizard-otter.json"
   },
   "files": [
     "scripts",
@@ -23,7 +24,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@stackwright-pro/mcp": "^0.2.0-alpha.1"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.103"
   },
   "scripts": {
     "generate-checksums": "node scripts/generate-checksums.js",
@@ -31,6 +32,7 @@
     "postinstall": "node scripts/install-agents.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "sanity-check-pipeline": "node scripts/sanity-check-pipeline.mjs"
   }
 }

package/scripts/add-pipeline-declarations.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""
+add-pipeline-declarations.py
+Inserts the `pipeline` I/O declaration into each specialist otter JSON.
+
+Run once: python3 scripts/add-pipeline-declarations.py
+Part of swp-amyw Batch 1.
+
+AUDIT NOTES (inline justifications for dep changes):
+- auth-otter: was ['pages', 'dashboard', 'workflow', 'geo'] in PHASE_DEPENDENCIES.
+  Bead 3 (swp-e4y6) changed the runtime model: AuthProvider reads _auth.json at
+  runtime, no longer needs build-time route enumeration. Auth only needs
+  design-language.json to extract personas/roles. Moves auth wave 4 → wave 2.
+
+- workflow (form-wizard-otter): was [] with a Prism mock fallback comment.
+  Bead swp-4071 (services hooks contract) made the workflow→api relationship
+  explicit via serviceHooks referencing API endpoints. Real deps added:
+  _theme.json (UI generation) and api-config.json (hook endpoint references).
+"""
+
+import json
+import os
+
+SRC_DIR = os.path.join(os.path.dirname(__file__), '..', 'src')
+
+# Pipeline declarations keyed by otter filename (no .json extension).
+# Matches the table in the swp-amyw plan.
+# Null-sentinel otters (foreman, domain-expert) are skipped — they're orchestrators.
+DECLARATIONS: dict[str, dict] = {
+    'stackwright-pro-designer-otter': {
+        'inputs': {},
+        'outputs': {
+            'artifact': 'design-language.json',
+        },
+    },
+    'stackwright-pro-theme-otter': {
+        'inputs': {
+            'artifacts': ['design-language.json'],
+        },
+        'outputs': {
+            'sinks': ['_theme.json'],
+            'artifact': 'theme-tokens.json',
+            'files': ['stackwright.theme.yml'],
+        },
+    },
+    'stackwright-pro-api-otter': {
+        'inputs': {},
+        'outputs': {
+            'sinks': ['_integrations.json'],
+            'artifact': 'api-config.json',
+            'files': ['stackwright.integrations.yml'],
+        },
+    },
+    # AUDIT: auth moved from wave 4 → wave 2.
+    # Bead 3 (swp-e4y6) changed the runtime model: AuthProvider reads
+    # _auth.json at runtime; auth no longer needs build-time route enumeration.
+    # Auth now only reads design-language.json to extract personas/roles.
+    'stackwright-pro-auth-otter': {
+        'inputs': {
+            'artifacts': ['design-language.json'],
+        },
+        'outputs': {
+            'sinks': ['_auth.json'],
+            'artifact': 'auth-config.json',
+            'files': [
+                'stackwright.auth.yml',
+                '.env.example',
+                'lib/mock-auth.ts',
+                'package.json',
+            ],
+        },
+    },
+    'stackwright-pro-scaffold-otter': {
+        'inputs': {
+            'sinks': ['_theme.json'],
+            'files': ['stackwright.yml'],
+        },
+        'outputs': {
+            'artifact': 'scaffold-manifest.json',
+            'files': ['app/**'],
+        },
+        # scaffold-otter generates app/layout.tsx which reads _collections.json
+        # and _auth.json at app build time — NOT at scaffold-otter execution time.
+        'runtimeReads': ['_collections.json', '_auth.json'],
+    },
+    'stackwright-pro-data-otter': {
+        'inputs': {
+            'artifacts': ['api-config.json'],
+        },
+        'outputs': {
+            'sinks': ['_collections.json'],
+            'artifact': 'data-config.json',
+            'files': ['stackwright.collections.yml'],
+        },
+    },
+    'stackwright-pro-geo-otter': {
+        'inputs': {
+            'artifacts': ['data-config.json'],
+        },
+        'outputs': {
+            'artifact': 'geo-manifest.json',
+        },
+    },
+    # AUDIT: workflow moved from [] → real deps.
+    # swp-4071 (services hooks contract) made workflow→api relationship explicit:
+    # serviceHooks reference API endpoints from api-config.json.
+    # UI generation requires _theme.json for component selection.
+    'stackwright-pro-form-wizard-otter': {
+        'inputs': {
+            'sinks': ['_theme.json'],
+            'artifacts': ['api-config.json'],
+        },
+        'outputs': {
+            'artifact': 'workflow-config.json',
+            'files': ['stackwright.workflow.yml'],
+        },
+    },
+    'stackwright-services-otter': {
+        'inputs': {
+            'artifacts': ['api-config.json', 'workflow-config.json'],
+        },
+        'outputs': {
+            'artifact': 'services-config.json',
+        },
+    },
+    'stackwright-pro-page-otter': {
+        'inputs': {
+            'sinks': ['_theme.json', '_collections.json', '_auth.json'],
+            'artifacts': [
+                'design-language.json',
+                'data-config.json',
+                'services-config.json',
+                'geo-manifest.json',
+            ],
+        },
+        'outputs': {
+            'artifact': 'pages-manifest.json',
+        },
+    },
+    'stackwright-pro-dashboard-otter': {
+        'inputs': {
+            'sinks': ['_theme.json', '_collections.json', '_auth.json'],
+            'artifacts': [
+                'design-language.json',
+                'data-config.json',
+                'services-config.json',
+                'geo-manifest.json',
+            ],
+        },
+        'outputs': {
+            'artifact': 'dashboard-manifest.json',
+        },
+    },
+    'stackwright-pro-polish-otter': {
+        'inputs': {
+            'artifacts': [
+                'pages-manifest.json',
+                'dashboard-manifest.json',
+                'workflow-config.json',
+                'auth-config.json',
+            ],
+        },
+        'outputs': {
+            'artifact': 'polish-manifest.json',
+            'files': ['stackwright.yml'],
+        },
+    },
+}
+
+
+def add_pipeline(filename_stem: str, declaration: dict) -> None:
+    path = os.path.join(SRC_DIR, f'{filename_stem}.json')
+    if not os.path.exists(path):
+        print(f'    SKIP (not found): {filename_stem}.json')
+        return
+
+    with open(path, 'r', encoding='utf-8') as fh:
+        data = json.load(fh)
+
+    if 'pipeline' in data:
+        print(f'  ⏭  ALREADY HAS pipeline: {filename_stem}.json — overwriting')
+
+    data['pipeline'] = declaration
+
+    serialized = json.dumps(data, indent=2, ensure_ascii=False) + '\n'
+    with open(path, 'w', encoding='utf-8') as fh:
+        fh.write(serialized)
+
+    print(f'   {filename_stem}.json')
+
+
+def main() -> None:
+    print('Adding pipeline declarations to specialist otter manifests...\n')
+    for stem, decl in DECLARATIONS.items():
+        add_pipeline(stem, decl)
+
+    print('\nDone. Run `node scripts/generate-checksums.js` to update checksums.json.')
+
+
+if __name__ == '__main__':
+    main()

package/scripts/generate-checksums.js

@@ -35,7 +35,6 @@ async function generateChecksums() {
   const manifest = {
     version: '1.0',
     algorithm: 'sha256',
-    generated: new Date().toISOString(),
     files,
   };
 

package/scripts/install-agents.js

@@ -8,14 +8,17 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const AGENTS_DIR = path.join(os.homedir(), '.code_puppy', 'agents');
+// Allow test overrides via env vars — production paths are the default.
+// STACKWRIGHT_AGENTS_DIR: override destination (normally ~/.code_puppy/agents/)
+// STACKWRIGHT_OTTERS_SRC_DIR: override source (normally <package>/src/)
+const AGENTS_DIR = process.env.STACKWRIGHT_AGENTS_DIR || path.join(os.homedir(), '.code_puppy', 'agents');
 
 // Resolve package root relative to this script's location
 const scriptDir = __dirname;
 const packageRoot = path.resolve(scriptDir, '..');
 
 // All Pro otters are in the src/ directory
-const srcDir = path.join(packageRoot, 'src');
+const srcDir = process.env.STACKWRIGHT_OTTERS_SRC_DIR || path.join(packageRoot, 'src');
 
 async function installAgents() {
   try {

package/scripts/launch-raft.cjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// ⚠️ DEPRECATED — This launcher has been replaced by @stackwright-pro/raft.
+// Run: npx @stackwright-pro/raft
+// This file is kept for users who may have cached a previous install.
+// It will be removed in a future release.
+
+console.error('⚠️  launch-raft in @stackwright-pro/otters is deprecated.');
+console.error('   Use: npx @stackwright-pro/raft');
+console.error('');
+console.error('   Install: npm install -g @stackwright-pro/raft');
+console.error('   Or run directly: npx @stackwright-pro/raft');
+process.exit(1);

package/scripts/sanity-check-pipeline.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * sanity-check-pipeline.mjs
+ * Verifies pipeline I/O declarations across all specialist otter manifests:
+ *   1. Every specialist otter (except foreman + domain-expert) has a pipeline field
+ *   2. No dangling sink references (every inputs.sinks value exists in some otter's outputs.sinks)
+ *   3. No dangling artifact references (every inputs.artifacts value exists in some otter's outputs.artifact)
+ *   4. No cycles (topological sort succeeds)
+ *
+ * Part of swp-amyw Batch 1 quality gate.
+ */
+
+import { readFileSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SRC_DIR = join(__dirname, '..', 'src');
+
+// Orchestrators: exempt from pipeline requirement
+const ORCHESTRATORS = new Set([
+  'stackwright-pro-foreman-otter',
+  'stackwright-pro-domain-expert-otter',
+]);
+
+// ─── Load all otter manifests ────────────────────────────────────────────────
+
+const otterFiles = readdirSync(SRC_DIR).filter(
+  (f) => f.endsWith('-otter.json') && !f.startsWith('checksums')
+);
+
+const otters = otterFiles.map((filename) => {
+  const raw = readFileSync(join(SRC_DIR, filename), 'utf-8');
+  const data = JSON.parse(raw);
+  return { filename, name: data.name, pipeline: data.pipeline ?? null };
+});
+
+let errors = 0;
+
+// ─── Check 1: Every specialist has a pipeline field ─────────────────────────
+
+console.log('\n[1] Pipeline field presence...');
+for (const { filename, name, pipeline } of otters) {
+  if (ORCHESTRATORS.has(name)) {
+    console.log(`    SKIP (orchestrator): ${filename}`);
+    continue;
+  }
+  if (pipeline === null || pipeline === undefined) {
+    console.error(`    FAIL: missing pipeline in ${filename}`);
+    errors++;
+  } else {
+    console.log(`    OK  : ${filename}`);
+  }
+}
+
+// ─── Collect all declared sinks + artifacts ──────────────────────────────────
+
+const allOutputSinks = new Set();
+const allOutputArtifacts = new Set();
+
+for (const { pipeline } of otters) {
+  if (!pipeline) continue;
+  (pipeline.outputs?.sinks ?? []).forEach((s) => allOutputSinks.add(s));
+  if (pipeline.outputs?.artifact) allOutputArtifacts.add(pipeline.outputs.artifact);
+}
+
+// ─── Check 2: No dangling sink refs ─────────────────────────────────────────
+
+console.log('\n[2] Dangling sink references...');
+for (const { filename, pipeline } of otters) {
+  if (!pipeline) continue;
+  for (const sink of pipeline.inputs?.sinks ?? []) {
+    if (!allOutputSinks.has(sink)) {
+      console.error(`    FAIL: ${filename} inputs.sinks references '${sink}' but no otter outputs it`);
+      errors++;
+    } else {
+      console.log(`    OK  : ${filename} <- ${sink}`);
+    }
+  }
+}
+if (errors === 0) console.log('    (no dangling sinks)');
+
+// ─── Check 3: No dangling artifact refs ─────────────────────────────────────
+
+console.log('\n[3] Dangling artifact references...');
+let artifactRefs = 0;
+for (const { filename, pipeline } of otters) {
+  if (!pipeline) continue;
+  for (const art of pipeline.inputs?.artifacts ?? []) {
+    artifactRefs++;
+    if (!allOutputArtifacts.has(art)) {
+      console.error(`    FAIL: ${filename} inputs.artifacts references '${art}' but no otter outputs it`);
+      errors++;
+    } else {
+      console.log(`    OK  : ${filename} <- ${art}`);
+    }
+  }
+}
+if (artifactRefs === 0) console.log('    (no artifact refs to check)');
+
+// ─── Check 4: No cycles (Kahn's algorithm topological sort) ─────────────────
+
+console.log('\n[4] Cycle detection (Kahn topological sort)...');
+
+// Build adjacency by artifact: producer -> [consumers]
+// Node = otter name
+const otterByOutputArtifact = new Map();
+for (const { name, pipeline } of otters) {
+  if (!pipeline) continue;
+  if (pipeline.outputs?.artifact) {
+    otterByOutputArtifact.set(pipeline.outputs.artifact, name);
+  }
+}
+
+// Build adjacency list: name -> Set<name> (direct dependencies)
+const deps = new Map();
+for (const { name, pipeline } of otters) {
+  if (!pipeline || ORCHESTRATORS.has(name)) continue;
+  deps.set(name, new Set());
+  for (const art of pipeline.inputs?.artifacts ?? []) {
+    const producer = otterByOutputArtifact.get(art);
+    if (producer && producer !== name) deps.get(name).add(producer);
+  }
+  for (const sink of pipeline.inputs?.sinks ?? []) {
+    // find which otter outputs this sink
+    for (const { name: pName, pipeline: pPipeline } of otters) {
+      if (!pPipeline || pName === name) continue;
+      if ((pPipeline.outputs?.sinks ?? []).includes(sink)) {
+        deps.get(name).add(pName);
+      }
+    }
+  }
+}
+
+// Kahn's: compute in-degree, enqueue zero-in-degree nodes
+const inDegree = new Map();
+const adjOut = new Map(); // name -> [names that depend on it]
+for (const name of deps.keys()) {
+  inDegree.set(name, 0);
+  adjOut.set(name, []);
+}
+for (const [name, upstream] of deps.entries()) {
+  for (const u of upstream) {
+    inDegree.set(name, (inDegree.get(name) ?? 0) + 1);
+    if (!adjOut.has(u)) adjOut.set(u, []);
+    adjOut.get(u).push(name);
+  }
+}
+
+const queue = [];
+for (const [name, deg] of inDegree.entries()) {
+  if (deg === 0) queue.push(name);
+}
+
+const sorted = [];
+while (queue.length > 0) {
+  const node = queue.shift();
+  sorted.push(node);
+  for (const dependent of adjOut.get(node) ?? []) {
+    const newDeg = (inDegree.get(dependent) ?? 1) - 1;
+    inDegree.set(dependent, newDeg);
+    if (newDeg === 0) queue.push(dependent);
+  }
+}
+
+if (sorted.length !== deps.size) {
+  console.error(`    FAIL: cycle detected! Sorted ${sorted.length} of ${deps.size} nodes.`);
+  const unsorted = [...deps.keys()].filter((n) => !sorted.includes(n));
+  console.error(`    Nodes in cycle: ${unsorted.join(', ')}`);
+  errors++;
+} else {
+  console.log(`    OK  : topological order (${sorted.length} nodes):`);
+  console.log(`           ${sorted.join(' -> ')}`);
+}
+
+// ─── Result ──────────────────────────────────────────────────────────────────
+
+console.log('');
+if (errors > 0) {
+  console.error(`SANITY CHECK FAILED — ${errors} error(s). Fix above before committing.`);
+  process.exit(1);
+} else {
+  console.log('SANITY CHECK PASSED — no dangling refs, no cycles.');
+  process.exit(0);
+}

package/scripts/strip-artifact-schemas.cjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * strip-artifact-schemas.cjs
+ *
+ * Removes hardcoded artifact schema JSON blocks from specialist otter system_prompts.
+ * These are now injected dynamically via build_specialist_prompt (REQUIRED_ARTIFACT_SCHEMA).
+ *
+ * Run: node packages/otters/scripts/strip-artifact-schemas.cjs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const OTTERS_DIR = path.join(__dirname, '..', 'src');
+const REFERENCE_LINE =
+  '**Artifact shape:** See the **REQUIRED_ARTIFACT_SCHEMA** section in your prompt for the canonical artifact shape. Use it when calling `stackwright_pro_validate_artifact`.';
+
+function stripArtifactSchemaFromArray(promptArray) {
+  // Strategy: find the index of the ```json opening fence,
+  // then find the matching closing ``` fence.
+  // Replace everything from the fence through the closing fence + surrounding context
+  // with the REFERENCE_LINE.
+
+  const result = [];
+  let i = 0;
+  let stripped = false;
+
+  while (i < promptArray.length) {
+    const item = promptArray[i];
+
+    // Detect start of a JSON code block fence
+    if (typeof item === 'string' && item.trim() === '```json') {
+      // Find the closing fence
+      let j = i + 1;
+      while (j < promptArray.length && promptArray[j].trim() !== '```') {
+        j++;
+      }
+      // j now points to the closing ``` (or end of array)
+
+      // Replace this entire block with the reference line
+      // (but only the first JSON block per otter — the artifact schema block)
+      if (!stripped) {
+        result.push(REFERENCE_LINE);
+        stripped = true;
+      }
+
+      // Skip past the closing fence
+      i = j + 1;
+      continue;
+    }
+
+    result.push(item);
+    i++;
+  }
+
+  return result;
+}
+
+function stripArtifactSchemaFromString(str) {
+  // For cases where the schema is embedded in a longer string as a ```json...``` block
+  // Replace the first ```json ... ``` block with the reference line
+  const jsonFenceRegex = /```json[\s\S]*?```/;
+  if (jsonFenceRegex.test(str)) {
+    return str.replace(jsonFenceRegex, REFERENCE_LINE);
+  }
+  return str;
+}
+
+function processOtterFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const otter = JSON.parse(raw);
+
+  if (!Array.isArray(otter.system_prompt)) {
+    console.log(`  ⚠️  ${path.basename(filePath)}: system_prompt is not an array — skipping`);
+    return false;
+  }
+
+  // Check if the artifact schema block is spread across array elements (```json as its own element)
+  // or embedded within a longer string
+  const hasFenceAsElement = otter.system_prompt.some(
+    (s) => typeof s === 'string' && s.trim() === '```json'
+  );
+
+  const hasEmbeddedFence = otter.system_prompt.some(
+    (s) => typeof s === 'string' && s.includes('```json')
+  );
+
+  let modified = false;
+
+  if (hasFenceAsElement) {
+    // Multi-element block — strip using array strategy
+    const original = JSON.stringify(otter.system_prompt);
+    otter.system_prompt = stripArtifactSchemaFromArray(otter.system_prompt);
+    if (JSON.stringify(otter.system_prompt) !== original) {
+      modified = true;
+    }
+  } else if (hasEmbeddedFence) {
+    // Embedded fence within a string — strip using string replacement
+    const original = JSON.stringify(otter.system_prompt);
+    otter.system_prompt = otter.system_prompt.map((s) =>
+      typeof s === 'string' ? stripArtifactSchemaFromString(s) : s
+    );
+    if (JSON.stringify(otter.system_prompt) !== original) {
+      modified = true;
+    }
+  }
+
+  if (modified) {
+    fs.writeFileSync(filePath, JSON.stringify(otter, null, 2) + '\n');
+    console.log(`  ✅ ${path.basename(filePath)}: artifact schema block removed`);
+  } else {
+    console.log(
+      `  ℹ️  ${path.basename(filePath)}: no artifact schema block found (may already be clean)`
+    );
+  }
+
+  return modified;
+}
+
+console.log('Stripping hardcoded artifact schema blocks from specialist otters...\n');
+
+const otterFiles = fs
+  .readdirSync(OTTERS_DIR)
+  .filter((f) => f.endsWith('-otter.json') && f !== 'stackwright-pro-foreman-otter.json')
+  .map((f) => path.join(OTTERS_DIR, f));
+
+let totalModified = 0;
+for (const filePath of otterFiles) {
+  const modified = processOtterFile(filePath);
+  if (modified) totalModified++;
+}
+
+console.log(`\nDone. ${totalModified} otter file(s) modified.`);