@medicine-wheel/brainstorming 0.5.3

package/README.md

@@ -0,0 +1,85 @@
+# @medicine-wheel/brainstorming
+
+Idea into committed design, through approval gates a human holds.
+
+> [!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
+
+Convergence has a shape: read the ground, ask one question at a time, offer two
+or three approaches with trade-offs, present the design in sections each
+approved before the next, write the spec, let the human read it, then plan. This
+package holds that shape as data rather than as advice, so it cannot be
+forgotten under load.
+
+## The part that matters
+
+It routes **every outcome statement it emits** through
+`@medicine-wheel/creative-orientation` — including its own questions.
+
+That is not decoration. An outcome phrased as elimination inside a
+multiple-choice option becomes the human's *selected answer*, and from that
+moment it stops looking like the agent's bias and starts looking like a
+requirement. The moment of speaking is the only point where that is still
+catchable.
+
+```ts
+import { openSession, checkOptions, ask, suspendedOn, advance } from '@medicine-wheel/brainstorming';
+
+const session = openSession('every cross-repository change arrives verified against its consumers');
+
+checkOptions(session, [
+  'Catch cross-service contract breaks',
+  'Every change arrives already verified',
+]);
+// → one finding, on the first option: phrased as removing something,
+//   while nothing is being restored.
+```
+
+## Gates are suspended states, not pauses
+
+`ask()` suspends the session on a question. `advance()` **refuses** while a gate
+is unanswered.
+
+This is the one place refusal is correct. Everywhere else in this suite a check
+advises and lets the caller proceed — but a gate is a question addressed to a
+person, and answering it on their behalf is not a shortcut. It is a
+substitution.
+
+```ts
+const waiting = ask(session, 'thin convention, or a framework?');
+suspendedOn(waiting);   // the gate, holding
+advance(waiting);       // throws — the question belongs to someone else
+```
+
+## Phases
+
+`explore → clarify → approaches → design → spec → review → plan`
+
+Four of them are gated: `clarify`, `approaches`, `design`, `review`. Those are
+the points where a half-finished creative process waits for its human — and
+where, today, we still have nowhere good to put that suspended state when the
+connection drops.
+
+## Where it sits
+
+```
+creative-orientation ......... the gate
+    ├── gap-analysis ......... the fire path
+    └── structural-tension ... the advancing path
+
+brainstorming ................ calls the gate on everything it says
+```
+
+## Status
+
+First release. The protocol is expressed; the surface for *holding* a suspended
+session across a dropped connection is not solved here and is named as open.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @medicine-wheel/brainstorming
+ *
+ * Idea into committed design, through approval gates a human holds.
+ *
+ * This is the convergence protocol as data: the phases, the order, and the
+ * points where the process stops and waits for a person. It calls
+ * `@medicine-wheel/creative-orientation` on every outcome statement it emits
+ * — including its own questions, which is the part that matters.
+ *
+ * An outcome phrased as elimination inside a multiple-choice option becomes
+ * the human's selected answer, and from then on it looks like a requirement
+ * rather than the agent's bias. Checking at the moment of speaking is the only
+ * point where that is still catchable.
+ *
+ * @packageDocumentation
+ */
+import { type OrientationReading } from '@medicine-wheel/creative-orientation';
+export type Phase = 'explore' | 'clarify' | 'approaches' | 'design' | 'spec' | 'review' | 'plan';
+export declare const PHASE_ORDER: Phase[];
+/** Phases that end with a suspended state holding a question for a human. */
+export declare const GATED_PHASES: ReadonlySet<Phase>;
+export interface Gate {
+    phase: Phase;
+    question: string;
+    /** Set when the human has answered. Absent means the process is suspended here. */
+    answer?: string;
+    askedAt: string;
+    answeredAt?: string;
+}
+export interface Session {
+    id: string;
+    /** The desired result this brainstorm is converging on. */
+    outcome: string;
+    phase: Phase;
+    gates: Gate[];
+    /** Reading taken on the outcome when the session opened. */
+    orientation: OrientationReading;
+    opened: string;
+}
+export interface OpenOptions {
+    id?: string;
+    timestamp?: string;
+    /** A prior state being restored, if this is a repair rather than a creating act. */
+    restores?: string | null;
+    evidence?: string;
+}
+/**
+ * Open a session.
+ *
+ * The outcome is read for orientation immediately. A session opened on an
+ * elimination-shaped outcome will converge rigorously on the wrong thing, and
+ * that is far more expensive to discover at the spec stage.
+ */
+export declare function openSession(outcome: string, options?: OpenOptions): Session;
+export interface EmitCheck {
+    /** The statement as written. */
+    statement: string;
+    reading: OrientationReading;
+    /** True when the statement should be reworded before it reaches a human. */
+    reword: boolean;
+    advice?: string;
+}
+/**
+ * Check any outcome statement before it is spoken — a section heading, an
+ * approach summary, and above all an option label in a question.
+ *
+ * `restores` is threaded through from the session so a repair session is not
+ * scolded for using repair vocabulary. Elimination language is only a finding
+ * when nothing is being restored.
+ */
+export declare function checkEmission(session: Session, statement: string): EmitCheck;
+/** Check a whole set of option labels at once, returning only the ones that need rewording. */
+export declare function checkOptions(session: Session, options: string[]): EmitCheck[];
+/** Suspend the session on a question. The process does not advance until answered. */
+export declare function ask(session: Session, question: string, at?: string): Session;
+export declare function answer(session: Session, question: string, response: string, at?: string): Session;
+/** The gate currently holding the session, if any. */
+export declare function suspendedOn(session: Session): Gate | null;
+/**
+ * Advance to the next phase.
+ *
+ * Refuses while a gate is unanswered. This is the one place refusal is right:
+ * the gate is a question addressed to a person, and answering it on their
+ * behalf is not a shortcut, it is a substitution.
+ */
+export declare function advance(session: Session): Session;
+export declare function isComplete(session: Session): boolean;
+//# 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,MAAM,KAAK,GACb,SAAS,GACT,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,CAAC;AAEX,eAAO,MAAM,WAAW,EAAE,KAAK,EAE9B,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,KAAK,CAE1C,CAAC;AAEH,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,4DAA4D;IAC5D,WAAW,EAAE,kBAAkB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAmB/E;AAED,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,kBAAkB,CAAC;IAC5B,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAY5E;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAE7E;AAID,sFAAsF;AACtF,wBAAgB,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAK5E;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CASjG;AAED,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAEzD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAUjD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEpD"}

package/dist/index.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATED_PHASES = exports.PHASE_ORDER = void 0;
+exports.openSession = openSession;
+exports.checkEmission = checkEmission;
+exports.checkOptions = checkOptions;
+exports.ask = ask;
+exports.answer = answer;
+exports.suspendedOn = suspendedOn;
+exports.advance = advance;
+exports.isComplete = isComplete;
+/**
+ * @medicine-wheel/brainstorming
+ *
+ * Idea into committed design, through approval gates a human holds.
+ *
+ * This is the convergence protocol as data: the phases, the order, and the
+ * points where the process stops and waits for a person. It calls
+ * `@medicine-wheel/creative-orientation` on every outcome statement it emits
+ * — including its own questions, which is the part that matters.
+ *
+ * An outcome phrased as elimination inside a multiple-choice option becomes
+ * the human's selected answer, and from then on it looks like a requirement
+ * rather than the agent's bias. Checking at the moment of speaking is the only
+ * point where that is still catchable.
+ *
+ * @packageDocumentation
+ */
+const creative_orientation_1 = require("@medicine-wheel/creative-orientation");
+exports.PHASE_ORDER = [
+    'explore', 'clarify', 'approaches', 'design', 'spec', 'review', 'plan',
+];
+/** Phases that end with a suspended state holding a question for a human. */
+exports.GATED_PHASES = new Set([
+    'clarify', 'approaches', 'design', 'review',
+]);
+function defaultId() {
+    return `brainstorm:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Open a session.
+ *
+ * The outcome is read for orientation immediately. A session opened on an
+ * elimination-shaped outcome will converge rigorously on the wrong thing, and
+ * that is far more expensive to discover at the spec stage.
+ */
+function openSession(outcome, options = {}) {
+    if (!outcome?.trim()) {
+        throw new Error('A brainstorm needs an outcome — what will exist when this is done?');
+    }
+    const claim = {
+        outcome,
+        restores: options.restores ?? null,
+        evidence: options.evidence,
+    };
+    return {
+        id: options.id ?? defaultId(),
+        outcome,
+        phase: 'explore',
+        gates: [],
+        orientation: (0, creative_orientation_1.readOrientation)(claim),
+        opened: options.timestamp ?? new Date().toISOString(),
+    };
+}
+/**
+ * Check any outcome statement before it is spoken — a section heading, an
+ * approach summary, and above all an option label in a question.
+ *
+ * `restores` is threaded through from the session so a repair session is not
+ * scolded for using repair vocabulary. Elimination language is only a finding
+ * when nothing is being restored.
+ */
+function checkEmission(session, statement) {
+    const reading = (0, creative_orientation_1.readOrientation)({
+        outcome: statement,
+        restores: session.orientation.orientation === 'oscillating' ? 'inherited from session' : null,
+    });
+    const reword = (0, creative_orientation_1.worthSaying)(reading);
+    return {
+        statement,
+        reading,
+        reword,
+        ...(reword ? { advice: reading.advice } : {}),
+    };
+}
+/** Check a whole set of option labels at once, returning only the ones that need rewording. */
+function checkOptions(session, options) {
+    return options.map(o => checkEmission(session, o)).filter(c => c.reword);
+}
+// ─── Gates ────────────────────────────────────────────────────────
+/** Suspend the session on a question. The process does not advance until answered. */
+function ask(session, question, at) {
+    return {
+        ...session,
+        gates: [...session.gates, { phase: session.phase, question, askedAt: at ?? new Date().toISOString() }],
+    };
+}
+function answer(session, question, response, at) {
+    return {
+        ...session,
+        gates: session.gates.map(g => g.question === question && g.answer === undefined
+            ? { ...g, answer: response, answeredAt: at ?? new Date().toISOString() }
+            : g),
+    };
+}
+/** The gate currently holding the session, if any. */
+function suspendedOn(session) {
+    return session.gates.find(g => g.answer === undefined) ?? null;
+}
+/**
+ * Advance to the next phase.
+ *
+ * Refuses while a gate is unanswered. This is the one place refusal is right:
+ * the gate is a question addressed to a person, and answering it on their
+ * behalf is not a shortcut, it is a substitution.
+ */
+function advance(session) {
+    const open = suspendedOn(session);
+    if (open) {
+        throw new Error(`Cannot advance past ${session.phase}: suspended on an unanswered question — "${open.question}"`);
+    }
+    const i = exports.PHASE_ORDER.indexOf(session.phase);
+    if (i === exports.PHASE_ORDER.length - 1)
+        return session;
+    return { ...session, phase: exports.PHASE_ORDER[i + 1] };
+}
+function isComplete(session) {
+    return session.phase === 'plan' && suspendedOn(session) === 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":"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"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@medicine-wheel/brainstorming",
+  "version": "0.5.3",
+  "description": "Idea into committed design through approval gates a human holds, with every emitted outcome statement routed through creative orientation — including its own questions.",
+  "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",
+    "brainstorming",
+    "design",
+    "approval-gates",
+    "creative-orientation"
+  ],
+  "author": "jgwill",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/medicine-wheel.git",
+    "directory": "src/brainstorming"
+  },
+  "dependencies": {
+    "@medicine-wheel/creative-orientation": "^0.5.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}