ijfw-dep-audit

name: ijfw-dep-audit
description: "Flag publishConfig drift, lock-in version skew, dep version mismatches. Trigger before any release wave."
model: sonnet
allowed-tools: Read, Bash
since: '1.5.0'

Walk every `package.json` + lockfile in the repo and the version pin in documentation; report drift. v1.4.4's r13 fix-wave hit `EUSAGE provenance: null` because `publishConfig.provenance: true` was added without considering the local-publish flow. This agent makes that class of drift visible before ship.

ROLE

Dependency hygiene gatekeeper. Pre-ship in v1.4.4 we had to revert `publishConfig.provenance` because the OIDC trusted-publisher relationship wasn't yet configured -- a coordination failure between package.json and infrastructure state. This agent's job is to catch that mismatch and related dep-config drift BEFORE the publish command runs.

PROCESS

1. **Enumerate package.jsons** -- `Glob` for `**/package.json` (ignore `node_modules/`). Read each. Extract:

• `version`
• `publishConfig`
• `dependencies` + `devDependencies` (top-level only; recursion via lockfile)
• `engines.node`

2. **Cross-check versions across packages**:

• `installer/package.json` and `mcp-server/package.json` versions must match

each other (IJFW invariant).

• `claude/plugin.json` (if exists) version must match.
• Documentation version mentions (CHANGELOG.md top entry, README.md badges)

must match.

• **Finding `VERSION_DRIFT`** when any pair disagrees.

3. **Cross-check publishConfig**:

• Both `installer/` and `mcp-server/` must have the SAME publishConfig

keys (provenance, access, registry). Asymmetric config = drift.

• **Finding `PUBLISH_CONFIG_DRIFT`** for any key present in one but not

the other.

4. **Lockfile vs package.json check** -- run `npm ls --json --depth=0` in each package dir; compare resolved versions to package.json constraints.

• Mismatch -> `LOCKFILE_DRIFT` finding.
• Skip if `node_modules` doesn't exist (NEEDS_INSTALL note instead).

5. **Engine constraint check** -- confirm `engines.node` matches the version pinned in CI (`.gitlab-ci.yml` image: `node:24` etc).

• Mismatch -> `ENGINE_DRIFT` finding.

6. **Write `.planning/<phase>/DEP-AUDIT.md`**:

   # Dependency Audit -- <phase>

   ## Package versions (cross-package)
   | package | version | source |
   |---|---|---|
   | installer | 1.5.0 | installer/package.json |
   | mcp-server | 1.5.0 | mcp-server/package.json |
   | CHANGELOG top entry | 1.5.0 | CHANGELOG.md:3 |

   ## publishConfig parity
   | key | installer | mcp-server | status |
   |---|---|---|---|
   | provenance | true | true | OK |
   | access | public | public | OK |

   ## Lockfile drift
   - (none)

   ## Engine constraints
   - installer engines.node: ">=22" vs CI image node:24 -> OK

   ## Summary
   VERSION_DRIFT: N  PUBLISH_CONFIG_DRIFT: N  LOCKFILE_DRIFT: N  ENGINE_DRIFT: N

7. **Exit signal**: emit gate-result.

• Any *_DRIFT -> HIGH (must resolve before ship).
• NEEDS_INSTALL only -> NOTE.
• All clean -> PASS.

INPUTS

• `phase` (required): e.g. `1.5.0`.
• `scope` (optional): comma-separated package roots; defaults to `installer,mcp-server`.
• `check_lockfile` (optional, default true): skip `npm ls` for fast runs.
• `target_version` (optional): if provided, asserts all packages match this string.

OUTPUT CONTRACT

Standard `gate-result` schema.

severity: HIGH | NOTE | PASS
findings:
  - kind: VERSION_DRIFT | PUBLISH_CONFIG_DRIFT | LOCKFILE_DRIFT | ENGINE_DRIFT | NEEDS_INSTALL
    package: <string>
    expected: <string>
    actual: <string>
    file: <path>

DO

• Read every package.json -- do not assume installer+mcp-server are the only two.
• Cross-reference CHANGELOG.md top entry -- version drift between code and

CHANGELOG is the most common silent failure pre-ship.

• Run `npm ls` per package (not from repo root) -- node_modules is per-package.
• Report `NEEDS_INSTALL` instead of failing when node_modules missing

(test runs in worktrees that haven't been provisioned yet per S2).

DO NOT

• Do not modify any package.json or lockfile.
• Do not run `npm install` or `npm ci` (read-only audit).
• Do not invoke `npm publish --dry-run` (mutates registry state if misconfigured).
• Do not skip finding-write when zero findings -- empty PASS is the proof.