pi-matt-pocock 0.2.0 → 0.2.2

package/README.md

@@ -191,3 +191,7 @@ You can optionally configure native macOS dialog prompts for `matt_pocock_ask` v
 By default (`useNativeDialog: false` or missing file), Pi uses its built-in TUI selection dialog. Native dialogs are automatically guarded to only trigger on local macOS GUI sessions (SSH sessions, non-macOS platforms, and CI environments always fall back cleanly to terminal TUI).
 
 See the detailed [中文架构说明](ARCHITECTURE.zh-CN.md), the upstream [selection metadata](upstream-selection.json) and [sync rules](UPSTREAM.md), and the deliberately deferred items in [TODO.md](TODO.md).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-matt-pocock",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "BDD-first engineering and productivity skills adapted from Matt Pocock's skills",
   "keywords": [
@@ -39,7 +39,7 @@
     "typebox": "*"
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.5.0"
+    "@fradser/pi-kit": "0.5.1"
   },
   "pi": {
     "extensions": [

package/src/index.ts

@@ -29,7 +29,7 @@ import {
   workflowDefinitions,
   workflowPlacement,
 } from "./catalog.ts";
-import { resolveAccessibleReference, resolveProcedureBundle, resolveWorkflowContext } from "./resolver.ts";
+import { resolveAccessibleReference, resolveProcedureBundle, resolveProcedureDelta, resolveWorkflowContext } from "./resolver.ts";
 /** Geometry bound once: every Matt Pocock row shares hint and wrapping. */
 const mattPocockRows = bindLifecycleRenderers({
   fit: truncateToWidth,
@@ -49,6 +49,7 @@ import {
   transitionState,
   workflowGuidance,
   workflowRoutes,
+  withDeliveryDefaults,
   WORKFLOW_STATE_ENTRY,
   WORKFLOW_STATE_VERSION,
   type TerminalWorkflowState,
@@ -164,9 +165,29 @@ function userRequestSection(request: string): string {
   return request ? `\n\nUser target/request:\n${request}` : "";
 }
 
-function workflowPrompt(state: WorkflowState, action: string, request = ""): string {
-  const bundle = resolveWorkflowContext(state.procedure, state.loadedReferences);
-  return `# Matt Pocock workflow procedure\n\nRoute: ${state.route}\nPhase: ${state.phase}\nWork item: ${state.workItemId}\n\n${bundle.content}${userRequestSection(request)}${stateContract(state, action)}`;
+/** Delivered when a procedure's body is already in the session, so the prompt is never empty. */
+const ALREADY_DELIVERED = "Its instructions were delivered earlier in this session and are unchanged. Continue against them; do not re-request them.";
+
+/**
+ * The prompt for a workflow step, plus the state that records what it delivered.
+ *
+ * Only procedures this session has not been shown are embedded. A transition re-delivers
+ * the active context every time, and a bundle carries its whole dependency closure, so
+ * re-sending that closure would spend the context the work needs and end a long task early
+ * for want of room rather than for want of work.
+ */
+function deliveryStep(state: WorkflowState, action: string, request = "", full = false): { text: string; state: WorkflowState } {
+  const delta = resolveProcedureDelta(
+    state.procedure,
+    state.loadedReferences,
+    full ? [] : state.deliveredProcedures,
+  );
+  const next: WorkflowState = { ...state, deliveredProcedures: delta.delivered };
+  const body = delta.content ? delta.content : ALREADY_DELIVERED;
+  return {
+    text: `# Matt Pocock workflow procedure\n\nRoute: ${next.route}\nPhase: ${next.phase}\nWork item: ${next.workItemId}\n\n${body}${userRequestSection(request)}${stateContract(next, action)}`,
+    state: next,
+  };
 }
 
 function standalonePrompt(capability: string, request = ""): string {
@@ -185,24 +206,33 @@ function standaloneReferencePrompt(capability: string, reference: string): strin
   return `# Matt Pocock standalone reference\n\nCapability: ${definition.id}\nReference: ${bundle.root}\nPersistent workflow state: none\nAvailable references: ${bundle.availableReferences.join(", ") || "none"}\n\n${bundle.content}`;
 }
 
-function startWorkflow(route: string): WorkflowState {
+/**
+ * Begin a workflow and persist its state exactly once, carrying the delivery set
+ * this first step shows. A second entry would read as two workflows begun, and a
+ * persisted state without the set would re-deliver the whole closure on restore.
+ */
+function startWorkflow(route: string, request = ""): { state: WorkflowState; text: string } {
   if (!findWorkflowRoute(route)) throw new Error(`Unknown Matt Pocock route: ${route}`);
-  const state = routeEntryState(route, randomUUID());
-  if (!state) throw new Error(`Workflow ${route} has no catalog entry procedure.`);
-  resolveProcedureBundle(state.procedure);
-  persistWorkflow(state);
-  return state;
+  const created = routeEntryState(route, randomUUID());
+  if (!created) throw new Error(`Workflow ${route} has no catalog entry procedure.`);
+  resolveProcedureBundle(created.procedure);
+  const step = deliveryStep(created, "started workflow", request);
+  persistWorkflow(step.state);
+  return step;
 }
 
 function loadActiveReference(reference: string): { state: WorkflowState; content: string } {
   if (!activeWorkflow) throw new Error("No active Matt Pocock workflow.");
   const bundle = resolveAccessibleReference(activeWorkflow.procedure, activeWorkflow.loadedReferences, reference);
   const loadedReferences = [...new Set([...activeWorkflow.loadedReferences, ...bundle.loaded])];
-  const state = { ...activeWorkflow, loadedReferences };
+  // The reference's own closure is deduplicated too: a reference whose body is already in
+  // the session does not need to arrive twice.
+  const delta = resolveProcedureDelta(reference, [], activeWorkflow.deliveredProcedures);
+  const state: WorkflowState = { ...activeWorkflow, loadedReferences, deliveredProcedures: delta.delivered };
   persistWorkflow(state);
   return {
     state,
-    content: `# Matt Pocock workflow reference\n\nWork item: ${state.workItemId}\nReference: ${bundle.root}\n\n${bundle.content}${stateContract(state, `loaded reference ${bundle.root}`)}`,
+    content: `# Matt Pocock workflow reference\n\nWork item: ${state.workItemId}\nReference: ${bundle.root}\n\n${delta.content || ALREADY_DELIVERED}${stateContract(state, `loaded reference ${bundle.root}`)}`,
   };
 }
 
@@ -227,9 +257,9 @@ async function chooseRoute(ctx: ExtensionCommandContext): Promise<void> {
   if (!choice) return;
   const route = routeFromChoice(choice);
   if (!route) return;
-  const state = startWorkflow(route);
+  const step = startWorkflow(route);
   clearPiStatus(ctx.ui, "matt-pocock");
-  deliverProcedure(workflowPrompt(state, "started workflow"), { ...state, request: "" });
+  deliverProcedure(step.text, { ...step.state, request: "" });
 }
 
 async function chooseCapability(ctx: ExtensionCommandContext): Promise<void> {
@@ -247,8 +277,9 @@ function applyTransition(ctx: ExtensionCommandContext, target: string): void {
   }
   const state = transitionState(activeWorkflow, target);
   resolveProcedureBundle(state.procedure);
-  persistWorkflow(state);
-  deliverProcedure(workflowPrompt(state, `transitioned to ${state.procedure}`), { ...state, request: "" });
+  const step = deliveryStep(state, `transitioned to ${state.procedure}`);
+  persistWorkflow(step.state);
+  deliverProcedure(step.text, { ...step.state, request: "" });
 }
 
 async function chooseTransition(ctx: ExtensionCommandContext): Promise<void> {
@@ -342,15 +373,21 @@ export default function mattPocock(extensionApi: ExtensionAPI): void {
       if (!workflowPlacement(record.route, record.procedure)) {
         throw new Error(`Procedure ${record.procedure} is not part of workflow ${record.route}.`);
       }
-      const content = workflowPrompt(record, "restored workflow");
-      activeWorkflow = record;
+      // A restore is a context boundary: this session may have been compacted or restarted,
+      // so the whole active context is re-delivered rather than deduplicated. Delivery
+      // tracking only suppresses repeats inside one continuous session.
+      const restored = withDeliveryDefaults(record);
+      const step = deliveryStep(restored, "restored workflow", "", true);
+      // Not persisted here: session_start must not write to the branch. The next transition
+      // records the delivery set it has actually shown.
+      activeWorkflow = step.state;
       refreshActiveTools(true);
       clearPiStatus(ctx.ui, "matt-pocock");
       pi.sendMessage({
         customType: PROCEDURE_ENTRY,
-        content,
+        content: step.text,
         display: false,
-        details: record,
+        details: step.state,
       }, { deliverAs: "nextTurn" });
     } catch (error) {
       activeWorkflow = record;
@@ -416,10 +453,10 @@ export default function mattPocock(extensionApi: ExtensionAPI): void {
         if (activeWorkflow) {
           throw new Error(`Workflow ${activeWorkflow.workItemId} is already active. Complete or cancel it before starting another.`);
         }
-        const state = startWorkflow(params.route);
+        const step = startWorkflow(params.route);
         return {
-          content: [{ type: "text", text: workflowPrompt(state, "started workflow") }],
-          details: { mode: "workflow", ...state },
+          content: [{ type: "text", text: step.text }],
+          details: { mode: "workflow", ...step.state },
         };
       }
       if (params.mode === "reference") {
@@ -471,11 +508,12 @@ export default function mattPocock(extensionApi: ExtensionAPI): void {
       if (params.action === "transition") {
         const state = transitionState(activeWorkflow, params.target);
         resolveProcedureBundle(state.procedure);
-        persistWorkflow(state);
+        const step = deliveryStep(state, `transitioned to ${state.procedure}`);
+        persistWorkflow(step.state);
         clearPiStatus(ctx.ui, "matt-pocock");
         return {
-          content: [{ type: "text", text: workflowPrompt(state, `transitioned to ${state.procedure}`) }],
-          details: { action: "transition", subject: workflowEventSubject("transition", state.phase), state },
+          content: [{ type: "text", text: step.text }],
+          details: { action: "transition", subject: workflowEventSubject("transition", state.phase), state: step.state },
         };
       }
       if (params.action === "load") {
@@ -715,9 +753,9 @@ export default function mattPocock(extensionApi: ExtensionAPI): void {
 
       if (findWorkflowRoute(token)) {
         if (activeWorkflow) throw new Error(`Workflow ${activeWorkflow.workItemId} is already active.`);
-        const state = startWorkflow(token);
+        const step = startWorkflow(token, task);
         clearPiStatus(ctx.ui, "matt-pocock");
-        deliverProcedure(workflowPrompt(state, "started workflow", task), { ...state, request: task });
+        deliverProcedure(step.text, { ...step.state, request: task });
         return;
       }
       const capability = findProcedure(token);

package/src/resolver.ts

@@ -125,3 +125,33 @@ export function resolveAccessibleReference(
   }
   return resolveProcedureBundle(target.id);
 }
+
+export interface ProcedureDelta {
+  content: string;
+  delivered: string[];
+  availableReferences: string[];
+}
+
+/**
+ * The part of the active context this session has not been shown yet.
+ *
+ * A workflow re-delivers its prompt on every transition, and a procedure's bundle carries
+ * its whole dependency closure -- so re-sending the closure each time spends the context
+ * the work itself needs, and a long task stops partway for lack of room rather than for
+ * lack of work. A procedure already delivered in this session is therefore not sent again:
+ * the instructions the model has already read stay read, and only what is new arrives.
+ */
+export function resolveProcedureDelta(
+  activeProcedure: string,
+  loadedReferences: string[],
+  delivered: string[],
+): ProcedureDelta {
+  const context = resolveWorkflowContext(activeProcedure, loadedReferences);
+  const already = new Set(delivered);
+  const pending = context.loaded.filter((id) => !already.has(id));
+  return {
+    content: pending.map((id) => renderSource(requireDefinition(id))).join("\n\n"),
+    delivered: [...new Set([...delivered, ...context.loaded])],
+    availableReferences: context.availableReferences,
+  };
+}

package/src/workflow.ts

@@ -18,6 +18,8 @@ export interface WorkflowState {
   phase: string;
   status: "active";
   loadedReferences: string[];
+  /** Procedures whose body has already been delivered in this session. */
+  deliveredProcedures: string[];
 }
 
 export interface TerminalWorkflowState {
@@ -54,6 +56,7 @@ export function routeEntryState(route: string, workItemId: string): WorkflowStat
     phase: placement.phase,
     status: "active",
     loadedReferences: [],
+    deliveredProcedures: [],
   };
 }
 
@@ -113,7 +116,17 @@ export function isWorkflowState(value: unknown): value is WorkflowState {
     && typeof candidate.phase === "string"
     && candidate.status === "active"
     && Array.isArray(candidate.loadedReferences)
-    && candidate.loadedReferences.every((reference) => typeof reference === "string");
+    && candidate.loadedReferences.every((reference) => typeof reference === "string")
+    // Absent is tolerated so a workflow persisted before delivery tracking existed still
+    // restores; it simply re-delivers once, which is harmless.
+    && (candidate.deliveredProcedures === undefined
+      || (Array.isArray(candidate.deliveredProcedures)
+        && candidate.deliveredProcedures.every((id) => typeof id === "string")));
+}
+
+/** Backfill delivery tracking on a state persisted before it existed. */
+export function withDeliveryDefaults(state: WorkflowState): WorkflowState {
+  return { ...state, deliveredProcedures: state.deliveredProcedures ?? [] };
 }
 
 export function isTerminalWorkflowState(value: unknown): value is TerminalWorkflowState {
@@ -138,13 +151,19 @@ export function latestWorkflowRecord(entries: unknown[]): WorkflowSessionData |
 
 export function latestWorkflowState(entries: unknown[]): WorkflowState | undefined {
   const record = latestWorkflowRecord(entries);
-  return record?.status === "active" ? record : undefined;
+  return record?.status === "active" ? withDeliveryDefaults(record) : undefined;
 }
 
 export function workflowGuidance(state: WorkflowState, availableReferences: string[]): string {
   const next = allowedTransitions(state.route, state.procedure);
   return `Matt Pocock workflow active: ${state.route} · ${state.phase}.
-Work item: ${state.workItemId}. Follow the loaded ${state.procedure} procedure. Use matt_pocock_active to transition only to: ${next.join(", ") || "none"}; load an available reference; complete the work; or cancel it with a reason. Available references: ${availableReferences.join(", ") || "none"}. Exact shapes: {"action": "transition", "target": "<allowedNext id>"}; {"action": "load", "reference": "<availableReferences id>"}; {"action": "complete"}; {"action": "cancel", "reason": "<why>"}. Proceed autonomously through non-user-owned work: once the current procedure's deliverables or decisions are ready, transition to the next applicable procedure via matt_pocock_active immediately without stopping to ask permission. Ask only for a genuinely user-owned decision, unavailable fact, or required external action. Use matt_pocock_ask for structured workflow decisions. Complete only after the integrated candidate has applicable verification and all blocking reviews have returned with findings resolved; a completed review assignment is not itself a PASS verdict. Evidence must match that candidate. If only required results remain outstanding, yield with the workflow still active rather than declaring completion. Once these conditions hold, call matt_pocock_active with action complete instead of leaving stale active state.`;
+Work item: ${state.workItemId}. Follow the loaded ${state.procedure} procedure.
+
+Drive the current procedure to its end in this turn. A multi-step deliverable is not finished because one step passed: keep implementing, testing and fixing until every step the procedure covers is done, rather than stopping at the first green slice or handing back a plan for the remainder. Do not end the turn to ask whether to continue.
+
+Use matt_pocock_active to transition only to: ${next.join(", ") || "none"}; load an available reference; complete the work; or cancel it with a reason. Available references: ${availableReferences.join(", ") || "none"}. Exact shapes: {"action": "transition", "target": "<allowedNext id>"}; {"action": "load", "reference": "<availableReferences id>"}; {"action": "complete"}; {"action": "cancel", "reason": "<why>"}. Proceed autonomously through non-user-owned work: transition to the next applicable procedure as soon as this one's deliverables are complete, without stopping to ask permission. Ask only for a genuinely user-owned decision, an unavailable fact, or a required external action, and use matt_pocock_ask for those.
+
+Yield only when the remaining work genuinely depends on an external actor, on a teammate result you cannot produce yourself, or on context you no longer have — and when you yield, state plainly what is unfinished rather than implying completion. Never announce completion early: call matt_pocock_active with action complete only once the integrated candidate has applicable verification and all blocking reviews have returned with their findings resolved; a completed review assignment is not itself a PASS verdict, and evidence must match that candidate.`;
 }
 
 export function availableWorkflowsGuidance(): string {