@pmelab/gtd 20.2.0 → 20.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gtd",
-  "version": "20.2.0",
+  "version": "20.3.0",
   "description": "Drive the gtd loop inside Claude Code: agent turns run as subagents, gtd decides every beat",
   "author": {
     "name": "Philipp Melab"

package/README.md

@@ -501,7 +501,9 @@ The workflow itself is a plain async TypeScript function: a `gtd.config.ts` at
 the repository root replaces it, and the pieces the bundled one is built from
 are exported for yours to reuse. See
 [Configuration](https://github.com/pmelab/gtd/blob/main/docs/configuration.md) —
-and remember gtd evaluates that file on every command.
+and remember gtd evaluates that file on every command. A shared workflow package
+bundling its own `@pmelab/gtd` is checked against the running gtd and refused,
+naming which side to upgrade, on a flows protocol mismatch.
 
 ## License
 

package/dist/gtd.bundle.mjs

@@ -32266,16 +32266,34 @@ Any runtime works: the contract is \`--json\`/\`--json=<path>\` in, subprocesses
 out.
 `;
 const renderBriefing = () => HEADER() + BEAT_PROTOCOL + JSON_FIELD_REFERENCE + DRIVER_OBLIGATIONS + RECOVERY + commandSuite() + EDITOR_INTEGRATION + PREREQUISITES;
-//#endregion
-//#region src/flows/runtime.ts
+var FlowsProtocolError = class extends Error {
+	constructor(engine, flows) {
+		super(`gtd: the workflow speaks flows protocol ${flows}, but the engine installed protocol ${engine} — ${engine < flows ? "upgrade the gtd that runs it" : "upgrade the @pmelab/gtd the workflow imports"}`);
+		this.name = "FlowsProtocolError";
+	}
+};
 const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context");
-/** Engine-only: install the replay context a flow run reads. */
+const PROTOCOL_KEY = Symbol.for("@pmelab/gtd/flow-protocol");
+const MISMATCH_KEY = Symbol.for("@pmelab/gtd/flow-protocol-mismatch");
+/** Engine-only. */
 const installContext = (context) => {
-	globalThis[CONTEXT_KEY] = context;
+	const holder = globalThis;
+	holder[CONTEXT_KEY] = context;
+	holder[PROTOCOL_KEY] = 1;
+	holder[MISMATCH_KEY] = void 0;
 };
+/** Engine-only: the mismatch a facade copy hit during this replay, if any. */
+const protocolMismatch = () => globalThis[MISMATCH_KEY];
 const ctx = () => {
-	const context = globalThis[CONTEXT_KEY];
+	const holder = globalThis;
+	const context = holder[CONTEXT_KEY];
 	if (context === void 0) throw new Error("gtd: a workflow step or helper was called outside a gtd replay");
+	const protocol = holder[PROTOCOL_KEY] ?? 1;
+	if (protocol !== 1) {
+		const error = new FlowsProtocolError(protocol, 1);
+		holder[MISMATCH_KEY] ??= error;
+		throw error;
+	}
 	return context;
 };
 /** An agent turn: `prompt` is emitted, the driver lands the diff. */
@@ -32553,6 +32571,8 @@ const requireRevert = (edited, base) => {
 //#endregion
 //#region src/flows/index.ts
 var flows_exports = /* @__PURE__ */ __exportAll({
+	FLOWS_PROTOCOL: () => 1,
+	FlowsProtocolError: () => FlowsProtocolError,
 	accessFor: () => accessFor,
 	agent: () => agent,
 	answered: () => answered,
@@ -32572,6 +32592,7 @@ var flows_exports = /* @__PURE__ */ __exportAll({
 	moveScript: () => moveScript,
 	numeric: () => numeric,
 	openQuestions: () => openQuestions,
+	protocolMismatch: () => protocolMismatch,
 	quote: () => quote,
 	read: () => read,
 	refuse: () => refuse,
@@ -49496,7 +49517,7 @@ const replay = async (input) => {
 			if (error instanceof Stop) return;
 			outcome ??= {
 				kind: "failed",
-				message: `gtd: the workflow threw: ${error instanceof Error ? error.message : String(error)}`
+				message: error instanceof Error && error.name === "FlowsProtocolError" ? error.message : `gtd: the workflow threw: ${error instanceof Error ? error.message : String(error)}`
 			};
 		});
 		const stuck = new Promise((resolve) => setImmediate(resolve));
@@ -49505,6 +49526,11 @@ const replay = async (input) => {
 			settled,
 			stuck
 		]);
+		const mismatch = protocolMismatch();
+		if (mismatch !== void 0) return {
+			kind: "failed",
+			message: mismatch.message
+		};
 	} finally {
 		installContext(void 0);
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "20.2.0",
+  "version": "20.3.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/flows/runtime.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  FLOWS_PROTOCOL,
+  FlowsProtocolError,
+  head,
+  installContext,
+  protocolMismatch,
+  type FlowContext,
+} from "./runtime.js"
+
+afterEach(() => installContext(undefined))
+
+const context = { head: () => "h1" } as unknown as FlowContext
+const globals = globalThis as Record<symbol, unknown>
+const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
+const PROTOCOL_KEY = Symbol.for("@pmelab/gtd/flow-protocol")
+
+describe("the flows protocol handshake", () => {
+  it("reads the context when the engine installed the facade's protocol", () => {
+    installContext(context)
+    expect(head()).toBe("h1")
+  })
+
+  it("tells a newer engine to have the workflow's package upgraded", () => {
+    installContext(context)
+    globals[PROTOCOL_KEY] = FLOWS_PROTOCOL + 1
+    expect(() => head()).toThrow(FlowsProtocolError)
+    expect(() => head()).toThrow(
+      `gtd: the workflow speaks flows protocol ${FLOWS_PROTOCOL}, but the engine installed protocol ${FLOWS_PROTOCOL + 1} — upgrade the @pmelab/gtd the workflow imports`,
+    )
+    expect(protocolMismatch()).toBeInstanceOf(FlowsProtocolError)
+  })
+
+  it("tells an older engine to be upgraded", () => {
+    installContext(context)
+    globals[PROTOCOL_KEY] = FLOWS_PROTOCOL - 1
+    expect(() => head()).toThrow(
+      `engine installed protocol ${FLOWS_PROTOCOL - 1} — upgrade the gtd that runs it`,
+    )
+  })
+
+  // Must go red once FLOWS_PROTOCOL passes 1: a pre-handshake engine is v1.
+  it("accepts an engine that installs no protocol number", () => {
+    delete globals[PROTOCOL_KEY]
+    globals[CONTEXT_KEY] = context
+    expect(head()).toBe("h1")
+  })
+
+  it("keeps the outside-a-replay error when nothing is installed", () => {
+    expect(() => head()).toThrow(
+      new Error("gtd: a workflow step or helper was called outside a gtd replay"),
+    )
+  })
+})

package/src/flows/runtime.ts

@@ -159,20 +159,66 @@ export interface FlowContext {
   readonly accessFor: (localName: string, file?: string) => AccessDef
 }
 
-const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
+/**
+ * Bump only when the installed `FlowContext` object changes shape or semantics;
+ * type-only authoring-API changes don't count. A bump past 1 must keep v1
+ * members working or move the context to a new symbol key — pre-handshake
+ * facades never read the protocol.
+ */
+export const FLOWS_PROTOCOL = 1
+
+export class FlowsProtocolError extends Error {
+  constructor(engine: number, flows: number) {
+    const upgrade =
+      engine < flows
+        ? "upgrade the gtd that runs it"
+        : "upgrade the @pmelab/gtd the workflow imports"
+    super(
+      `gtd: the workflow speaks flows protocol ${flows}, but the engine installed protocol ${engine} — ${upgrade}`,
+    )
+    this.name = "FlowsProtocolError"
+  }
+}
 
-type ContextHolder = { [CONTEXT_KEY]?: FlowContext | undefined }
+const CONTEXT_KEY = Symbol.for("@pmelab/gtd/flow-context")
+// Separate from the context so a facade older than the protocol still reads
+// the context it expects.
+const PROTOCOL_KEY = Symbol.for("@pmelab/gtd/flow-protocol")
+// The first mismatch, kept for the engine: workflow code may catch what ctx()
+// throws, and the refusal must still win.
+const MISMATCH_KEY = Symbol.for("@pmelab/gtd/flow-protocol-mismatch")
+
+type ContextHolder = {
+  [CONTEXT_KEY]?: FlowContext | undefined
+  [PROTOCOL_KEY]?: number | undefined
+  [MISMATCH_KEY]?: Error | undefined
+}
 
-/** Engine-only: install the replay context a flow run reads. */
+/** Engine-only. */
 export const installContext = (context: FlowContext | undefined): void => {
-  ;(globalThis as ContextHolder)[CONTEXT_KEY] = context
+  const holder = globalThis as ContextHolder
+  holder[CONTEXT_KEY] = context
+  holder[PROTOCOL_KEY] = FLOWS_PROTOCOL
+  holder[MISMATCH_KEY] = undefined
 }
 
+/** Engine-only: the mismatch a facade copy hit during this replay, if any. */
+export const protocolMismatch = (): Error | undefined => (globalThis as ContextHolder)[MISMATCH_KEY]
+
 const ctx = (): FlowContext => {
-  const context = (globalThis as ContextHolder)[CONTEXT_KEY]
+  const holder = globalThis as ContextHolder
+  const context = holder[CONTEXT_KEY]
   if (context === undefined) {
     throw new Error("gtd: a workflow step or helper was called outside a gtd replay")
   }
+  // An engine older than the handshake installs no number but the context
+  // protocol 1 describes.
+  const protocol = holder[PROTOCOL_KEY] ?? 1
+  if (protocol !== FLOWS_PROTOCOL) {
+    const error = new FlowsProtocolError(protocol, FLOWS_PROTOCOL)
+    holder[MISMATCH_KEY] ??= error
+    throw error
+  }
   return context
 }