wogiflow 2.17.0 → 2.18.0

package/.claude/docs/intent-grounded-review.md

@@ -0,0 +1,209 @@
+# Intent-Grounded Review (IGR v6.0) — Reference
+
+Detailed reference for the IGR phases added to `/wogi-review` in v2.17.3. The main `/wogi-review` skill file contains the mandatory execution flow; this doc holds the full rationale, examples, and background each phase depends on.
+
+Read this when:
+- You're debugging unexpected review-skill behavior
+- You're tuning `config.review.*` and want to understand each key's impact
+- You're extending the review pipeline (adding a new phase, new adversary, new tier)
+- A review surfaced a false-positive finding and you want to know which phase should have caught it
+
+The four IGR additions to the review pipeline:
+
+| Phase | What it adds |
+|-------|---|
+| Phase 0 — Framing | Scope + assumptions surfaced BEFORE agents launch |
+| Phase 2 — Evidence Tiers | Every finding carries `evidenceTier` + `evidenceNote`; severity capped by tier |
+| Phase 2.8 — Findings Adversary | Different-model critique of the findings themselves |
+| Phase 5 — Completion Truth Gate | "Fixed" claims require INTERACTIVE evidence |
+
+---
+
+## Phase 0: Review Framing Pass — Reference Detail
+
+**Problem this solves**: "Review" means different things in different invocations. "Review what we just did" is bounded to the session diff; "review the auth flow" is bounded to a module; "review before ship" expects a final-sign-off posture. Without explicit framing, the AI picks its own scope and grades findings against its own mental rubric, producing a different answer than the user asked for.
+
+### The Five Framing Fields
+
+| Field | What it captures |
+|---|---|
+| `interpretation` | One sentence: "I understand this as: review X with posture Y" |
+| `scopeIn` | Explicit list: which files, commits, or modules are in scope |
+| `scopeOut` | Explicit list: what this review will NOT cover (by design, not omission) |
+| `assumptions` | 2–5 review-model assumptions (e.g., "a refactor review must verify behavior preservation, not just test pass") |
+| `posture` | `pre-ship` / `session-review` / `security-focused` / `exploratory` — adjusts agent emphasis |
+
+### Posture → Agent Weight Adjustment
+
+- `pre-ship` → boost security + integration agents, require Phase 2.8 adversary pass
+- `session-review` → balanced across all agents
+- `security-focused` → security agent mandatory, injection/authn checks emphasized
+- `exploratory` → logic + architecture agents; adversary pass OPTIONAL (via `config.review.framingPass.adversaryInExploratory`)
+
+### Item Reconciliation (Anti-Deferral Guard)
+
+When the user's request enumerated multiple focus areas ("review X, Y, Z"), each named item MUST appear in `scopeIn`. If the count shrank (user named 5, framing has 3), the framing pass FAILS — display which items were dropped and require the user to confirm before proceeding.
+
+Ported from `/wogi-start`'s anti-deferral rule. The AI cannot silently drop items.
+
+---
+
+## Phase 2: Evidence Tiers — Reference Detail
+
+Every finding returned by any review agent MUST carry two additional fields: `evidenceTier` (0–4) and `evidenceNote` (one-line string citing what produced the evidence).
+
+### Tier Definitions
+
+| Tier | Name | What it means for findings |
+|------|------|----------------------------|
+| 0 | STATIC | AI inferred from the source alone — no grep, no execution. Weakest. |
+| 1 | STRUCTURAL | AI grepped / globbed / counted instances across the codebase. |
+| 2 | OBSERVATIONAL | AI ran a tool (lint, typecheck, npm audit) and read its output. |
+| 3 | INTERACTIVE | AI executed code or tests and observed the behavior. |
+| 4 | AUTOMATED | A quality gate or test suite produces this finding deterministically on every run. |
+
+### Severity Cap Rules
+
+- **Tier 0** findings: severity MUST be LOW (and flagged UNVERIFIED in the report).
+- **Tier 1** findings: severity capped at MEDIUM unless grep returned ≥5 instances.
+- **Tier 2+** findings: severity stands as the agent assigned.
+
+### Why Tiers Matter (Real Incident)
+
+During the v2.17.3 self-review (session 2026-04-15), a `code-reviewer` agent reported an F1 finding as "Critical — broken require path" without citing evidence. Manual verification via `require.resolve()` showed the path was correct — the agent's path math was flawed.
+
+With tier enforcement, F1 would have been Tier 0 (no grep, no execution), capped at LOW, and flagged UNVERIFIED — alerting the reader to verify before acting. The evidence-tier requirement is the single most powerful rubber-stamp-prevention mechanism in the IGR toolkit.
+
+---
+
+## Phase 2.8: Findings Adversary Critique — Reference Detail
+
+This is the review analogue of the `/wogi-audit` Adversary Pass (Step 3.5) and the IGR Logic Adversary (wf-3975a001). Same pattern: different model, separate context, looking for specific defect classes.
+
+### Adversary Model Selection Rule (CRITICAL)
+
+The `adversaryPass.adversaryModel` is a mapping, NOT a static string. The AI resolves it at runtime by inspecting which model the review agents used.
+
+```json
+"adversaryModel": {
+  "whenAgentOnSonnet": "opus",
+  "whenAgentOnOpus": "sonnet",
+  "whenAgentOnHaiku": "sonnet",
+  "default": "sonnet"
+}
+```
+
+**Override-always rule**: if the resolved value equals the agent model (e.g., legacy plain-string config set to `sonnet` when agents ran on Sonnet), pick a different model instead. Same-model adversary = rubber-stamp, which defeats the entire purpose of the adversary pass.
+
+### Specific Defect Classes to Hunt
+
+The adversary prompt includes HUNT instructions for these patterns:
+
+1. Findings where `evidenceTier=0` but severity ≥ HIGH
+2. Findings that cite line numbers without quoting the surrounding code
+3. "Broken require path" / "missing import" / "wrong type" claims without `require.resolve` / `tsc` / `grep` verification
+4. Findings that contradict the framing's `scopeIn` / `scopeOut` declarations
+
+### Applied Adjustments
+
+The orchestrator applies the adversary's recommendations automatically:
+
+- `severityAdjustments` rewrite findings' severity in the consolidated report (mark `[ADVERSARY-ADJUSTED]`)
+- `scopeDrift` moves findings out of the main report into an "Out-of-Scope Findings" appendix (not dropped — user still sees them)
+- `falsePositives` get marked `[DISPUTED]` in the report body (not removed — user sees both the finding AND the dispute)
+- `missedIssues` get appended as new Tier-0 findings labeled `[ADVERSARY-FOUND]`
+- `evidenceChallenges` downgrade the `evidenceTier` on challenged findings and re-apply the severity cap
+
+### Verdict Semantics
+
+- `ACCEPT` — no adjustments needed; findings are well-grounded
+- `ACCEPT_WITH_ADJUSTMENTS` — severity caps/scope fixes applied, report still ships
+- `REVISE_SCOPE` — framing was wrong; reviewer should restart with corrected scope
+- `BLOCK` — adversary found a critical false positive or missed issue that makes the report untrustworthy; user must acknowledge before Phase 3 proceeds
+
+**One pass only** — no iteration loop. If the adversary BLOCKS, the user calls it out and we re-review with adjusted scope.
+
+### Archival
+
+Every adversary run is archived to `.workflow/state/adversary-runs/review-{timestamp}.json` — same directory as IGR + audit adversary runs. This feeds the `flow promote` pipeline: recurring review-adversary findings graduate to `feedback-patterns.md`.
+
+---
+
+## Phase 5: Completion Truth Gate — Reference Detail
+
+**Problem this solves**: A review's "fixed" claim is only as good as the evidence behind it. A finding marked `fixed` because the AI applied an edit is NOT the same as a finding verified to work. Without a truth gate, the sign-off rubber-stamps whatever the agent says.
+
+### Downgrade Rules
+
+For every finding now marked `status: fixed`:
+
+| Fix evidence tier | New status |
+|---|---|
+| Tier ≥ 3 (INTERACTIVE) | stays `fixed` |
+| Tier 4 (AUTOMATED quality gate) | stays `fixed` |
+| Tier 2 (OBSERVATIONAL — lint/typecheck pass only) | downgraded to `fixed-unverified` |
+| Tier ≤ 1 (STATIC / STRUCTURAL) | downgraded to `implemented-unverified` |
+
+### Persistence
+
+Downgraded statuses are persisted to `last-review.json` — NOT silently dropped back to `fixed`. The user should consciously accept unverified fixes, not have them hidden.
+
+### Self-Incident (v2.17.4)
+
+In v2.17.4 I claimed to "fix all review findings." The truth gate (applied manually) caught:
+
+- F1, F2, F3 — fixed with Tier 2+ evidence (OK)
+- F4 — doc update only, Tier 0, should have been `implemented-unverified`
+- M1 — deferred, but the release notes said "fix all" — promise/delivery mismatch
+- M3 — dropped entirely, never mentioned in the commit
+
+User correction: "You're not supposed to defer any fixes. It's up to the user to defer, not you." → Anti-Deferral Guard added to feedback-patterns + decisions.
+
+---
+
+## Config Enforcement Model — Reference Detail
+
+All `config.review.*` toggles are AI-honored, not runtime-enforced. No JavaScript reads `config.review.framingPass`, `config.review.evidenceTiers`, `config.review.adversaryPass`, or `config.review.completionTruthGate`.
+
+The AI executing `/wogi-review` is responsible for reading these keys via `getConfig()` and honoring them. This matches `/wogi-audit`'s docs-driven model.
+
+**Practical implication**: a user who sets `review.adversaryPass.enabled: false` will have the pass skipped ONLY if the AI respects the config. As a reviewer, always load config first and print the toggle states before launching phases.
+
+---
+
+## Config Reference (all IGR keys)
+
+```json
+{
+  "review": {
+    "minFindings": 3,
+    "requireJustificationIfClean": true,
+    "framingPass": {
+      "enabled": true,
+      "itemReconciliation": true,
+      "adversaryInExploratory": false
+    },
+    "evidenceTiers": {
+      "enabled": true,
+      "capByTier": true
+    },
+    "adversaryPass": {
+      "enabled": true,
+      "adversaryModel": {
+        "whenAgentOnSonnet": "opus",
+        "whenAgentOnOpus": "sonnet",
+        "whenAgentOnHaiku": "sonnet",
+        "default": "sonnet"
+      },
+      "applySeverityAdjustments": true,
+      "applyScopeDrift": true,
+      "blockOnBlockVerdict": true,
+      "archiveRuns": true
+    },
+    "completionTruthGate": {
+      "enabled": true,
+      "requireInteractiveForFixed": true
+    }
+  }
+}
+```

package/.claude/settings.json

@@ -133,10 +133,43 @@
           }
         ]
       }
+    ],
+    "TaskCreated": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/entry/claude-code/task-created.js",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PermissionDenied": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/entry/claude-code/permission-denied.js",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node scripts/hooks/entry/claude-code/pre-compact.js",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   },
   "_comment_dynamicHooks": "TaskCreated (2.1.84+) and PermissionDenied (2.1.88+) are added by postinstall.js when the CC version supports them. They must NOT be committed statically — CC rejects the entire settings file if it encounters an unknown hook event name.",
   "_wogiFlowManaged": true,
-  "_wogiFlowVersion": "2.4.2",
+  "_wogiFlowVersion": "2.17.5",
   "_comment": "Shared WogiFlow hook configuration. Committed to repo for team use. User-specific overrides go in settings.local.json."
 }

package/.workflow/agents/logic-adversary.md

@@ -35,6 +35,14 @@ Patterns that produce logic failures in practice — seen in real agent session
 
 **P11.3 — Also check for EXISTING WOGIFLOW FEATURES that touch the same domain.** Before shipping any new mechanism (hook, wrapper, CLI entry, state file, config key, skill), enumerate the sibling surface: (S1) `grep -r "execSync\|spawn.*claude" lib/ scripts/`, check `.claude/commands/`, check `scripts/flow-constants.js`, check `lib/workspace.js` — does an existing feature already touch this domain? (S2) Show how the new mechanism composes, conflicts, or integrates with each sibling. "Orthogonal" is OK but must be asserted. (S3) If integration work is needed (e.g., the new wrapper needs to be injected into workspace's `execSync('claude')` call), include it in scope OR explicitly file a follow-up story. Silent omission of sibling integration = FAIL. Example violation caught live: `wogi-claude` wrapper initially missed that `lib/workspace.js:1612` spawns claude directly, so workspace-mode workers weren't restart-capable.
 
+**P11.4 — Generative edge-case taxonomy (5 buckets, always run for any new mechanism).** Go through EACH bucket and demand a sentence of acknowledgment — "addressed by X", "N/A because Y", or "accepted limitation Z documented in spec". Blank buckets = FAIL. The buckets: **B1 Interleaving/concurrency** (TOCTOU, two instances at once, hook-in-hook races), **B2 Partial failure** (step 1 ok, step 2 fails — is the half-done state acceptable?), **B3 Boundary counts** (0x, 1x, 1000x — accumulation, caps, restart-storm), **B4 Execution-environment portability** (which OS/browser/runtime/deploy-target variants does this run in? Which are in scope vs explicitly unsupported?), **B5 Silent-failure observability** (if it breaks silently, will anyone notice? — is there a health-check surface, log line, or telemetry event?). Distinct from P11.1-P11.3 because it's GENERATIVE (force-enumeration) not REACTIVE (critique what the plan says).
+
+**Stack-agnostic**: the buckets are universal. Substitute examples with whatever your plan's stack uses. "Windows / non-bash / filesystem" applies to CLI tools; for web frontends B4 means "Safari vs Chrome vs mobile WebView, SSR vs CSR, accessibility modes"; for mobile apps it means "iOS / Android versions, phone vs tablet"; for backends it means "Node/Python/Go runtime spread, containerized vs bare-metal, serverless cold-start". See rubric P11.4 for the full stack-specific mapping.
+
+Cost: ~50-100 words added per plan. Value: catches architectural gaps at plan-time that otherwise surface as post-ship fires.
+
+Reflex (stack-agnostic): *"for this mechanism — can 2 run at once? can a step half-fail? what happens at 0x and 1000x? which execution-environment variants does this run on? if this breaks silently, what surfaces it?"*
+
 ### What you are NOT looking for
 
 - Code style, lint, naming — other gates handle these.

package/.workflow/templates/claude-md.hbs

@@ -131,6 +131,7 @@ npm install -D wogiflow && npx flow onboard
 | `/wogi-register` | Register plugins for /wogi-start routing |
 
 See `.claude/docs/commands.md` for complete command reference.
+See `.claude/docs/claude-code-compatibility.md` for Claude Code version features, performance tips, and env vars (incl. **`ENABLE_PROMPT_CACHING_1H=1`** recommended for API-key / Bedrock / Vertex / Foundry users).
 
 ## Natural Language Command Detection
 
@@ -243,6 +244,23 @@ If the user provides N items, ALL N must become tracked work items. No exception
 
 **When genuinely unsure the work is still needed**: ask the user explicitly — "Do you still want wf-XXXX to ship this epic, or should we drop it?" Let them decide. Do NOT make that call autonomously.
 
+### Review-Findings Anti-Deferral (MANDATORY — INCIDENT-DRIVEN)
+
+**Extends Mid-Execution Anti-Deferral to `/wogi-review`, `/wogi-audit`, `/wogi-triage` findings.** If the user asks you to "fix all findings" / "option 1" / any variant that means "address everything," you MUST:
+
+1. **Ship a fix for every finding that carries evidence tier ≥ 1**, regardless of effort estimate.
+2. **Never silently convert a finding to "deferred"** in the commit or release notes without the user explicitly saying "defer X."
+3. **If an item is genuinely too large for the current release**, STOP and ask: "Finding X requires ~Y minutes of work. Ship it in this release, split it into its own release, or defer? Your call."
+4. **Never list a finding in the release description without fixing it.** If v2.17.4 says "fixes F1, F2, F3, M1" and M1 wasn't fixed, that's a promise/delivery mismatch — exactly the rubber-stamp pattern the Completion Truth Gate was designed to prevent.
+
+**Anti-Rationalization Checklist for review findings** — if you catch yourself thinking any of these, STOP:
+- "M1 is a restructure, that warrants a separate release" → WRONG. The user said fix all. Ask first if you think it's too big.
+- "This finding is low-risk, it can wait" → WRONG. Low-risk doesn't mean drop-worthy.
+- "The release notes will acknowledge it's deferred" → WRONG. User didn't defer. You are.
+- "I'll mention it in the commit so it's transparent" → WRONG. Transparency ≠ permission. Ship the fix.
+
+**Incident that promoted this rule to decisions.md**: 2026-04-15, v2.17.4 release. I claimed "fix all" in the commit message but silently deferred M1 (wogi-review.md bloat) and completely dropped M3 (_fastPath test coverage gap) from the Findings Adversary. User correction: "You're not supposed to defer any fixes. It's up to the user to defer, not you." v2.17.5 fixed M1 + M3 and added this rule.
+
 ### Task ID Format (MANDATORY)
 
 All task IDs MUST be generated by `generateTaskId()` from `wogiflow/scripts/flow-utils.js`. **Never manually type a task ID.**

package/lib/installer.js

@@ -16,6 +16,7 @@ const readline = require('node:readline');
 
 // Shared utilities
 const { copyDir, safeReadJson } = require('./utils');
+const { getTodayDate } = require('../scripts/flow-output');
 
 // Package root (where wogi-flow is installed)
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
@@ -1029,6 +1030,27 @@ async function init(args) {
   console.log('  /wogi-health  - Check workflow health');
   console.log('  /wogi-story   - Create a new story');
   console.log('');
+  printPromptCachingTip();
+}
+
+/**
+ * Print the ENABLE_PROMPT_CACHING_1H recommendation for non-subscriber Claude Code users.
+ *
+ * Claude Pro/Max/Team/Enterprise (OAuth via claude.ai) already get 1-hour prompt-cache TTL.
+ * API-key, Bedrock, Vertex, and Foundry users default to 5min TTL — any pause longer than
+ * 5min during a WogiFlow session invalidates the cached CLAUDE.md + state-file prefix and
+ * re-pays the full input-token cost on the next turn. Enabling 1h TTL gives substantial
+ * savings on typical multi-hour sessions.
+ *
+ * We surface this exactly once, during `flow init` onboarding. The full rationale lives in
+ * `.claude/docs/claude-code-compatibility.md` under "Features in 2.1.108+".
+ */
+function printPromptCachingTip() {
+  console.log('💡 Performance tip (API-key / Bedrock / Vertex / Foundry users):');
+  console.log('   Set \x1b[33mENABLE_PROMPT_CACHING_1H=1\x1b[0m in your shell profile for 1-hour');
+  console.log('   prompt-cache TTL (default is 5min). Claude subscribers already get 1h by default.');
+  console.log('   Details: \x1b[36m.claude/docs/claude-code-compatibility.md\x1b[0m (Features in 2.1.108+)');
+  console.log('');
 }
 
 /**

package/lib/utils.js

@@ -20,20 +20,46 @@ const REQUEST_TIMEOUT = 10000; // 10 seconds
 const MAX_RESPONSE_SIZE = 10 * 1024 * 1024; // 10MB
 
 /**
- * Find the project root by looking for .workflow directory
+ * Find the project root with layered strategies:
+ *   (0) WOGI_PROJECT_ROOT env var if set and valid
+ *   (1) git rev-parse --show-toplevel (handles worktrees, submodules)
+ *   (2) filesystem walk for .workflow
+ *
+ * Matches scripts/flow-paths.getProjectRoot semantics — enhanced 2026-04-15
+ * per audit dup-005 (wf-7072d3ac). Kept in lib/ because lib/ cannot require
+ * from scripts/ (cross-domain dependency per dual-repo-management.md).
+ *
  * @returns {string|null} Project root path or null if not in a project
  */
 function findProjectRoot() {
+  // Strategy 0: env var short-circuit
+  if (process.env.WOGI_PROJECT_ROOT && fs.existsSync(path.join(process.env.WOGI_PROJECT_ROOT, '.workflow'))) {
+    return process.env.WOGI_PROJECT_ROOT;
+  }
+
+  // Strategy 1: git rev-parse (handles worktrees + submodules)
+  try {
+    const { execSync } = require('node:child_process');
+    const gitRoot = execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (gitRoot && fs.existsSync(path.join(gitRoot, '.workflow'))) {
+      return gitRoot;
+    }
+  } catch (_err) {
+    // Not in git repo or git unavailable — fall through to walk
+  }
+
+  // Strategy 2: filesystem walk (works outside git)
   let dir = process.cwd();
   const root = path.parse(dir).root;
-
   while (dir !== root) {
     if (fs.existsSync(path.join(dir, '.workflow'))) {
       return dir;
     }
     dir = path.dirname(dir);
   }
-
   return null;
 }
 

package/lib/workspace-changelog.js

@@ -11,6 +11,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { safeReadJson } = require('./utils');
 
 const { WORKSPACE_CONFIG_FILE } = require('./workspace');
 
@@ -94,7 +95,7 @@ function aggregateChangelogs(workspaceRoot, options = {}) {
 
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    config = safeReadJson(configPath);
   } catch (_err) {
     return { entries: [], memberCount: 0, totalEntries: 0 };
   }

package/lib/workspace-channel-server.js

@@ -20,6 +20,7 @@
 
 const http = require('node:http');
 const readline = require('node:readline');
+const { safeJsonParseContent } = require('./utils');
 
 // ============================================================
 // Constants
@@ -372,12 +373,9 @@ rl.on('line', (line) => {
   const trimmed = line.trim();
   if (!trimmed) return;
 
-  try {
-    const msg = JSON.parse(trimmed);
-    handleRequest(msg);
-  } catch (_err) {
-    // Ignore malformed JSON
-  }
+  const msg = safeJsonParseContent(trimmed);
+  if (msg) handleRequest(msg);
+  // else ignore malformed / prototype-polluting JSON
 });
 
 // ============================================================

package/lib/workspace-contracts.js

@@ -11,6 +11,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { safeReadJson } = require('./utils');
 const crypto = require('node:crypto');
 
 // ============================================================
@@ -410,7 +411,7 @@ function trackContractVersion(workspaceRoot, contractName, content, changedBy, r
   let versions = { contracts: {} };
   try {
     if (fs.existsSync(versionsPath)) {
-      versions = JSON.parse(fs.readFileSync(versionsPath, 'utf-8'));
+      versions = safeReadJson(versionsPath);
     }
   } catch (_err) {
     versions = { contracts: {} };
@@ -468,7 +469,7 @@ function generateContractChangelog(workspaceRoot) {
 
   let versions;
   try {
-    versions = JSON.parse(fs.readFileSync(versionsPath, 'utf-8'));
+    versions = safeReadJson(versionsPath);
   } catch (_err) {
     return '# Contract Changelog\n\nError reading contract versions file.\n';
   }
@@ -514,7 +515,7 @@ function detectContractFormat(filePath) {
   if (ext === '.ts' || ext === '.d.ts') return 'typescript';
   if (ext === '.json') {
     try {
-      const content = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      const content = safeReadJson(filePath);
       if (content.openapi || content.swagger) return 'openapi';
       if (content.$schema?.includes('json-schema')) return 'jsonschema';
       if (content.type || content.properties) return 'jsonschema';
@@ -693,7 +694,7 @@ function checkTypeSyncCompliance(workspaceRoot, manifest) {
   // Check each consumer's schema-map for duplicates
   const configPath = path.join(workspaceRoot, 'wogi-workspace.json');
   try {
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const config = safeReadJson(configPath);
 
     for (const [name, memberConfig] of Object.entries(config.members || {})) {
       const member = manifest.members?.[name];

package/lib/workspace-events.js

@@ -26,6 +26,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { safeReadJson, safeJsonParseContent } = require('./utils');
 const crypto = require('node:crypto');
 
 // ============================================================
@@ -150,13 +151,13 @@ function readEvents(workspaceRoot, filter = {}) {
       const content = fs.readFileSync(eventsPath, 'utf-8');
       // Support both NDJSON (one JSON per line) and legacy JSON array format
       if (content.trimStart().startsWith('[')) {
-        events = JSON.parse(content);
+        events = safeJsonParseContent(content, []);
         if (!Array.isArray(events)) events = [];
       } else {
         // NDJSON format
-        events = content.trim().split('\n').filter(Boolean).map(line => {
-          try { return JSON.parse(line); } catch (_err) { return null; }
-        }).filter(Boolean);
+        events = content.trim().split('\n').filter(Boolean)
+          .map(line => safeJsonParseContent(line))
+          .filter(Boolean);
       }
     }
   } catch (_err) {
@@ -229,7 +230,7 @@ function saveSubscription(workspaceRoot, subscription) {
 
   try {
     if (fs.existsSync(subsPath)) {
-      subs = JSON.parse(fs.readFileSync(subsPath, 'utf-8'));
+      subs = safeReadJson(subsPath);
       if (!Array.isArray(subs)) subs = [];
     }
   } catch (_err) {
@@ -254,7 +255,7 @@ function getActiveSubscriptions(workspaceRoot) {
 
   try {
     if (fs.existsSync(subsPath)) {
-      const subs = JSON.parse(fs.readFileSync(subsPath, 'utf-8'));
+      const subs = safeReadJson(subsPath);
       return (Array.isArray(subs) ? subs : []).filter(s => s.active);
     }
   } catch (_err) {
@@ -276,7 +277,7 @@ function removeSubscription(workspaceRoot, subscriptionId) {
 
   try {
     if (!fs.existsSync(subsPath)) return false;
-    let subs = JSON.parse(fs.readFileSync(subsPath, 'utf-8'));
+    let subs = safeReadJson(subsPath);
     if (!Array.isArray(subs)) return false;
 
     const before = subs.length;

package/lib/workspace-gates.js

@@ -19,6 +19,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { safeReadJson } = require('./utils');
 
 const { WORKSPACE_CONFIG_FILE, WORKSPACE_DIR } = require('./workspace');
 const { buildIntegrationMap } = require('./workspace-contracts');
@@ -150,7 +151,7 @@ function identifyCurrentMember(workspaceRoot, cwd) {
   const configPath = path.join(workspaceRoot, WORKSPACE_CONFIG_FILE);
 
   try {
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const config = safeReadJson(configPath);
     for (const [name, memberConfig] of Object.entries(config.members || {})) {
       const memberPath = path.resolve(workspaceRoot, memberConfig.path);
       if (currentDir === memberPath || currentDir.startsWith(memberPath + path.sep)) {
@@ -187,7 +188,7 @@ function loadWorkspaceContext(workspaceRoot) {
   // Load config
   const configPath = path.join(workspaceRoot, WORKSPACE_CONFIG_FILE);
   try {
-    context.config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    context.config = safeReadJson(configPath);
   } catch (_err) {
     return context;
   }
@@ -196,7 +197,7 @@ function loadWorkspaceContext(workspaceRoot) {
   const manifestPath = path.join(workspaceRoot, WORKSPACE_DIR, 'state', 'workspace-manifest.json');
   try {
     if (fs.existsSync(manifestPath)) {
-      context.manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+      context.manifest = safeReadJson(manifestPath);
     }
   } catch (_err) {
     // Non-critical

package/lib/workspace-integration-tests.js

@@ -12,6 +12,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { safeReadJson } = require('./utils');
 
 const { buildIntegrationMap } = require('./workspace-contracts');
 
@@ -190,7 +191,7 @@ function generateAllIntegrationSpecs(workspaceRoot, oldManifest, newManifest) {
     try {
       const contractPath = path.join(contractsDir, `${impact.provider}.json`);
       if (fs.existsSync(contractPath)) {
-        contract = JSON.parse(fs.readFileSync(contractPath, 'utf-8'));
+        contract = safeReadJson(contractPath);
       }
     } catch (_err) {
       // No contract available — generate basic tests

package/lib/workspace-intelligence.js

@@ -11,6 +11,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { safeReadJson } = require('./utils');
 
 // ============================================================
 // S5: Contract Drift Detection (Criterion 1)
@@ -35,7 +36,7 @@ function detectContractDrift(workspaceRoot, manifest) {
 
   for (const file of files) {
     try {
-      const spec = JSON.parse(fs.readFileSync(path.join(contractsDir, file), 'utf-8'));
+      const spec = safeReadJson(path.join(contractsDir, file));
       if (spec.paths) {
         for (const [routePath, methods] of Object.entries(spec.paths)) {
           for (const method of Object.keys(methods)) {
@@ -906,7 +907,7 @@ function auditWorkspaceDimension(workspaceRoot, manifest) {
   try {
     const memberMetadata = {};
     const configPath = path.join(workspaceRoot, 'wogi-workspace.json');
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    const config = safeReadJson(configPath);
 
     for (const [name, memberConfig] of Object.entries(config.members || {})) {
       const memberPath = path.resolve(workspaceRoot, memberConfig.path);

package/lib/workspace-locks.js

@@ -19,6 +19,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { safeReadJson } = require('./utils');
 const crypto = require('node:crypto');
 
 // ============================================================
@@ -240,7 +241,7 @@ function listLocks(workspaceRoot) {
     const files = fs.readdirSync(locksDir).filter(f => f.endsWith('.json'));
     for (const file of files) {
       try {
-        const content = JSON.parse(fs.readFileSync(path.join(locksDir, file), 'utf-8'));
+        const content = safeReadJson(path.join(locksDir, file));
         if (content.id && content.interface && content.owner) {
           locks.push(content);
         }