@orchestrator-claude/definitions 3.31.1 → 3.32.0

package/hooks/mailbox-listener.ts

@@ -20,15 +20,24 @@
  *   - Backward compat: if process.stdin.isTTY → skip stdin read (PostToolUse path)
  */
 
-import { readdirSync, readFileSync, unlinkSync, renameSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
-import { log, outputContext } from "./lib/api-client.js";
-
-const HOOK = "MAILBOX-LISTENER";
+import {
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  renameSync,
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { log, outputContext } from './lib/api-client.js';
+
+const HOOK = 'MAILBOX-LISTENER';
 
 // --- Types (minimal, no Zod dependency in hooks) ---
 
-interface MailboxMessage {
+export interface MailboxMessage {
   id: string;
   from: { role: string; index: number };
   to: { role: string; index: number };
@@ -53,7 +62,7 @@ async function readStdinPayload(): Promise<Record<string, unknown>> {
   for await (const chunk of process.stdin) {
     chunks.push(chunk as Buffer);
   }
-  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  const raw = Buffer.concat(chunks).toString('utf-8').trim();
   if (!raw) return {};
   try {
     return JSON.parse(raw) as Record<string, unknown>;
@@ -67,13 +76,13 @@ async function readStdinPayload(): Promise<Record<string, unknown>> {
 function consumeInbox(
   inboxPath: string,
   quarantinePath: string,
-  paneRole: string,
+  paneRole: string
 ): { consumed: MailboxMessage[]; errors: string[] } {
   // List .json files (exclude .tmp- in-flight writes)
   let files: string[];
   try {
     files = readdirSync(inboxPath)
-      .filter((f) => f.endsWith(".json") && !f.startsWith(".tmp-"))
+      .filter((f) => f.endsWith('.json') && !f.startsWith('.tmp-'))
       .sort(); // FIFO by filename (UUID-based, but sorted for determinism)
   } catch {
     return { consumed: [], errors: [] }; // Directory read error — fail silently
@@ -91,7 +100,7 @@ function consumeInbox(
   for (const file of files) {
     const filePath = join(inboxPath, file);
     try {
-      const raw = readFileSync(filePath, "utf-8");
+      const raw = readFileSync(filePath, 'utf-8');
       const parsed = JSON.parse(raw) as MailboxMessage;
 
       // Basic validation (no Zod in hooks — keep deps minimal)
@@ -102,7 +111,10 @@ function consumeInbox(
       // Consume: delete after successful parse
       unlinkSync(filePath);
       consumed.push(parsed);
-      log(HOOK, `Consumed: ${parsed.id} (${parsed.body.type} from ${parsed.from.role}-${parsed.from.index})`);
+      log(
+        HOOK,
+        `Consumed: ${parsed.id} (${parsed.body.type} from ${parsed.from.role}-${parsed.from.index})`
+      );
     } catch (err) {
       // Quarantine malformed message
       const errMsg = err instanceof Error ? err.message : String(err);
@@ -125,23 +137,21 @@ function consumeInbox(
 function buildContext(
   consumed: MailboxMessage[],
   errors: string[],
-  paneRole: string,
+  paneRole: string
 ): string | null {
   if (consumed.length === 0 && errors.length === 0) {
     return null;
   }
 
-  const parts: string[] = [
-    `[MAILBOX] ${consumed.length} new message(s) for ${paneRole}:`,
-  ];
+  const parts: string[] = [`[MAILBOX] ${consumed.length} new message(s) for ${paneRole}:`];
 
   for (const msg of consumed) {
     const from = `${msg.from.role}-${msg.from.index}`;
-    parts.push("");
+    parts.push('');
     parts.push(`--- Message from ${from} (${msg.body.type}) ---`);
 
     switch (msg.body.type) {
-      case "task_assignment":
+      case 'task_assignment':
         parts.push(`Task: ${msg.body.taskId}`);
         parts.push(`Title: ${msg.body.title}`);
         if (msg.body.description) parts.push(`Description: ${msg.body.description}`);
@@ -153,28 +163,28 @@ function buildContext(
         }
         break;
 
-      case "task_complete":
+      case 'task_complete':
         parts.push(`Task: ${msg.body.taskId}`);
         parts.push(`Summary: ${msg.body.summary}`);
         break;
 
-      case "status_update":
+      case 'status_update':
         parts.push(`Task: ${msg.body.taskId}`);
         parts.push(`Progress: ${msg.body.progress}%`);
         parts.push(`Status: ${msg.body.message}`);
         break;
 
-      case "error_report":
+      case 'error_report':
         parts.push(`Error: ${msg.body.errorCode}`);
         parts.push(`Message: ${msg.body.message}`);
         if (msg.body.taskId) parts.push(`Task: ${msg.body.taskId}`);
         break;
 
-      case "ping":
+      case 'ping':
         parts.push(`Ping received — respond with pong if appropriate.`);
         break;
 
-      case "pong":
+      case 'pong':
         parts.push(`Pong received — heartbeat confirmed.`);
         break;
 
@@ -185,14 +195,113 @@ function buildContext(
   }
 
   if (errors.length > 0) {
-    parts.push("");
+    parts.push('');
     parts.push(`[MAILBOX-WARN] ${errors.length} malformed message(s) quarantined:`);
     for (const e of errors) {
       parts.push(`  - ${e}`);
     }
   }
 
-  return parts.join("\n");
+  return parts.join('\n');
+}
+
+// --- Sidecar relay helpers (exported for testability, raw node:fs only) ---
+
+/** Injectable deps interface for enumerateSidecarAddresses (enables unit testing without real fs). */
+export interface SidecarRelayDeps {
+  readdirSync: (path: string) => string[];
+  writeFileSync: (path: string, data: string, encoding: BufferEncoding) => void;
+}
+
+/**
+ * Known sidecar roles (RFC-025 RoleSchema). Used as allowlist in enumerateSidecarAddresses
+ * to prevent path-traversal from crafted registry filenames and to guarantee valid role values.
+ */
+const SIDECAR_ROLE_ALLOWLIST: ReadonlySet<string> = new Set([
+  'debug-sidecar',
+  'test-sidecar',
+  'doc-sidecar',
+]);
+
+/**
+ * Reads registry filenames and returns sidecar addresses (role + index).
+ * Reads filenames only — never parses registry JSON content.
+ * Returns [] on ENOENT or any read error (best-effort).
+ * Only returns entries whose role is in SIDECAR_ROLE_ALLOWLIST (path-traversal defense).
+ */
+export function enumerateSidecarAddresses(
+  sprintId: string,
+  deps: SidecarRelayDeps = { readdirSync, writeFileSync }
+): { role: string; index: number }[] {
+  const registryDir = `/tmp/${sprintId}/registry`;
+  let files: string[];
+  try {
+    files = deps.readdirSync(registryDir);
+  } catch {
+    return [];
+  }
+  const results: { role: string; index: number }[] = [];
+  for (const filename of files) {
+    if (!filename.endsWith('.json')) continue;
+    const base = filename.slice(0, -5); // strip .json
+    if (!base.includes('sidecar')) continue;
+    const lastDash = base.lastIndexOf('-');
+    if (lastDash === -1) continue;
+    const indexStr = base.slice(lastDash + 1);
+    const index = parseInt(indexStr, 10);
+    if (isNaN(index)) continue;
+    const role = base.slice(0, lastDash);
+    // Allowlist: only accept known sidecar roles (prevents path-traversal, guarantees RoleSchema validity)
+    if (!SIDECAR_ROLE_ALLOWLIST.has(role)) continue;
+    results.push({ role, index });
+  }
+  return results;
+}
+
+/**
+ * Relays task_complete messages from consumed list to each sidecar inbox.
+ * Best-effort: per-sidecar try/catch — one failure does not block others.
+ * Only task_complete messages trigger relay (RF-001).
+ * Only runs when paneRole belongs to the orchestrator (role component === 'orchestrator').
+ */
+export function relaySidecarMessages(
+  consumed: MailboxMessage[],
+  sprintId: string,
+  paneRole: string,
+  deps: SidecarRelayDeps = { readdirSync, writeFileSync }
+): void {
+  // Guard: only the orchestrator pane relays messages (prevents duplicate relay from other panes)
+  const roleComponent = paneRole.slice(0, paneRole.lastIndexOf('-'));
+  if (roleComponent !== 'orchestrator') return;
+
+  const taskCompletes = consumed.filter((m) => m.body.type === 'task_complete');
+  if (taskCompletes.length === 0) return;
+
+  const sidecars = enumerateSidecarAddresses(sprintId, deps);
+  if (sidecars.length === 0) return;
+
+  for (const msg of taskCompletes) {
+    for (const sidecar of sidecars) {
+      try {
+        const envelope = {
+          id: randomUUID(),
+          from: { role: 'orchestrator', index: 0 },
+          to: { role: sidecar.role, index: sidecar.index },
+          timestamp: new Date().toISOString(),
+          body: msg.body,
+        };
+        const sidecarAddr = `${sidecar.role}-${String(sidecar.index)}`;
+        const targetInbox = `/tmp/${sprintId}/mailbox/${sidecarAddr}/inbox`;
+        const targetPath = join(targetInbox, `${envelope.id}.json`);
+        deps.writeFileSync(targetPath, JSON.stringify(envelope), 'utf-8');
+        log(HOOK, `Relayed task_complete to ${sidecarAddr}: ${envelope.id}`);
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log(HOOK, `Relay failed for ${sidecar.role}-${String(sidecar.index)}: ${errMsg}`);
+        // Best-effort: continue to next sidecar
+      }
+    }
+  }
 }
 
 // --- Main ---
@@ -232,6 +341,9 @@ async function main(): Promise<void> {
     return;
   }
 
+  // Relay task_complete to sidecar inboxes (best-effort, RFC-025 TD-135)
+  relaySidecarMessages(consumed, sprintId, paneRole);
+
   // Build context string
   const context = buildContext(consumed, errors, paneRole);
   if (!context) {
@@ -239,8 +351,10 @@ async function main(): Promise<void> {
   }
 
   // Emit context with the appropriate hook event name
-  const effectiveEvent = hookEventName === "SessionStart" ? "SessionStart" : "PostToolUse";
+  const effectiveEvent = hookEventName === 'SessionStart' ? 'SessionStart' : 'PostToolUse';
   outputContext(effectiveEvent, context);
 }
 
+// main() exits silently when SPRINT_ID/PANE_ROLE are unset (test/import context).
+// No guard needed: the env-var check at the top of main() is the safe gate.
 void main();

package/hooks/post-compact.ts

@@ -2,23 +2,142 @@
  * post-compact.ts — PostCompact hook (RFC-022 Phase 2)
  * NEW hook: re-injects workflow state after context compaction
  * so Claude doesn't lose track of active workflow.
+ * Enhanced (RFC-027 S3): also re-injects capability matrix + memory context.
  */
 
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+import { log, getActiveWorkflow, getNextAction, outputContext } from './lib/api-client.js';
 import {
-  log,
-  getActiveWorkflow,
-  getNextAction,
-  outputContext,
-} from "./lib/api-client.js";
+  needsRescan,
+  buildCapabilityIndex,
+  writeCapabilitiesToVault,
+  readCapabilitiesFromVault,
+  scanAgentDefinitions,
+  formatCapabilityMatrix,
+  readMemoryIndex,
+  filterRelevantMemories,
+  formatMemoryContext,
+} from './lib/capability-scanner.js';
 
-const HOOK = "POST-COMPACT";
+const HOOK = 'POST-COMPACT';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PROJECT_ROOT = join(__dirname, '..', '..');
+
+// ─── Capability Matrix paths (mirror session-start.ts constants) ────────────
+const HOME = process.env.HOME ?? process.env.USERPROFILE ?? '/home/user';
+const INSTALLED_PLUGINS_PATH = join(HOME, '.claude', 'plugins', 'installed_plugins.json');
+const AGENTS_DIR = join(PROJECT_ROOT, '.claude', 'agents');
+const VAULT_CONFIG_PATH = join(PROJECT_ROOT, 'project-guidelines', '.vault-config.yaml');
+const PROFILES_PATH = join(PROJECT_ROOT, '.claude', 'plugin-profiles.yaml');
+const MEMORY_INDEX_PATH = join(
+  PROJECT_ROOT,
+  '.claude',
+  'agent-memory',
+  'orchestrator',
+  'memory-index.yaml'
+);
+
+/**
+ * Build [CAPABILITY-MATRIX] + [MEMORY-CONTEXT] lines for injection.
+ * Fail-open: returns empty string on any error.
+ * Pattern copied from session-start.ts buildCapabilityMatrixContext().
+ */
+function buildCapabilityMatrixContext(): string {
+  try {
+    let index = readCapabilitiesFromVault(VAULT_CONFIG_PATH);
+    const cachedMtime = index?.installedPluginsMtime ?? '';
+
+    if (!index || needsRescan(INSTALLED_PLUGINS_PATH, cachedMtime)) {
+      log(HOOK, 'Capability rescan triggered');
+      index = buildCapabilityIndex({
+        installedPluginsPath: INSTALLED_PLUGINS_PATH,
+        agentsDir: AGENTS_DIR,
+        vaultConfigPath: VAULT_CONFIG_PATH,
+        profilesPath: PROFILES_PATH,
+      });
+      writeCapabilitiesToVault(VAULT_CONFIG_PATH, index);
+    } else {
+      // Agents are always scanned fresh (fast, <10ms)
+      index.agents = scanAgentDefinitions(AGENTS_DIR);
+      log(HOOK, 'Using cached capability index');
+    }
+
+    const matrixLine = formatCapabilityMatrix(index);
+
+    // Memory context
+    const memoryEntries = readMemoryIndex(MEMORY_INDEX_PATH);
+    let memoryLine = '';
+    if (memoryEntries) {
+      const filtered = filterRelevantMemories(memoryEntries);
+      memoryLine = formatMemoryContext(filtered);
+    }
+
+    return [matrixLine, memoryLine].filter(Boolean).join('\n');
+  } catch (err) {
+    log(HOOK, `Capability matrix failed: ${err}`);
+    return '';
+  }
+}
+
+/**
+ * Read version — try project-state.yaml first (RFC-033 Phase 1),
+ * fall back to legacy BACKLOG.md regex on any failure.
+ */
+function readVersion(): string {
+  // Primary: project-state.yaml
+  try {
+    const statePath = join(PROJECT_ROOT, 'project-guidelines', 'project-state.yaml');
+    if (existsSync(statePath)) {
+      const raw = readFileSync(statePath, 'utf-8');
+      const doc = parseYaml(raw) as Record<string, unknown>;
+      const version = doc?.version as string | undefined;
+      if (version && typeof version === 'string' && /^v\d+\.\d+\.\d+/.test(version)) {
+        log(HOOK, `project-state.yaml version=${version}`);
+        return version;
+      }
+    }
+  } catch {
+    // fall through to BACKLOG.md
+  }
+
+  // Fallback: BACKLOG.md regex (original logic, preserved)
+  try {
+    const backlogPath = join(PROJECT_ROOT, 'project-guidelines', 'BACKLOG.md');
+    if (!existsSync(backlogPath)) return 'v?.?.?';
+    const content = readFileSync(backlogPath, 'utf-8');
+    const lines = content.split('\n').slice(0, 40);
+    const versionLine = lines.find((l) => /release atual|current release/i.test(l));
+    const match = versionLine?.match(/v(\d+\.\d+\.\d+)/);
+    log(HOOK, 'BACKLOG.md fallback version');
+    return match ? `v${match[1]}` : 'v?.?.?';
+  } catch {
+    return 'v?.?.?';
+  }
+}
 
 async function main(): Promise<void> {
-  log(HOOK, "PostCompact hook triggered");
+  log(HOOK, 'PostCompact hook triggered');
 
+  const version = readVersion();
+  const capabilityContext = buildCapabilityMatrixContext();
   const workflow = await getActiveWorkflow();
+
   if (!workflow) {
-    log(HOOK, "No active workflow, nothing to re-inject");
+    log(HOOK, 'No active workflow — injecting capability context only');
+    outputContext(
+      'PostCompact',
+      [
+        `[ORCHESTRATOR] Context was compacted. version=${version} | workflow=none`,
+        `Remember: YOU are the orchestrator (RFC-022). Dispatch sub-agents directly via Agent tool.`,
+        capabilityContext,
+      ]
+        .filter(Boolean)
+        .join('\n')
+    );
     return;
   }
 
@@ -35,10 +154,17 @@ async function main(): Promise<void> {
     parts.push(`Next: invoke '${action.pendingAction.agent}' (${action.pendingAction.status})`);
   }
 
-  parts.push("", "Remember: YOU are the orchestrator (RFC-022). Dispatch sub-agents directly via Agent tool.");
+  parts.push(
+    '',
+    'Remember: YOU are the orchestrator (RFC-022). Dispatch sub-agents directly via Agent tool.'
+  );
+
+  if (capabilityContext) {
+    parts.push(capabilityContext);
+  }
 
-  log(HOOK, `Re-injecting workflow state (wf=${workflow.id})`);
-  outputContext("PostCompact", parts.join("\n"));
+  log(HOOK, `Re-injecting workflow state + capability context (wf=${workflow.id})`);
+  outputContext('PostCompact', parts.join('\n'));
 }
 
 main().catch(() => process.exit(0));

package/hooks/post-implement.ts

@@ -0,0 +1,88 @@
+/**
+ * post-implement.ts — PostToolUse[mcp__orchestrator-tools__advancePhase] hook
+ * (RFC-034 §5 / TD-102, System-A vehicle)
+ *
+ * Purpose: emit a deterministic orchestrator signal the moment the IMPLEMENT phase
+ * has been completed, so the main-as-orchestrator dispatches the docs-guardian
+ * sub-agent before proceeding past the IMPLEMENT gate. A hook cannot itself spawn a
+ * Claude sub-agent in the main-as-orchestrator model (RFC-022) — it can only signal;
+ * the orchestrator owns the dispatch (see the orchestrator Skin / SKILL dispatch rule).
+ *
+ * Detection rationale (verify-before-assert, S307):
+ *   The MCP advancePhase tool RESPONSE is only `{ success, workflowId }`
+ *   (AdvancePhaseHandler.ts) — it discards the REST controller's `currentPhase` and
+ *   carries NO from/previous phase. At PostToolUse time the advance has already
+ *   committed, so the live workflow's currentPhase is the NEW phase. In the standard
+ *   dev workflow sequence (… -> implement -> review -> complete), 'review' is reached
+ *   ONLY by leaving 'implement'. So post-advance currentPhase === 'review' is the
+ *   available, deterministic proxy for "IMPLEMENT just completed". It fires exactly
+ *   once (a later review -> complete advance lands on 'complete', not 'review').
+ *
+ * Fail-open: any missing env / API error / parse failure -> emit nothing, never throw.
+ * PostToolUse cannot block the tool; emitting no context is the safe no-op.
+ */
+
+import {
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  getWorkflowStatus,
+  outputContext,
+  log,
+} from './lib/api-client.js';
+
+const HOOK = 'POST-IMPLEMENT';
+
+/** The phase entered upon completing IMPLEMENT in the standard dev workflow sequence. */
+const POST_IMPLEMENT_PHASE = 'review';
+
+/**
+ * True when the post-advance phase indicates IMPLEMENT was just completed.
+ * Case-insensitive; empty/unknown phases return false (fail-safe — no signal).
+ */
+function isImplementCompleted(currentPhase: string | null | undefined): boolean {
+  return (currentPhase ?? '').toLowerCase() === POST_IMPLEMENT_PHASE;
+}
+
+/** Builds the orchestrator dispatch signal for a completed IMPLEMENT phase. */
+function buildPostImplementSignal(workflowId: string): string {
+  return [
+    `[ORCHESTRATOR] IMPLEMENT completed for ${workflowId} — dispatch the docs-guardian sub-agent before proceeding past the IMPLEMENT gate.`,
+    `(RFC-034 System-A post-implement signal: docs-guardian checks documentation compliance against the DOCS-CONSTITUTION after implementation.)`,
+  ].join('\n');
+}
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+
+  // Defensive: only act on advancePhase (the settings.json matcher already scopes this).
+  const toolName = getField(stdin, 'tool_name') || getField(stdin, 'tool');
+  if (toolName && !toolName.includes('advancePhase')) {
+    return;
+  }
+
+  // Resolve the workflow id: prefer the tool input, else the active workflow.
+  const wfId = getField(stdin, 'tool_input.workflowId') || (await getActiveWorkflow())?.id || '';
+  if (!wfId) {
+    log(HOOK, 'no workflow id resolvable — skip (fail-open)');
+    return;
+  }
+
+  const status = await getWorkflowStatus(wfId);
+  if (!status) {
+    log(HOOK, `no status for workflow ${wfId} — skip (fail-open)`);
+    return;
+  }
+
+  const phase = (status.currentPhase || '').toLowerCase();
+  log(HOOK, `workflow=${wfId} post-advance currentPhase=${phase}`);
+
+  if (!isImplementCompleted(phase)) {
+    return; // not the implement -> review transition
+  }
+
+  log(HOOK, `IMPLEMENT completed for ${wfId} — emitting docs-guardian dispatch signal`);
+  outputContext('PostToolUse', buildPostImplementSignal(wfId));
+}
+
+main().catch(() => process.exit(0));