Recipe: Stack Audit

A stack audit answers three questions: Is our dependency graph healthy? Are we accumulating tech debt? What should we upgrade next and in what order?

This recipe uses SpecForge's Stream H tools to run a complete stack health audit and build an actionable upgrade plan.

---

Step 1 — Run the Full Stack Audit

Prompt:

Audit the stack for project proj_abc123

What to expect:

Stack Health Score: 71/100

Dependency Status:
  up_to_date:    34 packages  ✅
  outdated:      12 packages  ⚠️
  vulnerable:     3 packages  🚨
  unmaintained:   1 package   ❌

Critical (fix immediately):
  - lodash 4.17.20 → CVE-2021-23337 (Prototype pollution)
  - axios 0.21.1 → CVE-2023-45857 (CSRF vulnerability)
  - follow-redirects 1.14.7 → CVE-2023-26159

High Priority (next sprint):
  - typescript 4.9.5 → 5.7.2 (13 minor versions behind)
  - vitest 0.34.0 → 3.1.0 (major version behind)
  - express 4.18.0 → 5.0.1 (major version available)

Medium Priority (this quarter):
  - 8 packages 1–3 minor versions behind

---

Step 2 — Detect Deprecated APIs

Prompt:

Detect deprecated APIs in project proj_abc123

This scans source files (no network required) for deprecated API usage:

Deprecated API Usage Found:

src/middleware/session.ts:14
  express-session secret as string — deprecated, use array of secrets
  Effort to fix: 0.5h

src/utils/crypto.ts:8
  crypto.createCipher — deprecated since Node 10, use createCipheriv
  Security risk: HIGH
  Effort to fix: 2h

src/config/database.ts:22
  mongoose.connect callback — deprecated in Mongoose 7, use promise
  Effort to fix: 1h

Total tech debt: ~3.5h

---

Step 3 — Plan Priority Upgrades

For each critical or high-priority item, generate an upgrade plan:

Prompt:

Plan the upgrade from axios 0.21.1 to the latest stable for project proj_abc123

What to expect:

## Axios Upgrade Plan: 0.21.1 → 1.7.9

### Breaking Changes
- AbortController replaces CancelToken (deprecated in v0.22)
- Default Content-Type for POST changed to application/json (no change needed)
- Response types changed in TypeScript definitions

### Migration Steps
1. Update package.json: axios ^1.7.9
2. Replace all CancelToken usage:
   - Find: axios.CancelToken.source()
   - Replace: AbortController / AbortSignal
3. Update TypeScript types (AxiosResponse generic changed)
4. Run test suite — axios interceptors are backward compatible

### Files affected (5):
- src/api/client.ts (CancelToken usage on line 34, 67)
- src/api/interceptors.ts (token cancel on line 89)
- src/utils/request.ts (timeout handling)
- tests/api/client.test.ts (mock updates needed)
- tests/api/interceptors.test.ts (mock updates needed)

### Estimated effort: 3h
### Rollback: pin to 0.27.2 (last stable 0.x)

---

Step 4 — Create Specs for Major Upgrades

For major version upgrades that affect multiple files, create a proper spec:

Prompt:

Create a spec for upgrading Express from 4.18 to 5.0 in project proj_abc123

This gives you:

• Acceptance criteria for the upgrade (all endpoints still work, no breaking behavior)
• A migration plan
• Test coverage requirements (before + after comparison)

---

Step 5 — Data Governance Check

If the project handles user data:

Prompt:

Run a data governance check for project proj_abc123

What to expect:

PII Detection:
  spec SPEC-003 (user registration): email, name, phone — needs retention policy
  spec SPEC-007 (analytics): IP address stored — GDPR legitimate interest required

GDPR Compliance:
  ✅ Data minimization — specs collect minimal PII
  ⚠️  Retention policy missing for user.email (SPEC-003)
  ⚠️  Right to erasure not specified in any spec
  ❌  No privacy notice spec exists

Recommendations:
  1. Create spec for GDPR compliance (right to erasure, data export)
  2. Add retention policy to SPEC-003
  3. Generate privacy notice template

---

Step 6 — Prioritize the Remediation Backlog

Prompt:

Create specs for the top 3 security vulnerabilities found in the stack audit for project proj_abc123

SpecForge creates specs for each CVE fix, properly scoped with acceptance criteria.

---

Step 7 — Track Progress

Schedule regular audits and track the StackHealthScore over time:

Prompt:

Audit the stack for project proj_abc123

Target: StackHealthScore ≥ 85, zero vulnerable or unmaintained packages.

---

Audit Cadence Recommendations

Trigger	Action
Monthly	audit_stack — full dependency scan
Quarterly	detect_deprecations — source scan
Pre-release	audit_stack + security_check on payment/auth specs
Post-incident	capture_learning + update affected specs
Major Node.js LTS	detect_deprecations + plan_upgrade for affected packages

---

Common Findings and Fixes

Finding	Tool	Typical fix time
CVE in direct dependency	plan_upgrade	1–4h
CVE in transitive dependency	plan_upgrade + manual override	2–8h
Deprecated API in source	detect_deprecations	0.5–3h per file
Unmaintained package	Replace with maintained fork	4–16h
Major version behind	plan_upgrade	2–12h