@afokapu/atdd-flow 0.3.33 → 0.3.34

package/conventions/atdd-flow.collaboration/atdd-flow.collaboration.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.0.0
+rule_id: atdd-flow.collaboration
+kind: policy
+status: active
+name: Collaborate through durable accountable delegation
+statement: >-
+  Agents use accountable delegation, evidence-based escalation, economical delivery,
+  and bounded two-way resolution while keeping work within its assigned project and task.
+content:
+  canonical_policy: >-
+    Delegation flows operator → main → named coordinator → driver. Each level proactively
+    dispatches safe independent work, verifies durable delivery and visible execution, and
+    escalates material blockers upward with exact evidence, an economical recommendation,
+    viable alternatives and tradeoffs, and safe work that can continue. Choose the smallest
+    non-duplicative compliant implementation; do not skip lifecycle or gates. Use bounded
+    two-way evidence dialogue with the responsible actor to resolve assumptions or
+    disagreement; time-box it and escalate only unresolved decisions. Distinguish persisted,
+    delivered, acknowledged, awaiting actor, and executing. Never infer authorization or
+    restart productive sessions merely to relay policy. Proactive next-task discovery stays
+    within the same project. Keep one bounded active task and worktree per driver; assign
+    adjacent work separately. Cross-project dialogue is only for a real dependency or
+    interface through counterpart authority. Prefer atomic assignment; unassigned work needs
+    a project-main decision proposal with purpose, priority, recommended assignee,
+    alternatives, consequences, dependencies, and safe work meanwhile. Promptly complete,
+    supersede, reject, or time-bound defer work. Coordinating actors reconcile their durable
+    inbox as the first action at every session, turn, and task resumption, and after every
+    bounded action, phase completion, or wait before the next action. An actionable
+    expects_result remains visible until answered, executed, delegated with verified delivery
+    and follow-up, or explicitly deferred, superseded, or closed. Messages only communicate,
+    evidence, consensus, authorization, or status; they never request executable work unless it
+    references an existing assigned task. Tasks define, assign, execute, evidence, and complete
+    work; every code or repository mutation requires that task first. The operator accepts and
+    receipts inbound communication from any seat, but sends substantive direction, results, and
+    wakes only to main@project. Only main@project executes that project repository merge; the
+    operator may authorize, relay, or inspect but never merges.
+  projection: >-
+    Keep this full policy only in this convention. Managed AGENTS.md and CLAUDE.md blocks
+    contain only its canonical pointer and preserve all user-authored content outside the
+    marked block.
+metadata:
+  aliases:
+    - ATDD-FLOW-COLLABORATION
+implementation:
+  type: source-resolved

package/extensions/pi/index.ts

@@ -6,6 +6,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
 import { paths, readYaml, type Seat } from "../../src/core";
 import { directiveNotice, nextDirective } from "../../src/tasks";
+import { runtimeStartupInstruction } from "../../src/collaboration-policy";
 
 type Thread = { id?: unknown; participants?: unknown; subject?: unknown };
 export type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown; created_at?: unknown };
@@ -63,7 +64,6 @@ const defaultHeartbeatMs = 15_000;
 const defaultStaleAfterMs = 60_000;
 const defaultActivationIntervalMs = 25;
 const defaultActivationTimeoutMs = 60_000;
-const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
 function participants(thread: Thread) {
   return Array.isArray(thread.participants) && thread.participants.every((entry) => typeof entry === "string") ? thread.participants as string[] : [];
@@ -358,7 +358,7 @@ export default function (pi: ExtensionAPI) {
       root, seat, piSession, herdrSession, pane,
       activate: async () => {
         if (!await current.activate()) return;
-        pi.sendMessage({ customType: "atdd-flow-start", content: `SYSTEM: you are ${seat}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Convention: ${lifecycleConventionPath}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
+        pi.sendMessage({ customType: "atdd-flow-start", content: runtimeStartupInstruction(seat), display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
         await sendTaskDirective(pi, root, seat);
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.33",
+  "version": "0.3.34",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/collaboration-policy.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+export const collaborationConventionPath = "conventions/atdd-flow.collaboration/atdd-flow.collaboration.convention.yaml";
+const startMarker = "<!-- atdd-flow:collaboration-policy:start -->";
+const endMarker = "<!-- atdd-flow:collaboration-policy:end -->";
+export const collaborationPolicyPointer = `ATDD Flow collaboration policy: node_modules/@afokapu/atdd-flow/${collaborationConventionPath} (source checkout: ${collaborationConventionPath})`;
+
+type Convention = { content?: { canonical_policy?: unknown } };
+
+function conventionFile() {
+  return join(import.meta.dir, "..", collaborationConventionPath);
+}
+
+/** The convention is the sole policy text; projections and runtimes resolve it from here. */
+export function canonicalCollaborationPolicy() {
+  const convention = parse(readFileSync(conventionFile(), "utf8")) as Convention;
+  const policy = convention.content?.canonical_policy;
+  if (typeof policy !== "string" || !policy.trim()) throw new Error("Collaboration convention requires content.canonical_policy.");
+  return policy.trim();
+}
+
+function block() {
+  return `${startMarker}\n${collaborationPolicyPointer}\n${endMarker}\n`;
+}
+
+function escaped(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const existingBlock = new RegExp(`${escaped(startMarker)}\\r?\\n[\\s\\S]*?${escaped(endMarker)}(?:\\r?\\n)?`, "g");
+
+/** Replaces every prior managed block with one canonical pointer while retaining all other bytes. */
+export function projectCollaborationPolicyText(source: string) {
+  const matches = [...source.matchAll(existingBlock)];
+  if (matches.length) {
+    const first = matches[0]!;
+    const before = source.slice(0, first.index);
+    const after = source.slice((first.index ?? 0) + first[0].length).replace(existingBlock, "");
+    return `${before}${block()}${after}`;
+  }
+  if (!source) return block();
+  return `${source}${source.endsWith("\n") ? "\n" : "\n\n"}${block()}`;
+}
+
+function lineCount(text: string) {
+  return text ? text.replace(/\r?\n$/, "").split(/\r?\n/).length : 0;
+}
+
+/** Idempotently projects the canonical pointer while preserving user content and refusing oversized instruction files. */
+export async function projectCollaborationPolicy(root: string) {
+  const projections = await Promise.all(["AGENTS.md", "CLAUDE.md"].map(async (name) => {
+    const file = join(root, name);
+    let source = "";
+    try { source = await readFile(file, "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    return { name, file, source, next: projectCollaborationPolicyText(source) };
+  }));
+  for (const { name, source, next } of projections) {
+    if (lineCount(source) > 20 || lineCount(next) > 20) {
+      throw new Error(`${name} exceeds the 20-line cap; refusing projection without changing user content.`);
+    }
+  }
+  await Promise.all(projections.map(async ({ file, source, next }) => {
+    if (next !== source) await writeFile(file, next, "utf8");
+  }));
+}
+
+/** The one startup handoff for supported Flow-managed runtimes, resolved from the canonical convention. */
+export function runtimeStartupInstruction(seat: string) {
+  return `SYSTEM: you are ${seat}. Collaboration policy: ${canonicalCollaborationPolicy()} Canonical convention: ${collaborationConventionPath}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
+}

package/src/seats.ts

@@ -13,6 +13,7 @@ import { seatTasks } from "./tasks";
 import { misplacedSeats, projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
+import { projectCollaborationPolicy } from "./collaboration-policy";
 
 const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
@@ -51,6 +52,7 @@ export async function init(root: string, name: string, args: string[]) {
   const config = { schema: "atdd-workflow/desk/v1" as const, desk: name, application: "herdr", executables: defaultExecutables() };
   await Promise.all([mkdir(paths(root).work, { recursive: true }), mkdir(paths(root).threads, { recursive: true })]);
   await Promise.all([atomicYaml(paths(root).desk, config), atomicYaml(paths(root).models, defaultModels())]);
+  await projectCollaborationPolicy(root);
   if (args.includes("--git") && !await exists(join(root, ".git"))) await run(["git", "init", "--initial-branch=main", root]);
   console.log(`Initialized Desk ${root}`);
 }
@@ -58,6 +60,7 @@ export async function init(root: string, name: string, args: string[]) {
 export async function migrate(root: string) {
   if (await migrateDesk(root)) console.log("Migrated legacy coordination registry to desk.yaml");
   else console.log("Desk registry already exists");
+  await projectCollaborationPolicy(root);
 }
 
 export async function initProject(root: string, name: string) {