@albinocrabs/feynman 0.2.2 → 0.2.4

package/examples/incident-response.md

@@ -0,0 +1,77 @@
+# Incident Response: API Latency Spike and 502s
+
+## Question
+
+> My API started returning intermittent 502s and latency jumped from 120ms to
+> 4s. I have Redis, API pods, and DB replicas. How should we triage and restore
+> service in the next 20 minutes?
+
+## Without feynman
+
+The API has a latency issue. First verify if the issue is traffic-related or a
+deployment regression, then inspect pods, then check cache hit rates, and then
+inspect database query times. If the pods are overloaded, scale horizontally and
+enable degraded mode. If Redis errors increase, fail over to DB reads with a strict
+timeout. If replicas are behind replication lag, move read traffic back to primary
+only and notify users of elevated error rates.
+
+## With feynman
+
+Triage and restore sequence:
+
+```
+[Alert: 502 + latency spike] --> [1) Confirm incident scope]
+                                  |
+                                  +--> [Critical path only]
+                                  |        |
+                                  |        +--> [Disable non-core features]
+                                  |        |
+                                  |        +--> [Enable queue fallback]
+                                  |
+                                  +--> [2) Isolate root layer]
+                                           |
+                                   [Cache regression?]
+                                      |
+                                yes -->|                   |--> no
+                                       v                   v
+                               [Scale API / limit RPS]   [Deployment rollback?]
+                                      |                   |
+                                      pass                    fail
+                                      |                      |
+                                      v                      v
+                             [Service partially stable]
+                                      |                   |
+                                      v                   v
+                               [Resolve]       [Rollback last deploy]
+                                                       |
+                                                       v
+                                         [Restore response rate]
+```
+
+Live status summary:
+
+```
+┌─ Incident Runbook ────────────────────┐
+  step-1        in-progress
+  step-2        pending
+  step-3        pending
+  external-comm on-call-channel
+└───────────────────────────────────────┘
+```
+
+Priority gates:
+
+```
+▲ high
+  API error budget burn
+  Security-sensitive write path (stop writes if needed)
+▼ low
+  Nice-to-have dashboards
+  Cosmetic alert updates
+```
+
+## Why this works
+
+This example combines sequential flow (triage stages), branch isolation, status
+frames, and priority scale. It turns ad-hoc firefighting into an explicit,
+readable execution plan before any action is taken.

package/examples/release-readiness.md

@@ -0,0 +1,73 @@
+# Release Readiness: Monthly Deployment to Production
+
+## Question
+
+> We have a monthly release with API, web, and mobile changes. What gates and
+> rollback triggers do we need before and after deploy?
+
+## Without feynman
+
+Coordinate release notes, run migration checks, execute smoke tests on staging, and
+run targeted regression tests. If deployment passes, monitor key metrics for one hour
+and then announce success. Rollback should be triggered on increased errors or
+critical latency regressions.
+
+## With feynman
+
+```
+[Pre-release plan] --> [Staging deploy]
+                      |
+                      v
+              [Smoke + regression]
+                      |
+             pass ----+---- fail
+              |              |
+              v              v
+        [Production]    [Stop + fix]
+              |
+              v
+        [Observe 60 min]
+              |
+      pass ----+---- fail
+       |              |
+       v              v
+[Done + announce] 
+[Rollback + incident]
+```
+
+Readiness gates:
+
+```
+criterion            | gate type | owner          | must be true
+--------------------|-----------|----------------|----------------------
+migration safety     | schema    | platform       | dry-run + backward-compatible
+auth/checkout smoke  | functional| product qa      | 100% critical paths
+error budget         | reliability| sre            | error rate <= baseline + 0.2%
+security regression  | security  | infosec        | zero new critical findings
+```
+
+Readiness status:
+
+- staging-deploy: done
+- smoke-tests: in progress
+- security-gate: pending
+- rollback-drill: ready
+- comms-draft: in progress
+
+Priority ladder:
+
+```
+▲ high
+  no data loss
+  idempotent migrations
+  auth + checkout paths
+▼ low
+  branding tweaks
+  help-center wording
+```
+
+## Why this works
+
+The flow diagram shows what blocks progression to production and where rollback
+branches back. The gate table gives objective pass criteria. The status frame and
+priority scale separate urgent reliability conditions from polish work.

package/examples/service-migration.md

@@ -0,0 +1,72 @@
+# Service Migration: Move Billing to a New Provider
+
+## Question
+
+> We need to migrate billing from Provider A to Provider B. What is the safest rollout
+> sequence with fallback and acceptance gates?
+
+## Without feynman
+
+Start in read mode to keep both providers enabled, compare charge outcomes for a
+sample of users, run a pilot for low-risk plans, then run a staged migration to
+full traffic with manual approval and rollback checkpoints.
+
+## With feynman
+
+Migration ladder:
+
+```
+[Dual-run mode]
+      |
+      v
+[Replay 30 days of traffic] --> [Compare divergence < 1%] --> [Pilot 5% users]
+      |
+      v
+[Auto-scaling smoke] --> [Pilot 30% users] --> [100% rollout]
+      |
+      +--> [Error rate > threshold] --> [Disable 30% wave]
+      |
+      +--> [Critical incidents] --> [Fallback to A]
+```
+
+Vendor comparison:
+
+```
+Option A (keep)   | Option B (move)      | Hybrid (dual)
+------------------|----------------------|------------------
+steady risk       | new integration risk  | controlled transition
+low complexity     | higher validation    | higher ops cost
+higher cost risk   | lower long-term cost  | medium monitoring
+fast execution     | phased execution      | slower initial step
+```
+
+Go/no-go gates:
+
+- divergence_rate <= 1%
+- failed callbacks < 0.2%
+- latency_p95 <= baseline + 20ms
+- reconciliation queue no growth
+
+Fallback playbook:
+
+- trigger: payment failure spike
+- action: switch traffic to A
+- deadline: < 10 minutes
+- owner: on-call + fintech lead
+
+Execution priority:
+
+```
+▲ high
+  reconciliation accuracy
+  callback reliability
+▼ low
+  brand messaging tweaks
+  custom dashboard layout
+```
+
+## Why this works
+
+В миграции ключевая ценность — показывать не просто шаги, а условия перехода между
+ступенями. Поток делает это явно: переход к следующей стадии возможен только при
+прохождении метрик и готовности fallback.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@albinocrabs/feynman",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Claude Code and Codex plugin that auto-injects ASCII diagram rules into every AI request via UserPromptSubmit hook",
   "license": "MIT",
   "author": "apolenkov",
@@ -52,14 +52,16 @@
     "test": "node --test tests/*.test.js",
     "coverage": "c8 --reporter=text --reporter=lcov node --test tests/*.test.js",
     "lint": "node bin/feynman-lint.js",
+    "audit": "npm audit --audit-level=moderate",
     "test:docs": "node scripts/check-docs.js",
     "test:release": "node scripts/release-smoke.js",
+    "test:published": "node scripts/verify-published-package.js",
     "build": "node scripts/build-package.js",
     "changelog": "node scripts/generate-changelog.js",
-    "ci": "npm run coverage && npm run test:docs && npm run test:release && npm run build",
+    "ci": "npm run audit && npm run coverage && npm run test:docs && npm run test:release && npm run build",
     "prepublishOnly": "npm run ci"
   },
   "devDependencies": {
-    "c8": "^10"
+    "c8": "^11.0.0"
   }
 }

package/rules/feynman-activate.md

@@ -1,8 +1,6 @@
 <!-- feynman diagram rules — feynman-activate.md -->
 <!-- Hook reads only the section matching the active intensity. -->
 <!-- Variants: lite (flow+trees), full (all types, default), ultra (force diagrams). -->
-<!-- Each section must stay under 8,000 chars. Measure with: -->
-<!--   node -e "const f=require('fs').readFileSync('rules/feynman-activate.md','utf8');['lite','full','ultra'].forEach(v=>{const s=f.indexOf('<!-- '+v+' -->');const e=f.indexOf('<!-- /'+v+' -->',s);console.log(v,f.slice(s,e+('<!-- /'+v+' -->').length).length,'chars');})" -->
 
 <!-- lite -->
 ## Feynman Diagram Rules — Lite
@@ -95,11 +93,11 @@ no persistence    | full persistence  | optional
 
 Syntax:
 ```
-┌─ Status ─┐
-  item-a    done
-  item-b    in progress
-  item-c    blocked
-└─────────┘
++---- Status ----+
+|item-a: done    |
+|item-b: in prog |
+|item-c: blocked |
++----------------+
 ```
 
 **Priority orderings** — A response that orders three or more items by priority, importance, severity, or rank includes an ▲▼ priority scale.

package/skills/feynman/SKILL.md

@@ -3,7 +3,8 @@ name: feynman
 disable-model-invocation: true
 description: >
   Toggle ASCII diagram injection on/off or set intensity level (lite/full/ultra).
-  Use when user says /feynman, /feynman on, /feynman off, /feynman lite/full/ultra, /feynman status.
+  Use when user says /feynman, /feynman on/start, /feynman off/stop,
+  /feynman lite/full/ultra, /feynman status.
 ---
 
 Manage feynman diagram injection. Read current state, apply requested change, report result.
@@ -11,8 +12,8 @@ Manage feynman diagram injection. Read current state, apply requested change, re
 ## When invoked
 
 Parse `$ARGUMENTS`:
-- `on` — enable feynman, keep current intensity
-- `off` — disable feynman
+  - `on`, `start` — enable feynman, keep current intensity
+  - `off`, `stop` — disable feynman
 - `lite` — enable at lite intensity (flows + trees only)
 - `full` — enable at full intensity (all diagram types)
 - `ultra` — enable at ultra intensity (force diagram always)
@@ -40,12 +41,13 @@ node -e "
 const fs = require('fs'), os = require('os'), path = require('path');
 const stateFile = path.join(os.homedir(), '.claude', '.feynman', 'state.json');
 const flagFile  = path.join(os.homedir(), '.claude', '.feynman-active');
-const arg = process.argv[1] || '';
+const arg = (process.argv[1] || '').trim().toLowerCase();
+const normalized = arg === 'start' ? 'on' : arg === 'stop' ? 'off' : arg;
 let st = {enabled: true, intensity: 'full', injections: 0};
 try { st = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch(e) {}
-if (arg === 'on')  { st.enabled = true;  fs.writeFileSync(flagFile, st.intensity); }
-if (arg === 'off') { st.enabled = false; try { fs.unlinkSync(flagFile); } catch(e) {} }
-if (['lite','full','ultra'].includes(arg)) { st.intensity = arg; st.enabled = true; fs.writeFileSync(flagFile, arg); }
+if (normalized === 'on')  { st.enabled = true;  fs.writeFileSync(flagFile, st.intensity); }
+if (normalized === 'off') { st.enabled = false; try { fs.unlinkSync(flagFile); } catch(e) {} }
+if (['lite','full','ultra'].includes(normalized)) { st.intensity = normalized; st.enabled = true; fs.writeFileSync(flagFile, normalized); }
 fs.mkdirSync(path.dirname(stateFile), {recursive: true});
 fs.writeFileSync(stateFile, JSON.stringify(st, null, 2));
 console.log(JSON.stringify(st));