@etiquekit/etq 1.0.14 → 1.0.15

package/packages/protocol/src/huddle-board.ts

@@ -1,198 +0,0 @@
-import { z } from 'zod';
-import {
-  HUDDLE_CARD_MODES,
-  HuddleCardV1Schema,
-  HuddleExitReceiptV1Schema,
-  type HuddleCardV1,
-  type HuddleExitReceiptV1,
-} from './huddle';
-
-export const HUDDLE_BOARD_STATUSES = [
-  'ready',
-  'claimed',
-  'in_progress',
-  'waiting_return',
-  'accepted',
-  'blocked',
-  'stale',
-] as const;
-
-export type HuddleBoardStatus = (typeof HUDDLE_BOARD_STATUSES)[number];
-
-const nonEmptyString = z.string().trim().min(1);
-export const HUDDLE_BOARD_GENERATED_NOTICE =
-  'This is a read replica. Do not hand-edit; update source cards or receipts and regenerate.' as const;
-
-export const HuddleBoardItemV1Schema = z.object({
-  key: nonEmptyString,
-  repo: nonEmptyString,
-  lane: nonEmptyString,
-  task_id: nonEmptyString,
-  mode: z.enum(HUDDLE_CARD_MODES),
-  status: z.enum(HUDDLE_BOARD_STATUSES),
-  card_status: z.enum(HUDDLE_BOARD_STATUSES),
-  current_owner: nonEmptyString,
-  next_owner: nonEmptyString,
-  card_ref: nonEmptyString.optional(),
-  receipt_ref: nonEmptyString.optional(),
-  receipt_verdict: z.enum(['accept', 'counter', 'blocked']).optional(),
-  stale_reason: nonEmptyString.optional(),
-  evidence_refs: z.array(nonEmptyString).default([]),
-});
-
-export const HuddleBoardV1Schema = z.object({
-  schema_version: z.literal('huddle-board.v1'),
-  generated_notice: z.literal(HUDDLE_BOARD_GENERATED_NOTICE),
-  generated_at: nonEmptyString,
-  summary: z.record(z.enum(HUDDLE_BOARD_STATUSES), z.number().int().min(0)),
-  items: z.array(HuddleBoardItemV1Schema),
-});
-
-export type HuddleBoardItemV1 = z.infer<typeof HuddleBoardItemV1Schema>;
-export type HuddleBoardV1 = z.infer<typeof HuddleBoardV1Schema>;
-
-export type HuddleCardRef = {
-  card: HuddleCardV1;
-  ref?: string;
-};
-
-export type HuddleReceiptRef = {
-  receipt: HuddleExitReceiptV1;
-  ref?: string;
-};
-
-function taskKey(repo: string, lane: string, taskId: string): string {
-  return `${repo}::${lane}::${taskId}`;
-}
-
-function isExpired(value: string, now: Date): boolean {
-  const parsed = Date.parse(value);
-  return Number.isFinite(parsed) && parsed < now.getTime();
-}
-
-function emptySummary(): Record<HuddleBoardStatus, number> {
-  return {
-    ready: 0,
-    claimed: 0,
-    in_progress: 0,
-    waiting_return: 0,
-    accepted: 0,
-    blocked: 0,
-    stale: 0,
-  };
-}
-
-export function buildHuddleBoardV1(input: {
-  cards: HuddleCardRef[];
-  receipts?: HuddleReceiptRef[];
-  generated_at?: string;
-  now?: Date;
-}): HuddleBoardV1 {
-  const now = input.now ?? new Date(input.generated_at ?? Date.now());
-  const generatedAt = input.generated_at ?? now.toISOString();
-  const receiptsByKey = new Map<string, HuddleReceiptRef>();
-
-  for (const candidate of input.receipts ?? []) {
-    const receipt = HuddleExitReceiptV1Schema.parse(candidate.receipt);
-    receiptsByKey.set(taskKey(receipt.repo, receipt.lane, receipt.task_id), {
-      receipt,
-      ref: candidate.ref,
-    });
-  }
-
-  const items: HuddleBoardItemV1[] = input.cards.map((candidate) => {
-    const card = HuddleCardV1Schema.parse(candidate.card);
-    const key = taskKey(card.repo, card.lane, card.task_id);
-    const receiptRef = receiptsByKey.get(key);
-    const expired = isExpired(card.expires_or_refresh_after, now);
-
-    let status: HuddleBoardStatus = card.status;
-    let staleReason: string | undefined;
-    const evidenceRefs: string[] = [];
-
-    if (receiptRef) {
-      status = receiptRef.receipt.verdict === 'accept' ? 'accepted' : 'blocked';
-      evidenceRefs.push(receiptRef.receipt.source_ref, ...receiptRef.receipt.evidence);
-    } else if (expired && card.status !== 'accepted' && card.status !== 'blocked') {
-      status = 'stale';
-      staleReason = `expired after ${card.expires_or_refresh_after}`;
-    }
-
-    return HuddleBoardItemV1Schema.parse({
-      key,
-      repo: card.repo,
-      lane: card.lane,
-      task_id: card.task_id,
-      mode: card.mode,
-      status,
-      card_status: card.status,
-      current_owner: card.current_owner,
-      next_owner: receiptRef?.receipt.next_owner ?? card.next_owner,
-      card_ref: candidate.ref,
-      receipt_ref: receiptRef?.ref,
-      receipt_verdict: receiptRef?.receipt.verdict,
-      stale_reason: staleReason,
-      evidence_refs: evidenceRefs,
-    });
-  }).sort((left, right) => left.key.localeCompare(right.key));
-
-  const summary = emptySummary();
-  for (const item of items) {
-    summary[item.status] += 1;
-  }
-
-  return HuddleBoardV1Schema.parse({
-    schema_version: 'huddle-board.v1',
-    generated_notice: HUDDLE_BOARD_GENERATED_NOTICE,
-    generated_at: generatedAt,
-    summary,
-    items,
-  });
-}
-
-export function stableHuddleBoardFingerprint(board: HuddleBoardV1): string {
-  return JSON.stringify({
-    schema_version: board.schema_version,
-    generated_notice: board.generated_notice,
-    summary: board.summary,
-    items: board.items.map((item) => ({
-      key: item.key,
-      status: item.status,
-      current_owner: item.current_owner,
-      next_owner: item.next_owner,
-      receipt_verdict: item.receipt_verdict,
-      stale_reason: item.stale_reason,
-    })),
-  });
-}
-
-export function renderHuddleBoardMarkdown(board: HuddleBoardV1): string {
-  const lines = [
-    '# Huddle Board',
-    '',
-    `> ${board.generated_notice}`,
-    '',
-    `Generated: ${board.generated_at}`,
-    '',
-    '| Status | Count |',
-    '| --- | ---: |',
-    ...HUDDLE_BOARD_STATUSES.map((status) => `| ${status} | ${board.summary[status]} |`),
-    '',
-    '| Task | Repo | Lane | Status | Owner | Next | Receipt |',
-    '| --- | --- | --- | --- | --- | --- | --- |',
-  ];
-
-  for (const item of board.items) {
-    lines.push([
-      item.task_id,
-      item.repo,
-      item.lane,
-      item.status,
-      item.current_owner,
-      item.next_owner,
-      item.receipt_ref ?? '',
-    ].map((value) => String(value).replaceAll('|', '\\|')).join(' | ').replace(/^/, '| ').replace(/$/, ' |'));
-  }
-
-  return `${lines.join('\n')}\n`;
-}

package/packages/protocol/src/huddle.ts

@@ -1,295 +0,0 @@
-import { z } from 'zod';
-
-export const HUDDLE_CARD_MODES = ['read-only', 'docs-only', 'implementation', 'review'] as const;
-export const HUDDLE_CARD_STATUSES = [
-  'ready',
-  'claimed',
-  'in_progress',
-  'waiting_return',
-  'accepted',
-  'blocked',
-  'stale',
-] as const;
-export const HUDDLE_EXIT_RECEIPT_VERDICTS = ['accept', 'counter', 'blocked'] as const;
-export const PORTABLE_EXIT_RECEIPT_OUTCOMES = ['success', 'partial', 'blocked'] as const;
-
-export type HuddleCardMode = (typeof HUDDLE_CARD_MODES)[number];
-export type HuddleCardStatus = (typeof HUDDLE_CARD_STATUSES)[number];
-export type HuddleExitReceiptVerdict = (typeof HUDDLE_EXIT_RECEIPT_VERDICTS)[number];
-export type PortableExitReceiptOutcome = (typeof PORTABLE_EXIT_RECEIPT_OUTCOMES)[number];
-
-const nonEmptyString = z.string().trim().min(1);
-
-const stringList = z.array(nonEmptyString);
-const validationEntry = z.union([
-  nonEmptyString,
-  z.object({
-    command: nonEmptyString,
-    result: nonEmptyString,
-  }).passthrough(),
-]);
-
-function looksLikeChatMemoryPath(value: string): boolean {
-  const normalized = value.toLowerCase();
-  return (
-    normalized.includes('chat-history') ||
-    normalized.includes('chat_history') ||
-    normalized.includes('chatlog') ||
-    normalized.includes('chat-memory') ||
-    normalized.includes('conversation-log') ||
-    normalized.includes('transcript')
-  );
-}
-
-export const HuddleCardV1Schema = z.object({
-  schema_version: z.literal('huddle-card.v1'),
-  repo: nonEmptyString,
-  repo_path: nonEmptyString.optional(),
-  lane: nonEmptyString,
-  task_id: nonEmptyString,
-  mode: z.enum(HUDDLE_CARD_MODES),
-  status: z.enum(HUDDLE_CARD_STATUSES).default('ready'),
-  startup_docs: stringList.min(1),
-  task_packet: nonEmptyString.optional(),
-  allowed_writes: stringList,
-  forbidden_sources: stringList,
-  validation: stringList.min(1),
-  stop_conditions: stringList.min(1),
-  expected_return: stringList.min(1),
-  evidence_sink: nonEmptyString.optional(),
-  current_owner: nonEmptyString,
-  next_owner: nonEmptyString,
-  expires_or_refresh_after: nonEmptyString,
-}).superRefine((card, ctx) => {
-  for (const [index, source] of card.startup_docs.entries()) {
-    if (looksLikeChatMemoryPath(source)) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['startup_docs', index],
-        message: 'startup_docs must point to repo-local source of truth, not chat logs or transcripts',
-      });
-    }
-  }
-
-  const forbiddenText = card.forbidden_sources.join(' ').toLowerCase();
-  if (!forbiddenText.includes('chat') && !forbiddenText.includes('transcript')) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['forbidden_sources'],
-      message: 'forbidden_sources should explicitly ban chat/transcript memory for rotation-safe pickup',
-    });
-  }
-
-  if (card.mode === 'implementation') {
-    const usefulWrites = card.allowed_writes.filter((entry) => entry !== 'read-only');
-    if (usefulWrites.length === 0) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['allowed_writes'],
-        message: 'implementation cards must declare concrete allowed_writes',
-      });
-    }
-  }
-});
-
-export type HuddleCardV1 = z.infer<typeof HuddleCardV1Schema>;
-
-export const HuddleExitReceiptV1Schema = z.object({
-  schema_version: z.literal('huddle-exit-receipt.v1'),
-  task_id: nonEmptyString,
-  verdict: z.enum(HUDDLE_EXIT_RECEIPT_VERDICTS),
-  repo: nonEmptyString,
-  lane: nonEmptyString,
-  source_ref: nonEmptyString,
-  changed_files: z.array(nonEmptyString).default([]),
-  validation: z.array(nonEmptyString).default([]),
-  evidence: stringList.min(1),
-  blockers: z.array(nonEmptyString).default([]),
-  next_owner: nonEmptyString,
-  refresh_after: nonEmptyString,
-}).superRefine((receipt, ctx) => {
-  if (looksLikeChatMemoryPath(receipt.source_ref)) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['source_ref'],
-      message: 'source_ref must point to a durable task packet, commit, issue, bus event, or repo-local receipt; not chat logs or transcripts',
-    });
-  }
-
-  for (const [index, evidence] of receipt.evidence.entries()) {
-    if (looksLikeChatMemoryPath(evidence)) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['evidence', index],
-        message: 'evidence must be repo-local or packet-local durable proof, not chat logs or transcripts',
-      });
-    }
-  }
-
-  if (receipt.verdict !== 'accept' && receipt.blockers.length === 0) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['blockers'],
-      message: 'counter and blocked receipts must name at least one blocker',
-    });
-  }
-});
-
-export type HuddleExitReceiptV1 = z.infer<typeof HuddleExitReceiptV1Schema>;
-
-export const PortableExitReceiptV1Schema = z.object({
-  schema_version: z.literal('exit-receipt.v1'),
-  receipt_id: nonEmptyString,
-  work_id: nonEmptyString,
-  outcome: z.enum(PORTABLE_EXIT_RECEIPT_OUTCOMES),
-  changed_files: z.array(nonEmptyString).default([]),
-  validation: z.array(validationEntry).default([]),
-  evidence_refs: stringList.min(1),
-  stop_conditions: stringList.min(1),
-  deferred_work: z.array(nonEmptyString).default([]),
-  next_owner: nonEmptyString,
-}).superRefine((receipt, ctx) => {
-  for (const [index, evidence] of receipt.evidence_refs.entries()) {
-    if (looksLikeChatMemoryPath(evidence)) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['evidence_refs', index],
-        message: 'evidence_refs must be durable proof, not chat logs or transcripts',
-      });
-    }
-  }
-});
-
-export type PortableExitReceiptV1 = z.infer<typeof PortableExitReceiptV1Schema>;
-
-export function parseHuddleCardV1(value: unknown): HuddleCardV1 {
-  return HuddleCardV1Schema.parse(value);
-}
-
-export function validateHuddleCardV1(value: unknown): void {
-  HuddleCardV1Schema.parse(value);
-}
-
-export function parseHuddleExitReceiptV1(value: unknown): HuddleExitReceiptV1 {
-  return HuddleExitReceiptV1Schema.parse(value);
-}
-
-export function validateHuddleExitReceiptV1(value: unknown): void {
-  HuddleExitReceiptV1Schema.parse(value);
-}
-
-export function parsePortableExitReceiptV1(value: unknown): PortableExitReceiptV1 {
-  return PortableExitReceiptV1Schema.parse(value);
-}
-
-export function validatePortableExitReceiptV1(value: unknown): void {
-  PortableExitReceiptV1Schema.parse(value);
-}
-
-function huddleVerdictToPortableOutcome(verdict: HuddleExitReceiptVerdict): PortableExitReceiptOutcome {
-  if (verdict === 'accept') {
-    return 'success';
-  }
-  if (verdict === 'counter') {
-    return 'partial';
-  }
-  return 'blocked';
-}
-
-function portableOutcomeToHuddleVerdict(outcome: PortableExitReceiptOutcome): HuddleExitReceiptVerdict {
-  if (outcome === 'success') {
-    return 'accept';
-  }
-  if (outcome === 'partial') {
-    return 'counter';
-  }
-  return 'blocked';
-}
-
-function renderValidationEntry(entry: PortableExitReceiptV1['validation'][number]): string {
-  if (typeof entry === 'string') {
-    return entry;
-  }
-  return `${entry.command} -> ${entry.result}`;
-}
-
-export function toPortableExitReceiptV1(
-  receipt: HuddleExitReceiptV1,
-  receiptId = `${receipt.task_id}-exit-receipt`,
-): PortableExitReceiptV1 {
-  return PortableExitReceiptV1Schema.parse({
-    schema_version: 'exit-receipt.v1',
-    receipt_id: receiptId,
-    work_id: receipt.task_id,
-    outcome: huddleVerdictToPortableOutcome(receipt.verdict),
-    changed_files: receipt.changed_files,
-    validation: receipt.validation,
-    evidence_refs: [receipt.source_ref, ...receipt.evidence],
-    stop_conditions: receipt.blockers.length > 0 ? receipt.blockers : ['none fired'],
-    deferred_work: [],
-    next_owner: receipt.next_owner,
-  });
-}
-
-export function toHuddleExitReceiptV1(
-  receipt: PortableExitReceiptV1,
-  context: {
-    repo: string;
-    lane: string;
-    source_ref?: string;
-    refresh_after?: string;
-  },
-): HuddleExitReceiptV1 {
-  const blockers = receipt.outcome === 'success'
-    ? []
-    : [...receipt.stop_conditions, ...receipt.deferred_work].filter((entry) => entry !== 'none fired');
-
-  return HuddleExitReceiptV1Schema.parse({
-    schema_version: 'huddle-exit-receipt.v1',
-    task_id: receipt.work_id,
-    verdict: portableOutcomeToHuddleVerdict(receipt.outcome),
-    repo: context.repo,
-    lane: context.lane,
-    source_ref: context.source_ref ?? receipt.evidence_refs[0],
-    changed_files: receipt.changed_files,
-    validation: receipt.validation.map(renderValidationEntry),
-    evidence: receipt.evidence_refs,
-    blockers,
-    next_owner: receipt.next_owner,
-    refresh_after: context.refresh_after ?? 'after repo-local state changes',
-  });
-}
-
-export function summarizeHuddleCard(card: HuddleCardV1): string {
-  return [
-    `${card.task_id} [${card.status}/${card.mode}]`,
-    `repo=${card.repo}`,
-    `lane=${card.lane}`,
-    `owner=${card.current_owner}`,
-    `next=${card.next_owner}`,
-    `startup_docs=${card.startup_docs.length}`,
-    `validation=${card.validation.length}`,
-  ].join(' ');
-}
-
-export function summarizeHuddleExitReceipt(receipt: HuddleExitReceiptV1): string {
-  return [
-    `${receipt.task_id} [${receipt.verdict}]`,
-    `repo=${receipt.repo}`,
-    `lane=${receipt.lane}`,
-    `source=${receipt.source_ref}`,
-    `changed_files=${receipt.changed_files.length}`,
-    `validation=${receipt.validation.length}`,
-    `next=${receipt.next_owner}`,
-  ].join(' ');
-}
-
-export function summarizePortableExitReceipt(receipt: PortableExitReceiptV1): string {
-  return [
-    `${receipt.work_id} [${receipt.outcome}]`,
-    `receipt=${receipt.receipt_id}`,
-    `changed_files=${receipt.changed_files.length}`,
-    `validation=${receipt.validation.length}`,
-    `next=${receipt.next_owner}`,
-  ].join(' ');
-}