@coppica/persuasion-mcp 1.0.1

package/dist/scorers/flow-framework.d.ts

@@ -0,0 +1,69 @@
+/**
+ * FLOW & CADENCE FRAMEWORK — Phase 1 of the writing-tools strategy.
+ *
+ * The hook framework scores individual openers. The flow framework scores
+ * everything else: paragraphs, body sections, ad scripts, email bodies. It
+ * is the post-generation statistical detector that catches the "AI smell"
+ * patterns no prompt instruction can reliably suppress, in particular the
+ * "Five bots. Ten principles. That's not X, it's Y." rhythm tic.
+ *
+ * Three layers, called in order. Each layer cheaper than the next.
+ *
+ *   Layer 1 — SURFACE: regex/lexicon. Banned words, em-dash density,
+ *             negative-parallelism cap, triad ratio. Always fires.
+ *   Layer 2 — CADENCE: statistical. Sentence-length burstiness, paragraph
+ *             variance, rhythmic contrast, opening uniformity. Skipped on
+ *             non-prose contexts (bullets, headers, ad copy, subject lines)
+ *             where uniformity is by design.
+ *   Layer 3 — FLOW: discourse-aware approximations (no POS tagger). Bucket-
+ *             brigade density, threading ratio, closing-recap detection.
+ *             Same context gating as Layer 2.
+ *
+ * Pure module — no I/O, no DB. The evaluate_flow tool wraps this and
+ * persists the result. Reuses AI-smell lexicon from hook-framework.ts so
+ * the banned-word list has a single source of truth.
+ */
+export type FlowContext = 'hero' | 'body' | 'long_form' | 'email' | 'ad' | 'bullets' | 'header' | 'subject' | 'tldr';
+interface FlowGateResult {
+    name: string;
+    layer: 'surface' | 'cadence' | 'flow';
+    status: 'pass' | 'warn' | 'fail';
+    detail?: string;
+}
+interface FlowViolation {
+    pattern: string;
+    span: string;
+    reason: string;
+}
+export interface FlowScore {
+    score: number;
+    scoreLabel: 'fail' | 'weak' | 'passable' | 'strong' | 'excellent';
+    gates: FlowGateResult[];
+    violations: FlowViolation[];
+    suggestions: string[];
+    metadata: {
+        /** Counts for the ORIGINAL input. Always reflect what the bot passed in,
+         *  not what was actually scored. When `sampled` is true, the scoring
+         *  numbers came from the windows below — these stats describe the whole. */
+        wordCount: number;
+        sentenceCount: number;
+        paragraphCount: number;
+        /** True when input exceeded MAX_FULL_WORDS and was sampled. */
+        sampled: boolean;
+        /** When sampled: number of paragraphs/windows that were actually scored. */
+        sampledWindowCount?: number;
+        /** When sampled: word count of the scored subset (so the user can see
+         *  how representative the sample is). */
+        sampledWordCount?: number;
+        contextGated: ('cadence' | 'flow')[];
+    };
+}
+export interface ScoreFlowOptions {
+    context?: FlowContext;
+    /** Bot opts in to deliberate negative parallelism (Copy Autopsy diagnosing,
+     *  The Closer / Modern Masters teaching, White Stag character voice). */
+    allowAntithesis?: boolean;
+}
+export declare function splitSentences(text: string): string[];
+export declare function scoreFlow(rawText: string, options?: ScoreFlowOptions): FlowScore;
+export {};