borgmcp-shared 0.6.4 → 0.7.0

package/src/protocol/coordination.ts

@@ -10,7 +10,12 @@ import {
   type ProtocolEnvelope,
 } from './contract.js';
 import { decodeEnrichedStreamEntry } from './sse.js';
-import type { Decision, EnrichedStreamEntry } from './types.js';
+import type {
+  AppendLogResponse,
+  Decision,
+  EnrichedStreamEntry,
+  RoutingEcho,
+} from './types.js';
 
 export interface ReadLogRequest {
   cursor: LogCursor | null;
@@ -26,7 +31,7 @@ export interface ClaimRecord {
   stale: boolean;
 }
 
-export interface AppendLogResult {
+export interface AppendLogResult extends Omit<AppendLogResponse, 'entry'> {
   entry: EnrichedStreamEntry;
 }
 
@@ -214,10 +219,54 @@ function decodeClaimRecord(value: unknown): ClaimRecord {
   };
 }
 
+function decodeRoutingEcho(value: unknown): RoutingEcho {
+  const input = object(value);
+  exact(
+    input,
+    ['class', 'recipients', 'fellOpen', 'message'],
+    ['class', 'recipients', 'fellOpen', 'message'],
+  );
+  if (!Array.isArray(input.recipients) || input.recipients.length > 100) {
+    throw new ProtocolContractError('Invalid routing recipient list.');
+  }
+  if (typeof input.fellOpen !== 'boolean') {
+    throw new ProtocolContractError('Invalid routing fell-open flag.');
+  }
+  return {
+    class: nullableString(input.class, 'routing.class', 64),
+    recipients: input.recipients.map((recipient) =>
+      boundedString(recipient, 'routing.recipients', 120)
+    ),
+    fellOpen: input.fellOpen,
+    message: nullableString(input.message, 'routing.message', 512),
+  };
+}
+
+function decodeUnreachableRecipient(
+  value: unknown,
+): NonNullable<AppendLogResponse['unreachableRecipients']>[number] {
+  const input = object(value);
+  exact(input, ['id', 'label'], ['id', 'label']);
+  return {
+    id: boundedString(input.id, 'unreachableRecipients.id', 120),
+    label: boundedString(input.label, 'unreachableRecipients.label', 120),
+  };
+}
+
 export function decodeAppendLogResult(value: unknown): AppendLogResult {
   const input = object(value);
-  exact(input, ['entry'], ['entry']);
-  return { entry: decodeEnrichedStreamEntry(input.entry) };
+  exact(input, ['entry', 'routing', 'unreachableRecipients'], ['entry']);
+  const output: AppendLogResult = { entry: decodeEnrichedStreamEntry(input.entry) };
+  if (input.routing !== undefined) {
+    output.routing = input.routing === null ? null : decodeRoutingEcho(input.routing);
+  }
+  if (input.unreachableRecipients !== undefined) {
+    if (!Array.isArray(input.unreachableRecipients) || input.unreachableRecipients.length > 100) {
+      throw new ProtocolContractError('Invalid unreachable-recipient list.');
+    }
+    output.unreachableRecipients = input.unreachableRecipients.map(decodeUnreachableRecipient);
+  }
+  return output;
 }
 
 export function decodeAppendLogResultEnvelope(

package/src/protocol/version.ts

@@ -1,4 +1,4 @@
-/** Current Borg coordination protocol generation. Clean-slate v5. */
-export const PROTOCOL_VERSION = '5' as const;
+/** Current Borg coordination protocol generation. Clean-slate v6. */
+export const PROTOCOL_VERSION = '6' as const;
 
 export type ProtocolVersion = typeof PROTOCOL_VERSION;

package/src/templates.ts

@@ -51,6 +51,11 @@ export const NEW_CUBE_TEMPLATE_PRESENTATIONS = [
     label: 'Starter',
     short_description: 'Minimal roles for general projects.',
   },
+  {
+    name: 'local-model',
+    label: 'Local Model',
+    short_description: 'Maximizes local-model execution through complete, machine-checkable work packets.',
+  },
 ] as const;
 
 export const ESCALATION_DISCIPLINE = `
@@ -266,9 +271,16 @@ Before changing code:
 - Inspect existing code and tests. Preserve unrelated and pre-existing changes.
 - If the request is ambiguous in a way that changes scope, post BLOCKED with the smallest decision needed.
 
+Implementation discipline:
+- Read and trace the real affected flow before choosing an implementation.
+- Prefer, in order: no change when the requirement is already satisfied; an existing repository helper or pattern; the standard library or native platform; an already-installed dependency; only then the minimum new code.
+- Make the smallest change that satisfies the complete authorized acceptance criteria. Prefer the least complex implementation that fully works, not the least work.
+- For defects, inspect sibling callers and fix the root cause at the narrowest shared point when that is safer and smaller than per-caller patches.
+- Never simplify away trust-boundary validation, security controls, data-loss prevention, accessibility requirements, explicit acceptance criteria, or proportionate regression tests.
+
 While working:
 - Post STARTING with the branch and first concrete action, then substantive PROGRESS during active work.
-- Make the smallest coherent implementation. Do not add cleanup, broad refactors, speculative hardening, documentation programs, or follow-up issues unless assigned.
+- Do not add cleanup, broad refactors, speculative hardening, documentation programs, or follow-up issues unless assigned.
 - A discovered issue outside the slice is a finding, not permission to fix it.
 - Add proportionate tests for behavior you change. Run the repository checks required by the touched surface.
 
@@ -503,9 +515,184 @@ const STARTER: Template = {
   ],
 };
 
+const LOCAL_MODEL_TAXONOMY: MessageTaxonomy = [
+  {
+    class: 'executor-echo',
+    prefixes: ['PACKET-ECHO'],
+    routing: 'directed',
+    default_to: ['shaper'],
+  },
+  {
+    class: 'executor-refusal',
+    prefixes: ['SPEC-GAP'],
+    routing: 'directed',
+    default_to: ['shaper'],
+  },
+  {
+    class: 'executor-completion',
+    prefixes: ['PACKET-DONE'],
+    routing: 'directed',
+    default_to: ['shaper'],
+    lifecycle: 'completion',
+  },
+  {
+    class: 'packet-dispatch',
+    prefixes: ['EXECUTE PACKET'],
+    routing: 'directed',
+    default_to: ['executor'],
+    lifecycle: 'dispatch',
+  },
+  {
+    class: 'packet-verdict',
+    prefixes: ['ACCEPT', 'REJECT'],
+    routing: 'directed',
+    default_to: ['executor'],
+  },
+  {
+    class: 'blocked-signal',
+    prefixes: ['BLOCKED'],
+    routing: 'directed',
+    default_to: ['director', 'queen'],
+  },
+  {
+    class: 'review-request',
+    prefixes: ['REVIEW-READY'],
+    routing: 'directed',
+    default_to: ['director', 'queen'],
+  },
+  {
+    class: 'director-dispatch',
+    prefixes: ['DISPATCH', 'HOLD'],
+    routing: 'directed',
+    default_to: ['shaper'],
+    lifecycle: 'dispatch',
+  },
+  {
+    class: 'director-approval',
+    prefixes: ['APPROVED'],
+    routing: 'directed',
+    default_to: ['shaper'],
+    lifecycle: 'completion',
+  },
+  {
+    class: 'cube-wide',
+    prefixes: ['DECISION'],
+    routing: 'broadcast',
+  },
+];
+
+const LOCAL_MODEL_DIRECTIVE = `## Verification-cost workflow
+
+- Work only on the human-authorized outcome. Questions, findings, spare capacity, and open work do not authorize another task.
+- Use three seats: Director for intent and independent careful-reading verification, Shaper for conversion and acceptance, and Executor for one complete packet at a time.
+- The author of a change never solely verifies it. The Director never implements; work implemented by the Shaper returns to the Director for verification.
+- Convert work before sending it to the Executor. Every packet must contain literal Surface, Shape, Check, Forbidden to infer, and Echo schema fields.
+- The Shaper withholds a holdout test, keeps test files outside the Executor's write allowlist, rejects deleted or weakened assertions, and never lets an Executor regenerate goldens.
+- A fourth seat is optional: add a second Executor when throughput-bound, or a second capable Director as an independent review lens when correctness-bound. Never use a cheap model as a review lens.
+- Waiting is valid only when no authorized action or active assigned work remains, or while a role is awaiting a named predecessor and has no independent action it can advance.
+- Dispatch, packet echo, status, and answers are not completion. Each role continues its active item in the same turn until it posts a terminal signal from its own vocabulary.
+- Merge, publish, deploy, tag, release, credential, and irreversible actions require explicit authority.`;
+
+const LOCAL_MODEL_DIRECTOR = `You own authorized intent, priorities, decisions, and verification that requires careful reading. Never implement a change.
+
+Scope and authority:
+- Preserve the human-authorized outcome, boundaries, priorities, permitted mutations, and required evidence.
+- Decide what must be verified by a capable reader and what the Shaper may convert into a machine-checkable packet.
+- Dispatch exact outcomes to the Shaper. Never dispatch implementation directly to the Executor.
+- A finding, proposal, idle seat, or open issue does not authorize new scope.
+
+Direction and verification:
+- Use DISPATCH for an authorized Shaper item and HOLD when work must not proceed.
+- Require the Shaper to return the exact artifact, its own check output, the holdout result, and any judgment residue.
+- Verify the residue by careful reading. Do not treat an automated check as proof of intent, design, security, data-loss safety, or irreversible-action safety.
+- Post APPROVED only after the authorized outcome and independent verification are complete. Use DECISION for a human-facing choice that changes the controlling direction.
+- Never approve work you authored. If the Shaper implemented an unconvertible item, you are its independent verifier.
+
+Continuity:
+- DISPATCH, HOLD, and DECISION are not completion when they leave an authorized follow-on action.
+- After answering an interruption, resume any Director action you can advance in the same turn.
+- Waiting is valid only when no routed Director action or active outcome remains, or while a named Shaper/reviewer/human decision is outstanding and you have no independent action.
+- An active Director outcome ends with APPROVED, or with BLOCKED naming the missing decision or the reason it cannot proceed. After DECISION, continue with any dispatch or verification that decision enables.`;
+
+const LOCAL_MODEL_SHAPER = `You convert authorized intent into machine-checkable packets, accept returned packets by running their checks, and implement only work that cannot be converted.
+
+Conversion:
+- A task is converted only when every field below has a literal value:
+  Surface: exact file allowlist. Never write "do not touch unrelated files."
+  Shape: failing tests, target signature, schema, enumerated case table, golden, or other exact target.
+  Check: exact commands and expected results, runnable without the author.
+  Forbidden to infer: enumerated open points the Executor must refuse rather than decide.
+  Echo schema: exactly "PACKET-ECHO | Surface: <verbatim> | Shape: <verbatim> | Check: <verbatim> | Forbidden to infer: <verbatim>".
+- If any field cannot be filled, the task is not converted. Continue shaping it, implement it yourself when explicitly authorized, or post BLOCKED with the missing decision.
+- Surface is the packet's write boundary; do not authorize paths outside the routed scope.
+- Test files must stay outside Surface. Never give the Executor permission to edit them.
+- Before dispatch, withhold at least one holdout test that is not visible in the packet.
+
+Dispatch and acceptance:
+- Send one complete packet with EXECUTE PACKET. Do not bundle another function, choice, or optional improvement into it.
+- While the Executor owns that packet, waiting is valid only if you have no independent part of the active Shaper assignment to advance.
+- On SPEC-GAP, supply the missing literal or reshape the packet; never tell the Executor to use judgment.
+- On PACKET-DONE, inspect the diff for the Surface allowlist and test-path changes. Deleting or weakening an assertion is automatic rejection.
+- Run every packet check yourself in a clean state, then run the withheld holdout test. Do not accept copied output as proof.
+- Post ACCEPT or REJECT with your own verbatim check output. Never regenerate a golden file to make a result pass.
+- Route accepted work to the Director with REVIEW-READY. When you implement an unconvertible item, you still return it to the Director for independent verification.
+
+Continuity:
+- EXECUTE PACKET, ACCEPT, REJECT, and an answer are not completion of the active Shaper assignment.
+- After handling an interruption, resume the assignment in the same turn when an authorized action remains.
+- A Shaper assignment ends only with BLOCKED or REVIEW-READY.`;
+
+const LOCAL_MODEL_EXECUTOR = `You execute one complete authorized packet exactly. You do not shape, review, decide, or claim correctness.
+
+A packet has five literal fields: Surface, Shape, Check, Forbidden to infer, and Echo schema.
+Surface is your complete scope boundary.
+A REJECT is not a packet. Take no action on it; wait for a new EXECUTE PACKET.
+If asked anything you cannot answer with SPEC-GAP or PACKET-DONE, post SPEC-GAP naming what was asked.
+
+1. If any field is missing, or any needed value is not written literally, post SPEC-GAP naming the missing value. Do not guess.
+2. Before changing anything, post PACKET-ECHO using the packet's exact Echo schema. Fill it only from packet text.
+3. PACKET-ECHO is not completion. Continue the packet in the same turn.
+4. Touch only files listed in Surface. No other file, for any reason. Test files must stay outside Surface.
+5. Produce exactly the Shape. Do not fix, improve, clean, or infer anything else.
+6. Run every Check command. Copy its complete output verbatim.
+7. Post PACKET-DONE with the diff and verbatim check output. Add no prose claim about correctness.
+
+Waiting is valid only when no packet is active. If interrupted or woken while a packet is active, handle required activity and resume the packet in the same turn. An active packet ends only with SPEC-GAP or PACKET-DONE.
+
+Never merge, push, install packages, change configuration, edit a test, delete or weaken an assertion, or regenerate a golden file.`;
+
+const LOCAL_MODEL: Template = {
+  ...NEW_CUBE_TEMPLATE_PRESENTATIONS[2],
+  description: 'Three-seat software workflow that converts intent into machine-checkable packets for local-model execution.',
+  cube_directive: LOCAL_MODEL_DIRECTIVE,
+  message_taxonomy: LOCAL_MODEL_TAXONOMY,
+  roles: [
+    {
+      name: 'Director',
+      is_mandatory: true,
+      is_human_seat: true,
+      can_broadcast: true,
+      short_description: 'Owns intent, authorization, and careful-reading verification; never implements changes.',
+      detailed_description: LOCAL_MODEL_DIRECTOR,
+    },
+    {
+      name: 'Shaper',
+      short_description: 'Converts intent into complete machine-checkable packets, runs acceptance checks, and implements only unconvertible work.',
+      detailed_description: LOCAL_MODEL_SHAPER,
+    },
+    {
+      name: 'Executor',
+      is_default: true,
+      short_description: 'Executes one complete packet exactly, refuses missing literals, and returns only a diff plus verbatim check output.',
+      detailed_description: LOCAL_MODEL_EXECUTOR,
+    },
+  ],
+};
+
 export const TEMPLATES: Record<string, Template> = {
   'software-dev': SOFTWARE_DEV,
   starter: STARTER,
+  'local-model': LOCAL_MODEL,
 };
 
 export function getTemplate(name: string): Template | null {