@broject/retro 0.0.0 → 0.2.3

package/README.md

@@ -1,3 +1,32 @@
 # @broject/retro
 
-Placeholder for @broject/retro published by @nx-devkit/prepare-for-release.
+The retrospect engine behind `bro retrospect` — parses TOML retro plans
+(a root cause + prevention actions) and fans each action out to its sink:
+beads, skills, rules, or docs. Powers `bro wtf`.
+
+> You probably want the CLI instead: `bro wtf "it happened again"`.
+> Install this only when wiring self-correction into your own loop.
+
+## Install
+
+```bash
+npm i @broject/retro
+```
+
+Requires Node ≥ 22 and `bd`. ESM only.
+
+## Surface
+
+- `parsePlan` / `parsePlanDoc` / `PLAN_SCHEMA` — retro plan parsing +
+  validation
+- `ACTION_SINKS` — where prevention actions land: `backlog`, `memory`,
+  `agentic-documents`, `upstream-issue`, `workaround`
+- `RETRO_SCOPES` — action visibility: `universal`, `project`, `user`,
+  `agent`, `session`
+- Re-exports `bd` primitives from `@broject/core`
+
+## Links
+
+- Docs: https://broject.dev/docs/commands/retrospect
+- Source: https://github.com/ThePlenkov/bro/tree/main/packages/retro
+- CLI: https://www.npmjs.com/package/@broject/bro

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { bd, bdJson, checkBeads, refKind } from "@broject/core";
+
+//#region src/types.d.ts
+interface BeadRow {
+  id: string;
+  title: string;
+  status: string;
+  labels?: string[];
+  updated_at?: string;
+}
+/** Scope decides where a finding must be persisted to actually prevent
+ * recurrence — mirrors the retrospect skill's scope table. */
+declare const RETRO_SCOPES: readonly ["universal", "project", "user", "agent", "session"];
+type RetroScope = (typeof RETRO_SCOPES)[number];
+/** Where a follow-up action lands. Every action becomes a prevention bead;
+ * the sink label tells the executor which resource to write to. */
+declare const ACTION_SINKS: readonly ["backlog", "memory", "agentic-documents", "upstream-issue", "workaround"];
+type ActionSink = (typeof ACTION_SINKS)[number];
+interface RetroAction {
+  title: string;
+  sink: ActionSink;
+  scope?: RetroScope;
+  detail?: string;
+}
+interface RetroPlan {
+  what: string;
+  why: string;
+  scope: RetroScope;
+  /** Open wtf bead this retro answers — closed on record. */
+  wtf?: string;
+  evidence: string[];
+  actions: RetroAction[];
+}
+interface RecordResult {
+  retroId: string;
+  actionIds: string[];
+  closedWtf?: string;
+}
+//#endregion
+//#region src/plan.d.ts
+/** The `kind` value a retro plan must carry when it has one — lets
+ * `bro run <file>` route the plan to this plugin. */
+declare const PLAN_KIND = "retrospect";
+/** Validate an already-parsed plan document — the plugin planSchema.
+ *  Throws one error listing every problem — the agent fixes the file
+ *  once instead of iterating on single failures. */
+declare function parsePlanDoc(doc: unknown, source?: string): RetroPlan;
+/** Parse + validate a plan file's TOML text. */
+declare function parsePlan(text: string, source?: string): RetroPlan;
+/** The commented template `bro retrospect schema` prints — keeps the schema
+ * out of skill files so the CLI stays the single source of truth. */
+declare const PLAN_SCHEMA = "# retrospection plan \u2014 written by the agent, executed by `bro retrospect record`\n# or routed by kind via `bro run retro.toml`\n#\n#   bro retrospect record retro.toml\n\nkind = \"retrospect\"  # plan envelope \u2014 `bro run` routes on it\n\n[retro]\nwhat = \"\"            # required \u2014 what went wrong, one line\nwhy = \"\"             # required \u2014 root cause, not the symptom\nscope = \"project\"    # universal | project | user | agent | session\nwtf = \"\"             # optional \u2014 open wtf bead this retro answers (closed on record)\nevidence = []        # optional \u2014 shas, PR urls, bead ids \u2192 bd provenance\n\n# Every action becomes a 'prevention' bead linked discovered-from the retro.\n# sink decides where the executor lands it:\n#   backlog            tracked follow-up work\n#   memory             persist to user or project memory (scope decides)\n#   agentic-documents  AGENTS.md / rules / skill update\n#   upstream-issue     file an issue in the external repo\n#   workaround         code-level fix or guardrail to implement now\n#\n# recurrence: a root cause that recurred despite a prose rule needs >=1\n# workaround|backlog action \u2014 wider prose is more of what already failed\n#\n# [[actions]]\n# title = \"\"\n# sink = \"backlog\"\n# scope = \"project\"    # optional \u2014 overrides retro.scope for this action\n# detail = \"\"          # optional \u2014 body of the follow-up bead\n";
+//#endregion
+//#region src/retro.d.ts
+declare function listWtf(): BeadRow[];
+declare function openWtf(): BeadRow[];
+declare function listRetros(): BeadRow[];
+declare function openPreventions(): BeadRow[];
+/**
+ * Capture a wtf moment: the user's complaint verbatim + a context snapshot.
+ * The quote is evidence — never paraphrased.
+ */
+declare function captureWtf(complaint: string): BeadRow;
+/**
+ * Record a validated plan: the retro bead carries the analysis memo and is
+ * closed immediately — it is a record, not work. Each action lands as an
+ * open prevention bead the executor routes by its `sink:` label.
+ */
+declare function recordRetro(plan: RetroPlan): RecordResult;
+//#endregion
+export { ACTION_SINKS, type ActionSink, type BeadRow, PLAN_KIND, PLAN_SCHEMA, RETRO_SCOPES, type RecordResult, type RetroAction, type RetroPlan, type RetroScope, bd, bdJson, captureWtf, checkBeads, listRetros, listWtf, openPreventions, openWtf, parsePlan, parsePlanDoc, recordRetro, refKind };

package/dist/index.js

@@ -0,0 +1,323 @@
+import { bd, bd as bd$1, bdJson, checkBeads, evidenceKind, refKind, refKind as refKind$1, taskStore } from "@broject/core";
+import { parse } from "smol-toml";
+import { execFileSync } from "node:child_process";
+
+//#region src/types.ts
+/** Scope decides where a finding must be persisted to actually prevent
+* recurrence — mirrors the retrospect skill's scope table. */
+const RETRO_SCOPES = [
+	"universal",
+	"project",
+	"user",
+	"agent",
+	"session"
+];
+/** Where a follow-up action lands. Every action becomes a prevention bead;
+* the sink label tells the executor which resource to write to. */
+const ACTION_SINKS = [
+	"backlog",
+	"memory",
+	"agentic-documents",
+	"upstream-issue",
+	"workaround"
+];
+
+//#endregion
+//#region src/plan.ts
+const RETRO_KEYS = new Set([
+	"what",
+	"why",
+	"scope",
+	"wtf",
+	"evidence"
+]);
+const ACTION_KEYS = new Set([
+	"title",
+	"sink",
+	"scope",
+	"detail"
+]);
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+function scope(raw, where, errors) {
+	if (raw === void 0) return;
+	if (typeof raw !== "string" || !RETRO_SCOPES.includes(raw)) {
+		errors.push(`${where}: scope must be one of ${RETRO_SCOPES.join("|")}`);
+		return;
+	}
+	return raw;
+}
+function parseAction(raw, i, errors) {
+	const where = `actions[${i}]`;
+	if (!isRecord(raw)) {
+		errors.push(`${where}: must be a table`);
+		return;
+	}
+	for (const key of Object.keys(raw)) if (!ACTION_KEYS.has(key)) errors.push(`${where}: unknown key "${key}"`);
+	if (!nonEmpty(raw.title)) errors.push(`${where}: title is required`);
+	if (!nonEmpty(raw.sink) || !ACTION_SINKS.includes(raw.sink)) errors.push(`${where}: sink must be one of ${ACTION_SINKS.join("|")}`);
+	if (raw.detail !== void 0 && typeof raw.detail !== "string") errors.push(`${where}: detail must be a string`);
+	const actionScope = scope(raw.scope, where, errors);
+	if (!nonEmpty(raw.title) || !nonEmpty(raw.sink)) return;
+	return {
+		title: raw.title.trim(),
+		sink: raw.sink,
+		scope: actionScope,
+		detail: typeof raw.detail === "string" ? raw.detail : void 0
+	};
+}
+function parseRetroSection(retro, errors) {
+	for (const key of Object.keys(retro)) if (!RETRO_KEYS.has(key)) errors.push(`retro: unknown key "${key}"`);
+	if (!nonEmpty(retro.what)) errors.push("retro: what is required — what went wrong");
+	if (!nonEmpty(retro.why)) errors.push("retro: why is required — the root cause");
+	const retroScope = scope(retro.scope, "retro", errors) ?? "project";
+	if (retro.wtf !== void 0 && typeof retro.wtf !== "string") errors.push("retro: wtf must be a bead id");
+	let evidence = [];
+	if (retro.evidence !== void 0) if (!Array.isArray(retro.evidence) || !retro.evidence.every(nonEmpty)) errors.push("retro: evidence must be a list of refs (sha, PR url, bead id)");
+	else evidence = retro.evidence.map((e) => e.trim());
+	return {
+		what: typeof retro.what === "string" ? retro.what.trim() : "",
+		why: typeof retro.why === "string" ? retro.why.trim() : "",
+		scope: retroScope,
+		wtf: nonEmpty(retro.wtf) ? retro.wtf.trim() : void 0,
+		evidence
+	};
+}
+function parseActions(rawActions, errors) {
+	if (rawActions === void 0) return [];
+	if (!Array.isArray(rawActions)) {
+		errors.push("actions: must be an array of tables ([[actions]])");
+		return [];
+	}
+	const actions = [];
+	rawActions.forEach((raw, i) => {
+		const action = parseAction(raw, i, errors);
+		if (action) actions.push(action);
+	});
+	return actions;
+}
+/** The `kind` value a retro plan must carry when it has one — lets
+* `bro run <file>` route the plan to this plugin. */
+const PLAN_KIND = "retrospect";
+/** Validate an already-parsed plan document — the plugin planSchema.
+*  Throws one error listing every problem — the agent fixes the file
+*  once instead of iterating on single failures. */
+function parsePlanDoc(doc, source = "plan") {
+	const errors = [];
+	if (isRecord(doc)) {
+		for (const key of Object.keys(doc)) if (key !== "retro" && key !== "actions" && key !== "kind") errors.push(`unknown top-level key "${key}"`);
+		if (doc.kind !== void 0 && doc.kind !== PLAN_KIND) errors.push(`kind: expected "${PLAN_KIND}", got ${JSON.stringify(doc.kind)}`);
+	}
+	const retro = isRecord(doc) ? doc.retro : void 0;
+	if (!isRecord(retro)) throw new Error(`${source}: [retro] table is required`);
+	const section = parseRetroSection(retro, errors);
+	const actions = parseActions(isRecord(doc) ? doc.actions : void 0, errors);
+	if (errors.length > 0) {
+		const details = errors.map((e) => `  - ${e}`).join("\n");
+		throw new Error(`${source}:\n${details}`);
+	}
+	return {
+		...section,
+		actions
+	};
+}
+/** Parse + validate a plan file's TOML text. */
+function parsePlan(text, source = "plan") {
+	let doc;
+	try {
+		doc = parse(text);
+	} catch (err) {
+		throw new Error(`${source}: invalid TOML — ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return parsePlanDoc(doc, source);
+}
+/** The commented template `bro retrospect schema` prints — keeps the schema
+* out of skill files so the CLI stays the single source of truth. */
+const PLAN_SCHEMA = `# retrospection plan — written by the agent, executed by \`bro retrospect record\`
+# or routed by kind via \`bro run retro.toml\`
+#
+#   bro retrospect record retro.toml
+
+kind = "retrospect"  # plan envelope — \`bro run\` routes on it
+
+[retro]
+what = ""            # required — what went wrong, one line
+why = ""             # required — root cause, not the symptom
+scope = "project"    # universal | project | user | agent | session
+wtf = ""             # optional — open wtf bead this retro answers (closed on record)
+evidence = []        # optional — shas, PR urls, bead ids → bd provenance
+
+# Every action becomes a 'prevention' bead linked discovered-from the retro.
+# sink decides where the executor lands it:
+#   backlog            tracked follow-up work
+#   memory             persist to user or project memory (scope decides)
+#   agentic-documents  AGENTS.md / rules / skill update
+#   upstream-issue     file an issue in the external repo
+#   workaround         code-level fix or guardrail to implement now
+#
+# recurrence: a root cause that recurred despite a prose rule needs >=1
+# workaround|backlog action — wider prose is more of what already failed
+#
+# [[actions]]
+# title = ""
+# sink = "backlog"
+# scope = "project"    # optional — overrides retro.scope for this action
+# detail = ""          # optional — body of the follow-up bead
+`;
+
+//#endregion
+//#region src/retro.ts
+const WTF_LABEL = "wtf";
+const RETRO_LABEL = "retro";
+const PREVENTION_LABEL = "prevention";
+const isOpen = (row) => row.status !== "closed" && row.status !== "done";
+function listByLabel(label) {
+	return taskStore().list({
+		labels: [label],
+		all: true,
+		limit: 0
+	});
+}
+function listWtf() {
+	return listByLabel(WTF_LABEL);
+}
+function openWtf() {
+	return listWtf().filter(isOpen);
+}
+function listRetros() {
+	return listByLabel(RETRO_LABEL);
+}
+function openPreventions() {
+	return listByLabel(PREVENTION_LABEL).filter(isOpen);
+}
+function shorten(text) {
+	return text.length > 72 ? `${text.slice(0, 71)}…` : text;
+}
+/** Best-effort provenance for the capture — tolerate non-git directories. */
+function gitSnapshot() {
+	try {
+		return [`git: ${execFileSync("git", [
+			"rev-parse",
+			"--abbrev-ref",
+			"HEAD"
+		], { encoding: "utf8" }).trim()}@${execFileSync("git", [
+			"rev-parse",
+			"--short",
+			"HEAD"
+		], { encoding: "utf8" }).trim()}`];
+	} catch {
+		return [];
+	}
+}
+/**
+* Capture a wtf moment: the user's complaint verbatim + a context snapshot.
+* The quote is evidence — never paraphrased.
+*/
+function captureWtf(complaint) {
+	if (!complaint.trim()) throw new Error("wtf capture requires the complaint — quote the user verbatim");
+	const description = [
+		`> ${complaint}`,
+		"",
+		`captured: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+		`cwd: ${process.cwd()}`,
+		...gitSnapshot()
+	].join("\n");
+	const title = `wtf: ${shorten(complaint.trim().split("\n")[0] ?? "")}`;
+	return taskStore().create({
+		title,
+		labels: [WTF_LABEL],
+		description
+	});
+}
+function requireOpenWtf(id) {
+	const row = taskStore().get(id);
+	if (!row || !(row.labels?.includes(WTF_LABEL) ?? false) || !isOpen(row)) throw new Error(`wtf ${id} is not an open wtf bead`);
+	return row;
+}
+/** No explicit wtf? The single open wtf bead is the obvious answer;
+* ambiguity is the caller's problem to resolve. */
+function resolveSingleWtf() {
+	const open = openWtf();
+	if (open.length > 1) throw new Error(`${open.length} open wtf beads — set retro.wtf in the plan or pass --wtf to pick one`);
+	return open[0];
+}
+/**
+* Record a validated plan: the retro bead carries the analysis memo and is
+* closed immediately — it is a record, not work. Each action lands as an
+* open prevention bead the executor routes by its `sink:` label.
+*/
+function recordRetro(plan) {
+	const wtf = plan.wtf ? requireOpenWtf(plan.wtf) : resolveSingleWtf();
+	const memo = [
+		"## What",
+		"",
+		plan.what,
+		"",
+		"## Why",
+		"",
+		plan.why,
+		"",
+		`scope: ${plan.scope}`
+	].join("\n");
+	const title = `retro: ${shorten(plan.what.split("\n")[0] ?? "")}`;
+	const retro = taskStore().create({
+		title,
+		labels: [RETRO_LABEL],
+		description: memo,
+		...wtf ? {
+			deps: [`discovered-from:${wtf.id}`],
+			noInheritLabels: true
+		} : {}
+	});
+	const created = [retro.id];
+	const actionIds = [];
+	try {
+		for (const action of plan.actions) {
+			const detail = [
+				action.detail ?? "",
+				"",
+				`sink: ${action.sink}`,
+				`scope: ${action.scope ?? plan.scope}`,
+				`retro: ${retro.id}`
+			].join("\n").trim();
+			const row = taskStore().create({
+				title: action.title,
+				labels: [PREVENTION_LABEL, `sink:${action.sink}`],
+				noInheritLabels: true,
+				deps: [`discovered-from:${retro.id}`],
+				description: detail
+			});
+			actionIds.push(row.id);
+			created.push(row.id);
+		}
+		for (const ref of plan.evidence) bd$1([
+			"provenance",
+			"record",
+			"--issue",
+			retro.id,
+			"--kind",
+			evidenceKind(ref),
+			"--source",
+			"bro retrospect record",
+			"--ref",
+			ref,
+			"--ref-kind",
+			refKind$1(ref)
+		]);
+		taskStore().close(retro.id, "retrospect recorded");
+		if (wtf) taskStore().close(wtf.id, `answered by retro ${retro.id}`);
+	} catch (err) {
+		for (const id of created) try {
+			taskStore().remove(id);
+		} catch {}
+		throw err;
+	}
+	return {
+		retroId: retro.id,
+		actionIds,
+		closedWtf: wtf?.id
+	};
+}
+
+//#endregion
+export { ACTION_SINKS, PLAN_KIND, PLAN_SCHEMA, RETRO_SCOPES, bd, bdJson, captureWtf, checkBeads, listRetros, listWtf, openPreventions, openWtf, parsePlan, parsePlanDoc, recordRetro, refKind };

package/package.json

@@ -1,16 +1,48 @@
 {
-  "description": "Placeholder for @broject/retro published by @nx-devkit/prepare-for-release.",
-  "license": "MIT",
   "name": "@broject/retro",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+  "version": "0.2.3",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "tsx --test src/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "smol-toml": "1.7.1",
+    "@broject/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.15.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
   },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ThePlenkov/bro.git",
     "directory": "packages/retro"
   },
-  "type": "module",
-  "version": "0.0.0"
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Retrospect engine for bro — TOML retro plans fan prevention actions out to beads, skills, rules",
+  "keywords": [
+    "retrospective",
+    "self-correction",
+    "beads",
+    "agent",
+    "bro"
+  ],
+  "homepage": "https://broject.dev/docs"
+}