@harborppm/cli 0.56.0 → 0.57.0

package/dist/app.mjs

@@ -2274,9 +2274,158 @@ var init_premortem = __esmMin((() => {
 }));
 
 //#endregion
-//#region src/lib/voyage-log.ts
+//#region src/lib/charter-lines.ts
+/** Nothing written on any of the five lines. */
+function charterEmpty(charter) {
+	return !charter || CHARTER_FIELDS.every((f) => !clean(charter[f]));
+}
+/**
+* The charter after a change to some of its lines: trimmed, and null once
+* every line is empty so a cleared charter reads as never written.
+*/
+function withCharter(current, patch, by, at) {
+	const next = {
+		...current ?? {},
+		updatedAt: at,
+		updatedById: by
+	};
+	for (const field of CHARTER_FIELDS) {
+		if (!(field in patch)) continue;
+		const text = (patch[field] ?? "").trim();
+		if (text) next[field] = text;
+		else delete next[field];
+	}
+	return charterEmpty(next) ? null : next;
+}
+var CHARTER_FIELDS, clean;
+var init_charter_lines = __esmMin((() => {
+	CHARTER_FIELDS = [
+		"why",
+		"inScope",
+		"outScope",
+		"doneWhen",
+		"callsBy"
+	];
+	clean = (s) => (s ?? "").replace(/\s+/g, " ").trim();
+}));
+
+//#endregion
+//#region src/lib/charter.ts
 init_indexes();
 init_date_fns();
+init_date_text();
+init_premortem();
+init_charter_lines();
+const CHARTER_LABEL = {
+	why: "Why",
+	inScope: "In",
+	outScope: "Out",
+	doneWhen: "Done when",
+	callsBy: "Calls made by"
+};
+/** Each line's name for agents and the CLI's --json: plain words, no "Scope". */
+const CHARTER_KEY = {
+	why: "why",
+	inScope: "in",
+	outScope: "out",
+	doneWhen: "doneWhen",
+	callsBy: "callsBy"
+};
+/** The lines written so far, in order. */
+function charterLines(charter) {
+	if (!charter) return [];
+	return CHARTER_FIELDS.map((field) => ({
+		field,
+		label: CHARTER_LABEL[field],
+		text: clean(charter[field])
+	})).filter((l) => l.text);
+}
+function charterFilled(charter) {
+	return charterLines(charter).length;
+}
+/** A week after the start, an empty charter is worth a nudge. */
+const CHARTER_GRACE_DAYS = 7;
+/**
+* A project whose charter is still blank a week after it started, while
+* it's still running. Done and paused ones are left alone.
+*/
+function charterOverdue(project, today) {
+	if (project.health === "done" || project.health === "paused") return null;
+	if (!charterEmpty(project.charter)) return null;
+	const days = differenceInCalendarDays(parseIso(today), parseIso(project.startDate.slice(0, 10)));
+	return days >= 7 ? days : null;
+}
+/** The items of an In or Out line: split on commas, semicolons, "and" lists and new lines. */
+function charterItems(text) {
+	return (text ?? "").split(/[\n,;•]+/).map((s) => s.replace(/^\s*(?:and|or|-|\*)\s+/i, "").trim()).filter((s) => contentWords(s).size > 0);
+}
+/** True when a task's title names an item: every meaningful word of a short item, or two of a longer one. */
+function names(item, title) {
+	let shared = 0;
+	for (const w of item) if (title.has(w)) shared += 1;
+	return item.size <= 2 ? shared === item.size : shared >= 2;
+}
+/**
+* Tasks whose titles name something the charter put out of scope, newest
+* first: the "I thought that was in" list. Tasks made before the charter
+* was last written are left out when `since` is given, so writing an Out
+* line about work already on the board doesn't flag it.
+*/
+function outOfScope(charter, tasks, opts = {}) {
+	const items = charterItems(charter?.outScope).map((item) => ({
+		item,
+		words: contentWords(item)
+	}));
+	if (items.length === 0) return [];
+	const out = [];
+	for (const task of tasks) {
+		if (opts.since && task.createdAt < opts.since) continue;
+		const title = contentWords(task.title);
+		const hit = items.find((i) => names(i.words, title));
+		if (hit) out.push({
+			task,
+			item: hit.item
+		});
+	}
+	return out.sort((a, b) => b.task.createdAt.localeCompare(a.task.createdAt));
+}
+/** The voyage log's look at the charter: did the In list get done, did the Out list stay out. */
+function charterCheck(charter, tasks) {
+	if (charterEmpty(charter)) return null;
+	const finished = tasks.filter((t) => t.status === "done").map((t) => contentWords(t.title));
+	const delivered = charterItems(charter.inScope).map((item) => {
+		const words = contentWords(item);
+		return {
+			item,
+			done: finished.filter((title) => names(words, title)).length
+		};
+	});
+	return {
+		doneWhen: clean(charter.doneWhen) || null,
+		delivered,
+		crept: outOfScope(charter, tasks),
+		outItems: charterItems(charter.outScope).length
+	};
+}
+/** One sentence for the voyage log's story; null when there's no charter. */
+function charterSentence(check) {
+	if (!check) return null;
+	const bits = [];
+	if (check.delivered.length) {
+		const missing = check.delivered.filter((d) => d.done === 0).map((d) => d.item);
+		bits.push(missing.length === 0 ? "every item the charter put in has finished work against it" : `${check.delivered.length - missing.length} of ${check.delivered.length} items the charter put in have finished work against them (not: ${missing.join(", ")})`);
+	}
+	if (check.crept.length) {
+		const items = [...new Set(check.crept.map((c) => c.item))];
+		bits.push(`${check.crept.length} task${check.crept.length === 1 ? "" : "s"} touched what it put out (${items.join(", ")})`);
+	} else if (check.outItems > 0) bits.push("nothing it put out crept in");
+	if (!bits.length) return null;
+	return `Against the charter: ${bits.join("; ")}.`;
+}
+
+//#endregion
+//#region src/lib/voyage-log.ts
+init_date_fns();
 init_blockers();
 init_date_text();
 init_premortem();
@@ -2342,6 +2491,7 @@ function voyageLog(data, projectId) {
 		slips,
 		risks,
 		issues: issues.length,
+		charter: charterCheck(project.charter, tasks),
 		decisions,
 		carriers,
 		budget: project.budget,
@@ -2390,6 +2540,8 @@ function voyageStory(log) {
 		out.push(s.waitedOn ? `${late}; it waited on “${s.waitedOn.title}”, done ${md$2(s.waitedOn.completedAt)}.` : `${late}.`);
 	}
 	for (const r of log.risks.filter((x) => x.happened)) out.push(`The risk “${r.risk.title}” came true${r.guessed ? " (an issue names it)" : ""}.`);
+	const against = charterSentence(log.charter);
+	if (against) out.push(against);
 	if (log.decisions.length) {
 		const changed = log.decisions.filter((d) => d.status === "superseded").length;
 		out.push(`${plural$4(log.decisions.length, "decision was", "decisions were")} written down${changed ? `; ${changed === 1 ? "one was" : `${changed} were`} changed later` : ""}.`);
@@ -5026,6 +5178,29 @@ function premortemNote(data, project, now, today) {
 	const pending = answersOf(data.reflections, project.id).filter(isPending).length;
 	return pending ? `pre-mortem: ${pending} to sort · P` : "pre-mortem · P";
 }
+/**
+* The charter in a few words for the project's header: how many of its five
+* lines are written and any open task that names what it leaves out, or a
+* nudge (warned once it's a week overdue). Null on a finished project with none.
+*/
+function charterNote(project, tasks, today) {
+	const filled = charterFilled(project.charter);
+	if (filled === 0) {
+		if (project.health === "done") return null;
+		return {
+			text: "no charter yet · e writes it",
+			warn: charterOverdue(project, today) !== null
+		};
+	}
+	const creep = outOfScope(project.charter, tasksOf(tasks, project.id).filter((t) => t.status !== "done")).length;
+	return creep ? {
+		text: `charter: ${creep} task${creep === 1 ? "" : "s"} look out of scope · e`,
+		warn: true
+	} : {
+		text: `charter ${filled} of 5 · e`,
+		warn: false
+	};
+}
 const ROLE_LABEL = {
 	owner: "Owner",
 	member: "Can edit",
@@ -7416,6 +7591,24 @@ function reviewPrograms(data, opts = {}) {
 	const { ownerId, portfolioId } = opts;
 	return data.programs.filter((p) => (!portfolioId || p.portfolioId === portfolioId) && (!ownerId || programTouches(p, data, ownerId))).sort((a, b) => rankHealth(a.health) - rankHealth(b.health) || a.endDate.localeCompare(b.endDate));
 }
+/**
+* The projects in these programs whose charter is still blank a week after
+* they started (src/lib/charter.ts), longest-running first: the review's
+* nudge to write the five lines.
+*/
+function blankCharters(data, programs, today) {
+	const ids = new Set(programs.filter((p) => p.health !== "done").map((p) => p.id));
+	const out = [];
+	for (const project of data.projects) {
+		if (!ids.has(project.programId)) continue;
+		const days = charterOverdue(project, today);
+		if (days !== null) out.push({
+			project,
+			days
+		});
+	}
+	return out.sort((a, b) => b.days - a.days || a.project.name.localeCompare(b.project.name));
+}
 
 //#endregion
 //#region src/tui/moves.ts
@@ -10070,7 +10263,17 @@ function ProjectPanel({ id, width, height, go, active, onClose }) {
 				initial: project.description,
 				onSave: (v) => up({ description: v })
 			}
-		}
+		},
+		...CHARTER_FIELDS.map((f) => ({
+			label: `Charter: ${CHARTER_LABEL[f].toLowerCase()}`,
+			value: project.charter?.[f]?.replace(/\s+/g, " ") || "Not written",
+			color: project.charter?.[f] ? void 0 : theme.muted,
+			edit: {
+				kind: "text",
+				initial: project.charter?.[f] ?? "",
+				onSave: (v) => store.getState().setCharter(id, { [f]: v })
+			}
+		}))
 	];
 	return /* @__PURE__ */ jsx(DetailPanel, {
 		title: /* @__PURE__ */ jsx(Text, {
@@ -10708,6 +10911,8 @@ function ProjectsView({ active, width, height, go }) {
 		}
 	});
 }
+/** Projects a week in without a charter, in a few words; null for none. */
+const charterGap = (n) => n ? `${n} blank charter${n === 1 ? "" : "s"}` : null;
 /**
 * The review, as on the website: programs worst first, then by end date,
 * each with its lead, how much is late, where it sits on the priority matrix
@@ -10773,7 +10978,8 @@ function ProgramsView({ active, width, height, go }) {
 					late ? `${late} late` : null,
 					slip >= 100 ? `slipping costs ${dollars$1(slip)}` : null,
 					isRated(program) ? quadrantOf(program, maxBudget, rules) : null,
-					program.nextMove ? `next: ${program.nextMove}` : "no next move"
+					program.nextMove ? `next: ${program.nextMove}` : "no next move",
+					charterGap(blankCharters({ projects }, [program], day).length)
 				].filter(Boolean).join(" · ")
 			};
 		});
@@ -18297,6 +18503,24 @@ function decisionOut(data, r, people) {
 	};
 }
 const tool = (t) => t;
+/** A project's charter, as get_project gives it: the lines written, and open tasks that name what it leaves out. */
+function charterOf(p, tasks) {
+	const lines = charterLines(p.charter);
+	if (lines.length === 0) return { charter: null };
+	const creep = outOfScope(p.charter, tasks.filter((t) => t.status !== "done")).slice(0, 10);
+	return {
+		charter: {
+			...Object.fromEntries(lines.map((l) => [CHARTER_KEY[l.field], l.text])),
+			...p.charter?.updatedAt ? { updated: dayOf(p.charter.updatedAt) } : {}
+		},
+		...creep.length ? { outOfScope: creep.map((c) => ({
+			task: taskKey(c.task, p) ?? c.task.id,
+			title: c.task.title,
+			names: c.item,
+			added: dayOf(c.task.createdAt)
+		})) } : {}
+	};
+}
 /** A project's notes for later, as get_project gives them: sealed ones without their text unless they're the caller's. */
 function notesOf(ctx, p) {
 	const notes = bottlesOf(ctx.data.reflections, p.id);
@@ -18466,7 +18690,7 @@ const HARBOR_TOOLS = [
 	tool({
 		name: "get_project",
 		title: "Project details",
-		description: "One project: health and why, dates, budget, task counts, late tasks, what it waits on, milestones and open risks, when it will likely finish at the crew's recent pace (finish: shortHistory when there's under two weeks of it; lastDue names the open task whose due date the dates wait for, when the pace alone would finish sooner), notes the crew left for later (notesForLater: a sealed one shows only who left it and what opens it, unless it's the person's own), and its url on the website." + DATA_NOTE,
+		description: "One project: health and why, dates, budget, task counts, late tasks, what it waits on, milestones and open risks, when it will likely finish at the crew's recent pace (finish: shortHistory when there's under two weeks of it; lastDue names the open task whose due date the dates wait for, when the pace alone would finish sooner), notes the crew left for later (notesForLater: a sealed one shows only who left it and what opens it, unless it's the person's own), its charter (why, in, out, doneWhen, callsBy; null until someone writes one, and outOfScope lists open tasks whose titles name something it leaves out), and its url on the website." + DATA_NOTE,
 		input: object({
 			harbor: harborArg,
 			project: string().min(1).max(200).describe("Project id or name.")
@@ -18526,6 +18750,7 @@ const HARBOR_TOOLS = [
 				milestones,
 				openRaid: raid,
 				finish: finishForecast(p, tasks, ctx.now, spendEntriesOf(data, p.id), data.reflections),
+				...charterOf(p, tasks),
 				...notesOf(ctx, p),
 				...hillOf(p, today),
 				...webLink(ctx, { project: p.id })
@@ -18844,7 +19069,7 @@ const HARBOR_TOOLS = [
 	tool({
 		name: "program_review",
 		title: "The review",
-		description: "The website's Review: programs worst health first, then soonest end, each with its lead, end date, health (and the note when set by hand), late tasks, where it sits on the priority matrix and its next move. Done programs only with includeDone." + DATA_NOTE,
+		description: "The website's Review: programs worst health first, then soonest end, each with its lead, end date, health (and the note when set by hand), late tasks, where it sits on the priority matrix and its next move. Done programs only with includeDone. blankCharters lists running projects in them whose charter is still empty a week after they started (set_charter writes one)." + DATA_NOTE,
 		input: object({
 			harbor: harborArg,
 			owner: string().max(200).optional().describe("\"me\", or a person's id or name: programs they lead, lead a project in or hold a task in."),
@@ -18881,6 +19106,11 @@ const HARBOR_TOOLS = [
 					nextMove: p.nextMove?.trim() || null
 				})),
 				done: all.length - listed.length,
+				blankCharters: blankCharters(data, listed, todayISO(ctx.now)).map((b) => ({
+					project: b.project.name,
+					program: data.programs.find((x) => x.id === b.project.programId)?.name ?? null,
+					startedDaysAgo: b.days
+				})),
 				onlyOneKnows: lifeboats(data, ctx.now, { programIds: new Set(listed.map((p) => p.id)) }).slice(0, 25).map((l) => lifeboatOut(data, l, people))
 			};
 		}
@@ -18964,6 +19194,17 @@ const HARBOR_TOOLS = [
 					cameTrue: r.happened,
 					...r.guessed ? { guessed: true } : {}
 				})),
+				...log.charter ? { charter: {
+					doneWhen: log.charter.doneWhen,
+					inItems: log.charter.delivered.map((d) => ({
+						item: d.item,
+						finishedTasks: d.done
+					})),
+					outOfScopeTasks: log.charter.crept.map((c) => ({
+						title: c.task.title,
+						names: c.item
+					}))
+				} } : {},
 				decisions: log.decisions.map((d) => ({
 					title: d.title,
 					on: dayOf(d.decidedAt),
@@ -20226,6 +20467,13 @@ function hierarchySlice({ get, write }) {
 				hillMovedAt: stamp()
 			} : p) });
 		},
+		setCharter: (projectId, patch) => {
+			const by = get().currentUserId;
+			write({ projects: get().projects.map((p) => p.id === projectId ? {
+				...p,
+				charter: withCharter(p.charter, patch, by, stamp())
+			} : p) });
+		},
 		addCustomField: (projectId, def) => {
 			const id = uid("cf");
 			write({ projects: get().projects.map((p) => p.id === projectId ? {
@@ -20502,6 +20750,7 @@ var init_hierarchy = __esmMin((() => {
 	init_derived_health();
 	init_shared();
 	init_hill();
+	init_charter_lines();
 	init_sample_project();
 	init_format();
 	init_empty();
@@ -25611,6 +25860,7 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 		reflections,
 		raidItems
 	}, project, clockNow(), day);
+	const charter = charterNote(project, tasks, day);
 	const opened = freshlyOpened({
 		reflections,
 		milestones
@@ -25699,6 +25949,10 @@ function ProjectView({ projectId, active, width, height, go, onBack }) {
 					pmNote ? /* @__PURE__ */ jsxs(Text, {
 						color: theme.muted,
 						children: [" · ", pmNote]
+					}) : null,
+					charter ? /* @__PURE__ */ jsxs(Text, {
+						color: charter.warn ? theme.warn : theme.muted,
+						children: [" · ", charter.text]
 					}) : null
 				]
 			}),

package/lib/cli.mjs

@@ -33,6 +33,7 @@ import {
   myWork,
   premortemText,
   notesText,
+  charterText,
   daysText,
   soundingText,
   lifeboatsText,
@@ -205,6 +206,10 @@ export const HELP = `harbor: Harbor from the terminal
                                               answer or read it
   harbor voyage PROJECT ["YOUR LINE"]         a Done project's voyage log, and
                                               your line in it
+  harbor charter PROJECT [--why T] [--in T] [--out T] [--done-when T]
+                         [--calls T]
+                                              a project's five-line charter:
+                                              read it, or write some lines
   harbor note PROJECT ["NOTE"] [--opens DATE|--milestone NAME|--off-track]
                                               a note for later: sealed until
                                               its day, milestone, or Off track
@@ -423,6 +428,10 @@ const FLAG = {
   text: "the next move",
   waitsOn: "--waits-on",
   repeat: "--repeat",
+  in: "--in",
+  out: "--out",
+  doneWhen: "--done-when",
+  callsBy: "--calls",
   description: "--notes",
   body: "the comment",
   column: "the column",
@@ -701,6 +710,18 @@ const DETAIL = {
     "  --no-people. A task already in its project is left alone: by its key",
     "  (a Key column, as harbor export writes) or by title.",
   ],
+  charter: [
+    "  harbor charter PROJECT                 reads its charter, and any open task",
+    "                                         that names something it leaves out",
+    '  harbor charter PROJECT --why "TEXT"    writes: that line; give any of',
+    "                                         --why, --in, --out, --done-when and",
+    "                                         --calls at once",
+    "",
+    "  none clears a line: --out none. Separate items in --in and --out",
+    "  with commas, so Harbor can spot a task that names one. The review lists",
+    "  running projects still without a charter a week after they started.",
+    "  PROJECT is a name, a key like RR, or an id.",
+  ],
   sound: [
     "  harbor sound TASK                      reads its sounding: who hasn't answered,",
     "                                         and the spread once everyone has",
@@ -2083,7 +2104,13 @@ export async function run(argv, io = {}) {
             words && r.programs.length === 0
               ? `No program in the review matches "${words}".`
               : reviewList(r),
-          (r) => (words ? { ...r, programs: r.programs.filter((p) => nameHas(p.name, words)) } : r),
+          (r) => {
+            if (!words) return r;
+            const programs = r.programs.filter((p) => nameHas(p.name, words));
+            const names = new Set(programs.map((p) => p.name));
+            const blankCharters = (r.blankCharters ?? []).filter((b) => names.has(b.program));
+            return { ...r, programs, blankCharters };
+          },
         );
       }
       const status = { start: "doing", submit: "review", done: "done" }[command];
@@ -2405,6 +2432,44 @@ export async function run(argv, io = {}) {
         (r) => `Sealed your note on ${r.sealed.project}. It ${r.sealed.opens}.`,
       );
     }
+    case "charter": {
+      const { positionals, values, harbor } = parse(
+        spec([], ["why", "in", "out", "done-when", "calls"]),
+      );
+      const project = one(positionals, 'project: harbor charter "NAME"');
+      // none clears a line, as --due none does.
+      const line = (v) => (v.trim().toLowerCase() === "none" ? "" : v);
+      const lines = Object.fromEntries(
+        [
+          ["why", values.why],
+          ["in", values.in],
+          ["out", values.out],
+          ["doneWhen", values["done-when"]],
+          ["callsBy", values.calls],
+        ]
+          .filter(([, v]) => v !== undefined)
+          .map(([k, v]) => [k, line(v)]),
+      );
+      if (Object.keys(lines).length === 0) {
+        // --json: the project's charter (null until written) and any out-of-scope tasks.
+        return call(
+          "get_project",
+          { harbor, project },
+          (r) => charterText(r),
+          (r) => ({
+            id: r.id,
+            project: r.name,
+            charter: r.charter ?? null,
+            ...(r.outOfScope ? { outOfScope: r.outOfScope } : {}),
+          }),
+        );
+      }
+      return call("set_charter", { harbor, project, ...lines }, (r) =>
+        r.charter
+          ? `Saved ${r.project}'s charter.\n\n${charterText({ project: r.project, charter: r.charter })}`
+          : `Cleared ${r.project}'s charter.`,
+      );
+    }
     case "sound": {
       const { positionals, values, harbor } = parse(spec([], ["why", "ask", "settle"]));
       const [task, days, ...extra] = positionals;

package/lib/format.mjs

@@ -344,6 +344,14 @@ export function reviewList(r) {
     out.push(`${p.name}  (${bits.join(" · ")})`);
     out.push(`  ${p.nextMove ? `next: ${p.nextMove}` : "no next move yet"}`);
   }
+  const blank = r.blankCharters ?? [];
+  if (blank.length) {
+    out.push("", "Charters still blank a week in:");
+    for (const b of blank.slice(0, 8))
+      out.push(`  ${b.project}  (started ${b.startedDaysAgo} days ago)`);
+    if (blank.length > 8) out.push(`  and ${blank.length - 8} more`);
+    out.push('  harbor charter "PROJECT" --why "…" writes one.');
+  }
   return out.join("\n") + more;
 }
 
@@ -650,6 +658,36 @@ export function importText(r) {
 }
 
 /** A project's notes for later, as get_project lists them. */
+const CHARTER_LINES = [
+  ["why", "Why"],
+  ["in", "In"],
+  ["out", "Out"],
+  ["doneWhen", "Done when"],
+  ["callsBy", "Calls made by"],
+];
+
+/** A project's charter as get_project or set_charter gives it, with open tasks that name what it leaves out. */
+export function charterText(r) {
+  const project = r.name ?? r.project;
+  if (!r.charter) {
+    return `${project} has no charter yet. Write one, a line at a time:\n  harbor charter "${project}" --why "…" --in "…, …" --out "…, …" --done-when "…" --calls "…"`;
+  }
+  const lines = [`Charter · ${project}`];
+  const width = Math.max(...CHARTER_LINES.map(([, label]) => label.length));
+  for (const [key, label] of CHARTER_LINES) {
+    if (r.charter[key]) lines.push(`  ${label.padEnd(width)}  ${r.charter[key]}`);
+  }
+  if (r.outOfScope?.length) {
+    lines.push("", "Out of scope?");
+    for (const t of r.outOfScope) {
+      lines.push(
+        `  ${t.task}  ${t.title}  (added ${t.added}; the charter leaves out "${t.names}")`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
 export function notesText(project, notes) {
   if (!notes?.length)
     return `No notes for later on ${project}. Leave one: harbor note "${project}" "NOTE" --opens +30`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborppm/cli",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Harbor from the terminal: a full-screen app with everything, plus commands for scripts and agents.",
   "keywords": [
     "harbor",