@orchestrator-claude/definitions 3.44.0 → 3.44.1

package/hooks/workflow-guard.ts

@@ -17,6 +17,32 @@
  * foreign (trc/red-bull) cwd, where they become load-bearing: a Classe-A
  * gate NEVER no-ops silently on an unrecognized project path.
  *
+ * R7 (RFC-044 F3, S4) — evaluated FIRST, before rule 1, so SKIP_WORKFLOW_GUARD
+ * does not reach it (Q-PM-5). A Write/Edit whose resolved path lies under
+ * project-guidelines/workflows/ of a MANAGED project (registered, not
+ * `.unmanaged`, DV-P10) is allowed only when: the caller is a sub-agent whose
+ * normalized agent_type is in ARTIFACT_PRODUCER_AGENTS; the path is
+ * workflows/<wf>/<phase>/<type>.md (parseVaultPath, the one path function);
+ * and probeWorkflow(<wf of the path>) answers an ACTIVE workflow whose
+ * currentPhase is <phase>. Anything else is a DENY with an R7-* reason; the
+ * network failures carry the "API fora" runbook. The network is consulted ONLY
+ * for such a path (the 2-pass below is preserved for every other path), and an
+ * exception in the R7 branch is a DENY, never the fail-open main().catch.
+ *
+ * R8 (RFC-044 F3, S6c) — evaluated before R7, pure (no network). For a caller
+ * whose normalized agent_type is in VAULT_ONLY_WRITERS (agent_id plays no
+ * part; without agent_type R8 does not apply), the decision comes ENTIRELY
+ * from R8 + R7, never from rules 1-7:
+ *   - a workflows/ path of a managed project: an artifact type outside the
+ *     agent's pinned set is DENY R8-TYPE (no probe); otherwise R7 decides;
+ *   - its OWN memory dir <targetProjectRoot>/.claude/agent-memory/<slug>/
+ *     (resolved path, prefix with the trailing separator): allowed, silent
+ *     as before (R8-MEMORY in the log);
+ *   - anything else (src/, docs, another project, no project, `.unmanaged`,
+ *     SKIP_WORKFLOW_GUARD on): DENY R8-OUTSIDE-VAULT;
+ *   - an exception while deciding for such an agent: DENY R8-EXCEPTION.
+ * Edit decides like Write (R8 does not read tool_name).
+ *
  * Allow paths (in evaluation order — see decideWorkflowGuardAction):
  *   1. SKIP_WORKFLOW_GUARD=true (explicit bypass, all paths)
  *   2. Non-guarded path (file outside src/ or tests/)
@@ -35,19 +61,27 @@
  *   - No active workflow (target project IS registered)
  */
 
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve as resolvePath, sep as PATH_SEP } from 'node:path';
 import { existsSync } from 'node:fs';
+import {
+  parseVaultPath,
+  WORKFLOW_ARTIFACT_ROOT,
+} from '@orchestrator-claude/vault-projection/workflow-artifact';
 import {
   log,
   readStdin,
   getField,
   getActiveWorkflow,
   getWorkflowMode,
+  normalizeAgentName,
   outputPreToolUse,
   resolveAgentMemoryBaseDir,
   resolveHookProjectRoot,
+  type WorkflowStatus,
 } from './lib/api-client.js';
 import { appendObservation } from './lib/observations-helper.js';
+import { ARTIFACT_PRODUCER_AGENTS, VAULT_ONLY_WRITERS } from './lib/artifact-producers.js';
+import { probeWorkflow, type ProbeResult } from './lib/workflow-artifact-client.js';
 
 const HOOK = 'WORKFLOW-GUARD';
 
@@ -84,12 +118,17 @@ export interface WorkflowGuardDecision {
    * `matchedRule === 7` as the sole signal for whether the (network) active
    * workflow must actually be fetched to confirm the decision — see main().
    */
-  matchedRule: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+  matchedRule: 'R8' | 'R7' | 1 | 2 | 3 | 4 | 5 | 6 | 7;
   /** Whether outputPreToolUse must be called. Rules 2/3 are silent pass-throughs (pre-existing behavior — no hookSpecificOutput emitted). */
   emitOutput: boolean;
   output?: WorkflowGuardOutput;
   logMessages: string[];
   observation?: WorkflowGuardObservation;
+  /**
+   * R7 only: set when the decision still needs probeWorkflow(<wf of the path>). The decision that carries it
+   * is already a DENY (R7-PROBE-PENDING), so a caller that forgets to probe fails CLOSED.
+   */
+  r7NeedsProbe?: { workflowId: string; phase: string };
 }
 
 export interface WorkflowGuardWorkflowInput {
@@ -128,6 +167,237 @@ export interface WorkflowGuardDecisionInput {
   agentId: string;
   /** getField(stdin, 'agent_type') — empty string when absent. */
   agentType: string;
+  /** R7: probeWorkflow(<wf of the path>), filled by main() only when a previous decision asked for it. */
+  r7Probe?: ProbeResult;
+}
+
+// ---------------------------------------------------------------------------
+// R7 (RFC-044 F3, S4): workflow artifacts on disk — pure part
+// ---------------------------------------------------------------------------
+
+const WORKFLOWS_SEGMENT = `/${WORKFLOW_ARTIFACT_ROOT}/`;
+/** The house definition of "active" (api-client.ts getActiveWorkflow). */
+const ACTIVE_WORKFLOW_STATUSES: ReadonlySet<string> = new Set([
+  'in_progress',
+  'awaiting_agent',
+  'awaiting_approval',
+]);
+
+/** Runbook "API fora" (plan sec. 9), short; the full text lives in the plan and in the S7 amendment. */
+export const R7_RUNBOOK = [
+  'Runbook "API fora" (RFC-044 F3):',
+  '  1. curl -sS -m 3 "${ORCHESTRATOR_API_URL:-http://localhost:3001}/api/v1/health"  (200 = API up)',
+  '  2. 200 but still denied (R7-NO-TOKEN, or cause no-token): check ORCHESTRATOR_ADMIN_EMAIL, ORCHESTRATOR_ADMIN_PASSWORD, ORCHESTRATOR_PROJECT_ID',
+  '  3. no answer: bring the API back up (the project container/service); the hook retries on the next Write',
+  'SKIP_WORKFLOW_GUARD nao se aplica a R7, nem .orchestrator/.unmanaged; nao edite hooks.json nem os .mjs.',
+].join('\n');
+
+export type R7PathMatch =
+  | { kind: 'none' }
+  | { kind: 'shape'; rel: string }
+  | { kind: 'key'; rel: string; workflowId: string; phase: string; artifactType: string };
+
+/**
+ * Does the RESOLVED path lie under .../project-guidelines/workflows/ (any prefix)? Resolution first:
+ * `workflows/../specs/x.md` and `workflows.bak/...` do not match; `//` is normalized. A match is then
+ * either a well-formed workflows/<wf>/<phase>/<type>.md (parseVaultPath) or a shape violation.
+ */
+export function matchR7Path(filePath: string): R7PathMatch {
+  if (filePath.length === 0) return { kind: 'none' };
+  const resolved = resolvePath(filePath);
+  const at = resolved.indexOf(WORKFLOWS_SEGMENT);
+  if (at === -1) return { kind: 'none' };
+  const rel = resolved.slice(at + 1);
+  if (filePath.endsWith('/')) return { kind: 'shape', rel };
+  const key = parseVaultPath(rel);
+  return key === null ? { kind: 'shape', rel } : { kind: 'key', rel, ...key };
+}
+
+function r7Deny(
+  label: string,
+  message: string,
+  logLine: string,
+  extra: Partial<WorkflowGuardDecision> = {}
+): WorkflowGuardDecision {
+  return {
+    matchedRule: 'R7',
+    emitOutput: true,
+    output: {
+      decision: 'deny',
+      reason: `Workflow Guard ${label}: ${message}`,
+      context:
+        'R7 (RFC-044 F3): project-guidelines/workflows/<wf>/<phase>/<type>.md is written only by an artifact-producing sub-agent, while <wf> is active and in <phase>.',
+    },
+    logMessages: [`DENY (${label}) ${logLine}`],
+    ...extra,
+  };
+}
+
+function r7FromProbe(
+  probe: ProbeResult,
+  target: { rel: string; workflowId: string; phase: string },
+  agent: string
+): WorkflowGuardDecision {
+  const where = `file=${target.rel} agent=${agent}`;
+  if (probe.kind === 'not-found') {
+    return r7Deny(
+      'R7-WORKFLOW-NOT-FOUND',
+      `workflow ${target.workflowId} (from the path) does not exist in this project.`,
+      where
+    );
+  }
+  if (probe.kind === 'unavailable') {
+    // Only a token the API REJECTED proves the API is up. `no-token` is also what a DOWN API gives (login
+    // fails before any probe; measured S557 against a closed port), so it stays under API-UNAVAILABLE.
+    const label = probe.cause === 'unauthorized' ? 'R7-NO-TOKEN' : 'R7-API-UNAVAILABLE';
+    return r7Deny(
+      label,
+      `could not confirm workflow ${target.workflowId} with the API (cause: ${probe.cause}${probe.httpStatus === undefined ? '' : `, HTTP ${String(probe.httpStatus)}`}).\n${R7_RUNBOOK}`,
+      `${where} cause=${probe.cause}`
+    );
+  }
+  if (!ACTIVE_WORKFLOW_STATUSES.has(probe.status)) {
+    return r7Deny(
+      'R7-WORKFLOW-NOT-ACTIVE',
+      `workflow ${target.workflowId} is ${probe.status}, not active.`,
+      where
+    );
+  }
+  if ((probe.currentPhase ?? '').toLowerCase() !== target.phase) {
+    return r7Deny(
+      'R7-PHASE-NOT-CURRENT',
+      `workflow ${target.workflowId} is in phase ${String(probe.currentPhase)}, not ${target.phase}.`,
+      where
+    );
+  }
+  return {
+    matchedRule: 'R7',
+    emitOutput: true,
+    output: {
+      decision: 'allow',
+      context: `R7: ${agent} writes ${target.rel} (workflow ${target.workflowId} active, phase ${target.phase}).`,
+    },
+    logMessages: [`ALLOW (R7) ${where}`],
+  };
+}
+
+/** R7, pure. null = R7 does not apply (not a workflows/ path, or not a managed project): current rules. */
+function decideR7(input: WorkflowGuardDecisionInput): WorkflowGuardDecision | null {
+  const match = matchR7Path(input.filePath);
+  if (match.kind === 'none') return null;
+  if (input.targetProjectRoot === null || input.isUnmanaged) return null;
+  return decideR7ForMatch(input, match);
+}
+
+/** R7 on a workflows/ path of a managed project (the caller has checked both). */
+function decideR7ForMatch(
+  input: WorkflowGuardDecisionInput,
+  match: Exclude<R7PathMatch, { kind: 'none' }>
+): WorkflowGuardDecision {
+  const agent = input.agentType ? normalizeAgentName(input.agentType) : '';
+  if (agent === '') {
+    return r7Deny(
+      'R7-MAIN-AGENT',
+      `${match.rel} is written only by an artifact-producing sub-agent, never by the main agent (Q-PM-5).`,
+      `file=${match.rel}`
+    );
+  }
+  if (!ARTIFACT_PRODUCER_AGENTS.has(agent)) {
+    return r7Deny(
+      'R7-NOT-PRODUCER',
+      `agent ${agent} is not an artifact producer (ARTIFACT_PRODUCER_AGENTS).`,
+      `file=${match.rel} agent=${agent}`
+    );
+  }
+  if (match.kind === 'shape') {
+    return r7Deny(
+      'R7-SHAPE',
+      `${match.rel} is not project-guidelines/workflows/<workflow_id>/<phase>/<artifact_type>.md.`,
+      `file=${match.rel} agent=${agent}`
+    );
+  }
+  const target = { rel: match.rel, workflowId: match.workflowId, phase: match.phase };
+  if (input.r7Probe === undefined) {
+    return r7Deny('R7-PROBE-PENDING', 'workflow not confirmed yet.', `file=${match.rel}`, {
+      r7NeedsProbe: { workflowId: match.workflowId, phase: match.phase },
+    });
+  }
+  return r7FromProbe(input.r7Probe, target, agent);
+}
+
+// ---------------------------------------------------------------------------
+// R8 (RFC-044 F3, S6c): the Write of a VAULT_ONLY_WRITERS agent — pure
+// ---------------------------------------------------------------------------
+
+/** The fenced agent's bare name, or null when R8 does not apply (no agent_type, or an agent outside the set). */
+function vaultOnlyWriter(agentType: string): string | null {
+  if (agentType === '') return null;
+  const agent = normalizeAgentName(agentType);
+  return VAULT_ONLY_WRITERS.has(agent) ? agent : null;
+}
+
+const R8_CONTEXT =
+  'R8 (RFC-044 F3, S6c): this agent writes only (1) its artifact project-guidelines/workflows/<wf>/<phase>/<type>.md of a managed project, under R7, and (2) its own memory under .claude/agent-memory/<slug>/. SKIP_WORKFLOW_GUARD does not apply.';
+
+function r8Deny(label: string, message: string, logLine: string): WorkflowGuardDecision {
+  return {
+    matchedRule: 'R8',
+    emitOutput: true,
+    output: {
+      decision: 'deny',
+      reason: `Workflow Guard ${label}: ${message}`,
+      context: R8_CONTEXT,
+    },
+    logMessages: [`DENY (${label}) ${logLine}`],
+  };
+}
+
+/** Is the RESOLVED path inside <root>/.claude/agent-memory/<agent>/ (the separator keeps `<agent>-x/` out)? */
+function isOwnMemory(filePath: string, root: string, agent: string): boolean {
+  const dir = join(root, '.claude', 'agent-memory', agent) + PATH_SEP;
+  return resolvePath(filePath).startsWith(dir);
+}
+
+/** R8, pure. null = R8 does not apply (the caller is not a VAULT_ONLY_WRITERS agent): R7 and rules 1-7. */
+function decideR8(input: WorkflowGuardDecisionInput): WorkflowGuardDecision | null {
+  const agent = vaultOnlyWriter(input.agentType);
+  if (agent === null) return null;
+  const where = `file=${input.filePath} agent=${agent}`;
+  const match = matchR7Path(input.filePath);
+  if (match.kind !== 'none' && input.targetProjectRoot !== null && !input.isUnmanaged) {
+    const types = VAULT_ONLY_WRITERS.get(agent) ?? null;
+    if (match.kind === 'key' && types !== null && !types.has(match.artifactType)) {
+      return r8Deny(
+        'R8-TYPE',
+        `agent ${agent} writes only ${[...types].join(', ')} under workflows/, not ${match.artifactType} (R-6: never the artifact under review).`,
+        `file=${match.rel} agent=${agent}`
+      );
+    }
+    return decideR7ForMatch(input, match);
+  }
+  if (
+    input.targetProjectRoot !== null &&
+    isOwnMemory(input.filePath, input.targetProjectRoot, agent)
+  ) {
+    return { matchedRule: 'R8', emitOutput: false, logMessages: [`ALLOW (R8-MEMORY) ${where}`] };
+  }
+  return r8Deny(
+    'R8-OUTSIDE-VAULT',
+    `agent ${agent} may not write ${input.filePath}. It writes only project-guidelines/workflows/<wf>/<phase>/<type>.md of a managed project (R7) and its own memory .claude/agent-memory/${agent}/.`,
+    where
+  );
+}
+
+/** An exception while deciding for a VAULT_ONLY_WRITERS agent: a DENY, never main().catch -> exit 0. */
+export function r8ExceptionDecision(error: unknown): WorkflowGuardDecision {
+  const message = error instanceof Error ? error.message : String(error);
+  return r8Deny('R8-EXCEPTION', `unexpected error (${message}).`, 'exception');
+}
+
+/** An exception anywhere in the R7 branch of main(): a DENY, never main().catch -> exit 0 (fail-open). */
+export function r7ExceptionDecision(error: unknown): WorkflowGuardDecision {
+  const message = error instanceof Error ? error.message : String(error);
+  return r7Deny('R7-EXCEPTION', `unexpected error (${message}).\n${R7_RUNBOOK}`, 'exception');
 }
 
 const CONFIG_DOC_RE = /\.(json|ya?ml|md|env(\..*)?)$/;
@@ -152,6 +422,14 @@ export function decideWorkflowGuardAction(
     agentType,
   } = input;
 
+  // R8 (RFC-044 F3, S6c): FIRST — a VAULT_ONLY_WRITERS agent is decided by R8 + R7 only.
+  const r8 = decideR8(input);
+  if (r8 !== null) return r8;
+
+  // R7 (RFC-044 F3, S4): BEFORE rule 1 — SKIP_WORKFLOW_GUARD does not reach it.
+  const r7 = decideR7(input);
+  if (r7 !== null) return r7;
+
   // Rule 1: explicit global bypass
   if (skipWorkflowGuard) {
     return {
@@ -340,17 +618,48 @@ export function decideWorkflowGuardAction(
   };
 }
 
-async function main(): Promise<void> {
-  const stdin = await readStdin();
+/** Everything main() reads or writes outside the pure decision; injected by the tests. */
+export interface WorkflowGuardDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  env: Readonly<Record<string, string | undefined>>;
+  resolveHookProjectRoot: (dir: string) => string | null;
+  isUnmanaged: (projectRoot: string) => boolean;
+  getActiveWorkflow: () => Promise<WorkflowStatus | null>;
+  getWorkflowMode: (workflowId: string) => Promise<string | null>;
+  probeWorkflow: (workflowId: string) => Promise<ProbeResult>;
+  output: (output: WorkflowGuardOutput) => void;
+  log: (line: string) => void;
+  appendObservation: (
+    stdin: Record<string, unknown>,
+    observation: WorkflowGuardObservation
+  ) => void;
+}
+
+/** R7 network step: probe the workflow OF THE PATH and decide again; any exception is a DENY. */
+async function decideWithProbe(
+  input: WorkflowGuardDecisionInput,
+  needs: { workflowId: string },
+  deps: WorkflowGuardDeps
+): Promise<WorkflowGuardDecision> {
+  try {
+    const r7Probe = await deps.probeWorkflow(needs.workflowId);
+    return decideWorkflowGuardAction({ ...input, r7Probe });
+  } catch (e) {
+    return r7ExceptionDecision(e);
+  }
+}
+
+export async function mainWithDeps(deps: WorkflowGuardDeps): Promise<void> {
+  const stdin = await deps.readStdin();
   const filePath =
     getField(stdin, 'tool_input.file_path') ||
     getField(stdin, 'file_path') ||
     getField(stdin, 'input.file_path');
 
-  log(HOOK, `file_path=${filePath}`);
+  deps.log(`file_path=${filePath}`);
 
-  const skipWorkflowGuard = process.env.SKIP_WORKFLOW_GUARD === 'true';
-  const skipSubagentGuard = process.env.SKIP_SUBAGENT_GUARD === 'true';
+  const skipWorkflowGuard = deps.env.SKIP_WORKFLOW_GUARD === 'true';
+  const skipSubagentGuard = deps.env.SKIP_SUBAGENT_GUARD === 'true';
   const agentId = getField(stdin, 'agent_id');
   const agentType = getField(stdin, 'agent_type');
 
@@ -358,12 +667,10 @@ async function main(): Promise<void> {
   // (file_path), not the session's cwd. Cheap fs walk-up (no network) — safe
   // to compute unconditionally for every Write/Edit.
   const targetDir = filePath.length > 0 ? dirname(filePath) : process.cwd();
-  const targetProjectRoot = resolveHookProjectRoot(targetDir);
-  const isUnmanaged =
-    targetProjectRoot !== null &&
-    existsSync(join(targetProjectRoot, '.orchestrator', '.unmanaged'));
+  const targetProjectRoot = deps.resolveHookProjectRoot(targetDir);
+  const isUnmanaged = targetProjectRoot !== null && deps.isUnmanaged(targetProjectRoot);
 
-  const baseInput: Omit<WorkflowGuardDecisionInput, 'workflow'> = {
+  const baseInput: WorkflowGuardDecisionInput = {
     filePath,
     skipWorkflowGuard,
     skipSubagentGuard,
@@ -371,6 +678,7 @@ async function main(): Promise<void> {
     isUnmanaged,
     agentId,
     agentType,
+    workflow: null,
   };
 
   // Two-pass evaluation: try with workflow=null first. Rules 1-5 never
@@ -380,41 +688,76 @@ async function main(): Promise<void> {
   // unmanaged, and unregistered paths. Only when the trial itself lands on
   // rule 7 ("no active workflow") do we actually need the network fetch to
   // confirm — at most one real fetch, matching original behavior exactly.
-  let decision = decideWorkflowGuardAction({ ...baseInput, workflow: null });
+  // R7 has its own network step (probe of the workflow of the PATH), taken
+  // only when the trial asks for it (r7NeedsProbe), inside a DENY-on-throw.
+  let decision: WorkflowGuardDecision;
+  try {
+    decision = decideWorkflowGuardAction(baseInput);
+  } catch (e) {
+    if (vaultOnlyWriter(agentType) !== null) {
+      decision = r8ExceptionDecision(e);
+    } else {
+      if (matchR7Path(filePath).kind === 'none') throw e;
+      decision = r7ExceptionDecision(e);
+    }
+  }
 
-  if (decision.matchedRule === 7) {
-    const activeWorkflow = await getActiveWorkflow();
+  if (decision.r7NeedsProbe) {
+    decision = await decideWithProbe(baseInput, decision.r7NeedsProbe, deps);
+  } else if (decision.matchedRule === 7) {
+    const activeWorkflow = await deps.getActiveWorkflow();
     let workflow: WorkflowGuardWorkflowInput | null = null;
     if (activeWorkflow) {
-      const mode = await getWorkflowMode(activeWorkflow.id);
+      const mode = await deps.getWorkflowMode(activeWorkflow.id);
       workflow = { id: activeWorkflow.id, mode, currentPhase: activeWorkflow.currentPhase };
     }
     decision = decideWorkflowGuardAction({ ...baseInput, workflow });
   }
 
   for (const line of decision.logMessages) {
-    log(HOOK, line);
+    deps.log(line);
   }
 
   if (decision.observation) {
     try {
-      const sessionId = getField(stdin, 'session_id') || getField(stdin, 'claude_session_id') || '';
-      // RFC-040 Operator Multi-Project — Slice 5 (C5): resolves under the
-      // project root walked up from cwd (falls back to cwd when unregistered).
-      const memoryBaseDir = resolveAgentMemoryBaseDir(process.cwd());
-      appendObservation(memoryBaseDir, 'main', {
-        timestamp: new Date().toISOString(),
-        session_id: sessionId,
-        ...decision.observation,
-      });
+      deps.appendObservation(stdin, decision.observation);
     } catch {
       // fail-open — never block on telemetry
     }
   }
 
   if (decision.emitOutput && decision.output) {
-    outputPreToolUse(decision.output);
+    deps.output(decision.output);
   }
 }
 
+const defaultDeps: WorkflowGuardDeps = {
+  readStdin,
+  env: process.env,
+  resolveHookProjectRoot,
+  isUnmanaged: (projectRoot) => existsSync(join(projectRoot, '.orchestrator', '.unmanaged')),
+  getActiveWorkflow,
+  getWorkflowMode,
+  probeWorkflow: (workflowId) => probeWorkflow(workflowId),
+  output: outputPreToolUse,
+  log: (line) => {
+    log(HOOK, line);
+  },
+  appendObservation: (stdin, observation) => {
+    const sessionId = getField(stdin, 'session_id') || getField(stdin, 'claude_session_id') || '';
+    // RFC-040 Operator Multi-Project — Slice 5 (C5): resolves under the
+    // project root walked up from cwd (falls back to cwd when unregistered).
+    const memoryBaseDir = resolveAgentMemoryBaseDir(process.cwd());
+    appendObservation(memoryBaseDir, 'main', {
+      timestamp: new Date().toISOString(),
+      session_id: sessionId,
+      ...observation,
+    });
+  },
+};
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
 main().catch(() => process.exit(0));