marketing-mindset 1.5.0 → 1.6.0

package/README.md

@@ -75,3 +75,10 @@ npx -y marketing-mindset@1.5.0 budget --base 0.03 --lift 0.2 --cpl 4 --daily 500
 ```
 
 The money side of the same floor `sample` computes: contacts needed in both arms, cost per arm and cost to read the test at your cost per contact, days to the floor at a given daily volume, and the spend guard (below the floor the difference is noise, not a result). `--json` for agents. Work with me: https://axelfreeman.com/marketing-engineer.html
+### Dated plan: `plan`
+
+```
+npx -y marketing-mindset@1.6.0 plan --base 0.03 --lift 0.2 --daily 500 --weeks 4
+```
+
+The floor from `sample`/`budget` laid out on a calendar: contacts per week, cumulative volume against the floor, the first date the test can honestly be read, the mechanics-only first week, and an honest verdict when the volume cannot reach the floor inside the plan. `--json` for agents. Work with me: https://axelfreeman.com/marketing-engineer.html

package/bin/cli.js

@@ -290,6 +290,96 @@ function runBudget(opts) {
   return 0;
 }
 
+
+/* plan — the same floor as `sample`/`budget`, laid out on a calendar: weekly volume, the date the
+ * test can first be read, the mechanics-only week, and an honest verdict when it does not fit. */
+function runPlan(opts) {
+  const base = Number(opts.base === undefined ? 0 : opts.base);
+  const lift = Number(opts.lift === undefined ? 0 : opts.lift);
+  if (!isFinite(base) || base <= 0 || base >= 1) {
+    console.error("plan: --base must be a rate between 0 and 1 (got: " + JSON.stringify(opts.base) + ")");
+    return 1;
+  }
+  if (!isFinite(lift) || lift <= 0) {
+    console.error("plan: --lift must be a positive relative lift, e.g. 0.2 for +20%");
+    return 1;
+  }
+  const daily = Number(opts.daily === undefined ? 0 : opts.daily);
+  if (!isFinite(daily) || daily <= 0) {
+    console.error("plan: --daily must be a positive number of contacts per day (got: " + JSON.stringify(opts.daily) + ")");
+    return 1;
+  }
+  const weeks = opts.weeks === undefined ? 4 : Number(opts.weeks);
+  if (!isFinite(weeks) || weeks < 1 || weeks > 52 || Math.floor(weeks) !== weeks) {
+    console.error("plan: --weeks must be a whole number between 1 and 52");
+    return 1;
+  }
+  const power = opts.power === undefined ? 0.8 : opts.power;
+  const alpha = opts.alpha === undefined ? 0.05 : opts.alpha;
+  const start = typeof opts.start === "string" && /^\d{4}-\d{2}-\d{2}$/.test(opts.start)
+    ? opts.start : new Date().toISOString().slice(0, 10);
+  const t0 = Date.parse(start + "T00:00:00Z");
+  const day = (n) => new Date(t0 + n * 86400000).toISOString().slice(0, 10);
+
+  const perArm = sampleSize(base, lift, power, alpha);
+  const need = perArm * 2;
+  const daysToRead = Math.ceil(need / daily);
+  const weekRows = [];
+  for (let w = 1; w <= weeks; w++) {
+    const confirmed = Math.min(daily * 7 * w, need);
+    weekRows.push({
+      week: w,
+      start: day((w - 1) * 7),
+      end: day(w * 7 - 1),
+      planned_contacts: daily * 7,
+      cumulative: daily * 7 * w,
+      against_floor_pct: Math.round(Math.min(100, (daily * 7 * w / need) * 1000) / 10)
+    });
+  }
+  const capacity = daily * 7 * weeks;
+  const readable = capacity >= need;
+  const p2 = base * (1 + lift);
+  const out = {
+    start_date: start,
+    base_rate: base, target_rate: Math.round(p2 * 10000) / 10000, relative_lift: lift,
+    power: power, alpha: alpha,
+    per_arm: perArm, contacts_needed: need, daily_contacts: daily, weeks_planned: weeks,
+    weekly_volume: daily * 7, planned_capacity: capacity,
+    capacity_vs_floor_pct: Math.round((capacity / need) * 1000) / 10,
+    days_to_read: daysToRead,
+    read_date: day(daysToRead - 1),
+    readable_within_plan: readable,
+    plan: weekRows,
+    gates: [
+      "Week 1 is mechanics only: delivery, bounces, replies per 100 sent. Do not read a conversion rate.",
+      "First honest read: " + day(daysToRead - 1) + " - before that date a difference between variants is noise.",
+      "Every week: if the delivered volume is under half of the planned volume, fix the channel first; the test is not running."
+    ],
+    kill_rule: "What result ends the test and what result doubles it is decided before the first send, in writing.",
+    verdict: readable
+      ? "Readable in " + weeks + " week(s): the floor lands on " + day(daysToRead - 1) + " at " + daily + " contacts/day."
+      : "Not readable in " + weeks + " week(s): " + capacity + " contacts planned against a floor of " + need +
+        ". At " + daily + " contacts/day it needs " + daysToRead + " days - extend the plan, raise the volume, or change the offer.",
+    method: "two-proportion sample size; same formula as `marketing-mindset sample`"
+  };
+  if (opts.json) {
+    console.log(JSON.stringify(out, null, 2));
+    return 0;
+  }
+  console.log("Plan from " + out.start_date + ": base " + (base * 100).toFixed(2) + "% -> " +
+    (p2 * 100).toFixed(2) + "% (lift " + lift + "), " + daily + " contacts/day, " + weeks + " week(s)");
+  console.log("Floor: " + perArm + " per arm, " + need + " contacts in total. Weekly volume: " + daily * 7 + ".");
+  weekRows.forEach((w) => {
+    console.log("  Week " + w + " (" + w.start + " .. " + w.end + "): " + w.planned_contacts +
+      " contacts, cumulative " + w.cumulative + " (" + w.against_floor_pct + "% of the floor)");
+  });
+  console.log("First honest read: " + out.read_date + " (day " + daysToRead + ").");
+  console.log(out.verdict);
+  out.gates.forEach((g) => console.log("  gate: " + g));
+  console.log("Packages and the walkthrough: https://axelfreeman.com/marketing-engineer.html");
+  return 0;
+}
+
 const cmd = (process.argv[2] || "").toLowerCase();
 const rest = process.argv.slice(3);
 
@@ -324,6 +414,8 @@ if (cmd === "sample") {
   }, null, 2));
 } else if (cmd === "aeo") {
   process.exit(runAeo(flags(rest)));
+} else if (cmd === "plan") {
+  process.exit(runPlan(flags(rest)));
 } else if (cmd === "budget") {
   process.exit(runBudget(flags(rest)));
 } else if (cmd === "warmup") {
@@ -354,6 +446,10 @@ Usage:
       --base 0.03 --n 1500 --lift 0.2
   npx marketing-mindset budget          what an honest test costs before you can read it
       --base 0.03 --lift 0.2 --cpl 4 [--daily 500]
+  npx marketing-mindset plan            dated plan: weekly volume, gates, first honest read
+      --base 0.03 --lift 0.2 --daily 500 [--weeks 4] [--start 2026-09-21]
+  npx marketing-mindset plan            dated plan: weekly volume, gates, first honest read
+      --base 0.03 --lift 0.2 --daily 500 [--weeks 4] [--start 2026-09-21]
   npx marketing-mindset warmup          day-by-day sending ramp with stop rules
       --start 2026-09-21 --target 200 --days 21 --mailboxes 4
   npx marketing-mindset jd              marketing engineer job description

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marketing-mindset",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "A marketer's operating mindset as an installable agent skill and CLI: test-size floors, kill rules, agent-readiness checklist, marketing-engineer job description. npx marketing-mindset sample|kill|budget|warmup|aeo|jd|sections|read|install.",
   "keywords": [
     "agent-skill",