@medicine-wheel/gap-analysis 0.5.3

package/README.md

@@ -0,0 +1,81 @@
+# @medicine-wheel/gap-analysis
+
+Problem-solving, built properly and without apology.
+
+> [!WARNING]
+> **Experimental alpha.** Part of the Medicine Wheel Developer Suite, which is
+> under active development. APIs change between patch versions and all packages
+> move in lockstep — pin exact versions. See
+> [ALPHA.md](https://github.com/jgwill/medicine-wheel/blob/main/ALPHA.md).
+
+## Why it exists
+
+Sometimes the forest is on fire. Digitally too. When something worked and
+stopped working, closing the difference between the current state and the prior
+one is the **right** move — oscillating back to a baseline is the goal when you
+are below the baseline.
+
+Work like that deserves a real instrument rather than a euphemism, so this
+package is built as a first-class citizen of the suite and not smuggled in under
+a nicer name.
+
+## The question at the door
+
+Every analysis carries an orientation reading taken when it was opened, via
+`@medicine-wheel/creative-orientation`. The question is always the same: *is a
+prior state actually being restored?*
+
+Opening an analysis **requires a baseline with evidence**. That requirement is
+the whole point — it is the thing that separates a fire from a creating act, and
+it cannot be satisfied by a feeling of urgency.
+
+```ts
+import { openGapAnalysis, addStep, doorAdvice } from '@medicine-wheel/gap-analysis';
+
+let analysis = openGapAnalysis(
+  { description: 'the published image matched the published packages',
+    evidence: 'true through 0.5.0, tagged 2026-07-17' },
+  { description: 'newest versioned image tag is 0.5.0; npm is at 0.5.2; 0.5.1 has no image',
+    source: 'Docker Hub tags API, read 2026-07-25' },
+  'the image no longer tracks npm because building it depends on a human remembering a flag',
+);
+
+doorAdvice(analysis);   // null — the situation and the instrument agree
+
+analysis = addStep(analysis, {
+  action: 'build the image from the tag in CI rather than from release.sh',
+  verifiedBy: 'a v* tag push produces :app and :<version> without anyone running anything',
+});
+```
+
+## It advises; it never refuses
+
+If you open an analysis without evidence for the baseline, you get the analysis
+**and** advice saying the routing rests on a feeling. You are not blocked. A
+package that refuses is a package you learn to route around, and sometimes the
+caller knows something the check does not.
+
+## Steps must be verifiable
+
+`addStep` rejects a step with no `verifiedBy`. An elimination step you cannot
+check is a wish; the fire is out only when something says so.
+
+## Where it sits
+
+```
+creative-orientation ......... the gate
+    ├── gap-analysis ......... you are here — the fire path
+    └── structural-tension ... the advancing path
+```
+
+Gap analysis is a borrowed instrument. It is genuinely available, and it is not
+the foundation — the orientation question comes first, and this package reports
+to it rather than the reverse.
+
+## Status
+
+First release. Small on purpose.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @medicine-wheel/gap-analysis
+ *
+ * The fire path, built properly and without apology.
+ *
+ * When something worked and stopped working, closing the difference between
+ * current and prior state is the correct move. Oscillation back to a baseline
+ * is the goal when you are below the baseline. This package exists so that
+ * work has a real instrument instead of a euphemism.
+ *
+ * It carries one question at its door — is a prior state actually being
+ * restored? — and asks it through `@medicine-wheel/creative-orientation`.
+ * It **advises and proceeds**. It never refuses. A package that blocks you is
+ * a package you learn to route around.
+ *
+ * @packageDocumentation
+ */
+import { type OrientationReading } from '@medicine-wheel/creative-orientation';
+export interface Baseline {
+    /** The state being restored, described concretely. */
+    description: string;
+    /** Evidence it existed — a date, a commit, a reading, a receipt. */
+    evidence: string;
+}
+export interface Observation {
+    /** What is true now, stated as measurement rather than interpretation. */
+    description: string;
+    /** Where this reading came from. */
+    source?: string;
+}
+export interface EliminationStep {
+    action: string;
+    /** How you will know this step worked. */
+    verifiedBy: string;
+    done?: boolean;
+}
+export interface GapAnalysis {
+    id: string;
+    baseline: Baseline;
+    current: Observation;
+    /** What is missing or wrong, derived from the two states above. */
+    difference: string;
+    rootCause?: string;
+    steps: EliminationStep[];
+    opened: string;
+    /**
+     * The orientation reading taken when this analysis was opened. Kept on the
+     * record so a later reader can see whether the instrument suited the
+     * situation, rather than having to reconstruct it.
+     */
+    orientation: OrientationReading;
+}
+export interface OpenGapOptions {
+    id?: string;
+    idFactory?: () => string;
+    timestamp?: string;
+}
+/**
+ * Open a gap analysis.
+ *
+ * A baseline with evidence is required, and that requirement is the whole
+ * point: it is the question that separates a fire from a creating act. If you
+ * cannot name a state that existed, the returned analysis carries advice
+ * saying so — and is still returned, because the caller may know something
+ * this check does not.
+ */
+export declare function openGapAnalysis(baseline: Baseline, current: Observation, difference: string, options?: OpenGapOptions): GapAnalysis;
+/** Add a step, with the check that makes it verifiable rather than hopeful. */
+export declare function addStep(analysis: GapAnalysis, step: EliminationStep): GapAnalysis;
+export declare function markDone(analysis: GapAnalysis, action: string): GapAnalysis;
+/** Closed when every step is done. Says nothing about whether it was the right analysis. */
+export declare function isClosed(analysis: GapAnalysis): boolean;
+/**
+ * The advice to surface at the door, if any.
+ *
+ * Returns null when the situation and the instrument agree — advice on
+ * correctly-framed work is noise, and noise is how checks get switched off.
+ */
+export declare function doorAdvice(analysis: GapAnalysis): string | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,sCAAsC,CAAC;AAE9C,MAAM,WAAW,QAAQ;IACvB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,WAAW,CAAC;IACrB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,cAAmB,GAC3B,WAAW,CA0Bb;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,GAAG,WAAW,CAQjF;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAK3E;AAED,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAE/D"}

package/dist/index.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openGapAnalysis = openGapAnalysis;
+exports.addStep = addStep;
+exports.markDone = markDone;
+exports.isClosed = isClosed;
+exports.doorAdvice = doorAdvice;
+/**
+ * @medicine-wheel/gap-analysis
+ *
+ * The fire path, built properly and without apology.
+ *
+ * When something worked and stopped working, closing the difference between
+ * current and prior state is the correct move. Oscillation back to a baseline
+ * is the goal when you are below the baseline. This package exists so that
+ * work has a real instrument instead of a euphemism.
+ *
+ * It carries one question at its door — is a prior state actually being
+ * restored? — and asks it through `@medicine-wheel/creative-orientation`.
+ * It **advises and proceeds**. It never refuses. A package that blocks you is
+ * a package you learn to route around.
+ *
+ * @packageDocumentation
+ */
+const creative_orientation_1 = require("@medicine-wheel/creative-orientation");
+function defaultId() {
+    return `gap:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Open a gap analysis.
+ *
+ * A baseline with evidence is required, and that requirement is the whole
+ * point: it is the question that separates a fire from a creating act. If you
+ * cannot name a state that existed, the returned analysis carries advice
+ * saying so — and is still returned, because the caller may know something
+ * this check does not.
+ */
+function openGapAnalysis(baseline, current, difference, options = {}) {
+    if (!baseline.description?.trim()) {
+        throw new Error('A gap analysis needs a baseline — the state you are restoring. Without one there is ' +
+            'nothing to close toward, and the situation is a creating act rather than a repair.');
+    }
+    if (!current.description?.trim()) {
+        throw new Error('A gap analysis needs an observation of what is true now.');
+    }
+    const claim = {
+        outcome: difference,
+        restores: baseline.description,
+        evidence: baseline.evidence,
+    };
+    return {
+        id: options.id ?? (options.idFactory ? options.idFactory() : defaultId()),
+        baseline,
+        current,
+        difference,
+        steps: [],
+        opened: options.timestamp ?? new Date().toISOString(),
+        orientation: (0, creative_orientation_1.readOrientation)(claim),
+    };
+}
+/** Add a step, with the check that makes it verifiable rather than hopeful. */
+function addStep(analysis, step) {
+    if (!step.verifiedBy?.trim()) {
+        throw new Error(`Step "${step.action}" has no verification. An elimination step you cannot check is a ` +
+            'wish; the fire is out only when something says so.');
+    }
+    return { ...analysis, steps: [...analysis.steps, step] };
+}
+function markDone(analysis, action) {
+    return {
+        ...analysis,
+        steps: analysis.steps.map(s => (s.action === action ? { ...s, done: true } : s)),
+    };
+}
+/** Closed when every step is done. Says nothing about whether it was the right analysis. */
+function isClosed(analysis) {
+    return analysis.steps.length > 0 && analysis.steps.every(s => s.done === true);
+}
+/**
+ * The advice to surface at the door, if any.
+ *
+ * Returns null when the situation and the instrument agree — advice on
+ * correctly-framed work is noise, and noise is how checks get switched off.
+ */
+function doorAdvice(analysis) {
+    return (0, creative_orientation_1.worthSaying)(analysis.orientation) ? analysis.orientation.advice ?? null : null;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AAiFA,0CA+BC;AAGD,0BAQC;AAED,4BAKC;AAGD,4BAEC;AAQD,gCAEC;AAjJD;;;;;;;;;;;;;;;;GAgBG;AACH,+EAK8C;AA8C9C,SAAS,SAAS;IAChB,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACvE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAC7B,QAAkB,EAClB,OAAoB,EACpB,UAAkB,EAClB,UAA0B,EAAE;IAE5B,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,sFAAsF;YACpF,oFAAoF,CACvF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,KAAK,GAAmB;QAC5B,OAAO,EAAE,UAAU;QACnB,QAAQ,EAAE,QAAQ,CAAC,WAAW;QAC9B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;KAC5B,CAAC;IAEF,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;QACzE,QAAQ;QACR,OAAO;QACP,UAAU;QACV,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrD,WAAW,EAAE,IAAA,sCAAe,EAAC,KAAK,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,SAAgB,OAAO,CAAC,QAAqB,EAAE,IAAqB;IAClE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,SAAS,IAAI,CAAC,MAAM,mEAAmE;YACrF,oDAAoD,CACvD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,SAAgB,QAAQ,CAAC,QAAqB,EAAE,MAAc;IAC5D,OAAO;QACL,GAAG,QAAQ;QACX,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACjF,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,SAAgB,QAAQ,CAAC,QAAqB;IAC5C,OAAO,QAAQ,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACjF,CAAC;AAED;;;;;GAKG;AACH,SAAgB,UAAU,CAAC,QAAqB;IAC9C,OAAO,IAAA,kCAAW,EAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACxF,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@medicine-wheel/gap-analysis",
+  "version": "0.5.3",
+  "description": "Problem-solving done properly — baseline, observation, difference, elimination steps — with the orientation question asked at its door rather than assumed.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "medicine-wheel",
+    "gap-analysis",
+    "problem-solving",
+    "root-cause",
+    "incident"
+  ],
+  "author": "jgwill",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/medicine-wheel.git",
+    "directory": "src/gap-analysis"
+  },
+  "dependencies": {
+    "@medicine-wheel/creative-orientation": "^0.5.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}