@orchestrator-claude/definitions 3.43.1 → 3.44.1

package/hooks/lib/artifact-gate.ts

@@ -0,0 +1,518 @@
+/**
+ * artifact-gate.ts — the gate-guardian's ledger step over the files on disk (RFC-044 F3, S5; ADR-031).
+ *
+ * Leaving phase P (P = probeWorkflow(W).currentPhase, never targetPhase), immediately before an ALLOW:
+ *   1. observe: list <root>/project-guidelines/workflows/W/**, read and parse each file (sha256 of the WHOLE bytes);
+ *   2. validate every file of P (RF-019: the same validator as the CI gate, the constitution of the vault);
+ *   3. verify the files of the SEALED phases (!= P) with `exhaustive: {excludePhases: [P]}` (S3c, M6, D-469): a
+ *      verdict that is not ok, or a registered host file nobody showed (`unobserved`), is a DENY citing the file;
+ *   4. register every file of P (idempotent by (key, hash) on the server), with `advancedBySession` and WITHOUT
+ *      `agentType` (TD-390, D-486 (2), D-485 (1)).
+ * Every failure is a DENY with its reason; nothing here throws to the caller (fail closed).
+ *
+ * Amendment (c), D-486 (3): until S6c the content store and the file share the `adversarial_review` key, and the
+ * ledger compares against the LAST revision whatever its locator. A sealed adversarial_review file is therefore held
+ * out of the exhaustive call: if its key comes back in `unobserved`, the last revision is a host file and it is
+ * verified strictly; if it does not, the last revision is content-store (or there is no row), and only a
+ * hash-mismatch is skipped (the MinIO bytes are not the file). NOT_REGISTERED and an incomplete row still deny.
+ *
+ * Out of scope on purpose (TD-391): a file deleted in the CURRENT phase, Bash in the current phase, quick mode
+ * (the caller never gets here), and a delete after the last advance or completeWorkflow.
+ *
+ * The vault root is the git toplevel of the PROCESS (ADR-031 D1), resolved here with `git rev-parse`, so the
+ * bundle never pulls vault-projection's gate/git.ts (PL-ADR-3).
+ */
+import { execFileSync } from 'node:child_process';
+import type { Dirent } from 'node:fs';
+import { open, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import {
+  PHASE_PATTERN,
+  SESSION_ID_PATTERN,
+  WORKFLOW_ARTIFACT_ROOT,
+  loadConstitution,
+  parseVaultPath,
+  parseWorkflowArtifact,
+  validateWorkflowArtifact,
+  vaultPathFor,
+  type ConstitutionVocab,
+  type VerifyItemFailed,
+  type VerifyObservedItem,
+  type WorkflowArtifactContext,
+  type WorkflowArtifactKey,
+  type WorkflowArtifactViolation,
+} from '@orchestrator-claude/vault-projection/workflow-artifact';
+import type { AdversarialVerdictResult } from './api-client.js';
+import {
+  defaultClientDeps,
+  probeWorkflow,
+  registerArtifact,
+  verifyObserved,
+  type ClientDeps,
+  type ProbeResult,
+  type RegisterInput,
+  type RegisterResult,
+  type UnobservedArtifact,
+  type VerifyOptions,
+  type VerifyResult,
+} from './workflow-artifact-client.js';
+
+export const ADVERSARIAL_REVIEW_TYPE = 'adversarial_review';
+/** A phase artifact above this size is a DENY (EFBIG): a text artifact, never a blob. */
+export const MAX_ARTIFACT_BYTES = 2 * 1024 * 1024;
+const CONSTITUTION_REL = 'project-guidelines/.docs-constitution.yaml';
+/** How many violations a DENY reason lists before it says "and N more". */
+const MAX_LISTED = 12;
+
+const RUNBOOK =
+  'Runbook "API fora" (RFC-044 F3): curl -sS -m 3 "${ORCHESTRATOR_API_URL:-http://localhost:3001}/api/v1/health" ' +
+  '(200 = API up; then check token/project). The gate fails closed by design: do not edit hooks.json nor the .mjs.';
+
+export interface ArtifactGateDeps {
+  /** The git toplevel of the process (ADR-031 D1); null outside a git checkout. */
+  getRepoToplevel: () => string | null;
+  /** Repo-relative paths of <wf>/<phase>/*.md and <wf>/*.md, sorted; [] when the workflow has no directory. */
+  listWorkflowFiles: (root: string, workflowId: string) => Promise<readonly string[]>;
+  /** Whole bytes; rejects with `code` (ENOENT, EACCES, EISDIR, EFBIG above `maxBytes`). */
+  readFile: (absPath: string, maxBytes: number) => Promise<Uint8Array>;
+  probeWorkflow: (workflowId: string) => Promise<ProbeResult>;
+  registerArtifact: (input: RegisterInput) => Promise<RegisterResult>;
+  verifyObserved: (
+    workflowId: string,
+    items: readonly VerifyObservedItem[],
+    options?: VerifyOptions
+  ) => Promise<VerifyResult>;
+  /** Throws when the constitution is missing, unreadable or malformed (no embedded fallback, RF-019). */
+  loadConstitution: (path: string) => ConstitutionVocab;
+  validateArtifact: (
+    frontmatter: Readonly<Record<string, unknown>> | null,
+    ctx: WorkflowArtifactContext
+  ) => readonly WorkflowArtifactViolation[];
+}
+
+const codeOf = (e: unknown): string => {
+  const code = (e as { code?: unknown } | null)?.code;
+  return typeof code === 'string' ? code : e instanceof Error ? e.message : String(e);
+};
+
+function fsError(code: string, message: string): Error {
+  return Object.assign(new Error(`${code}: ${message}`), { code });
+}
+
+/** `git rev-parse --show-toplevel` from `cwd`; null when it is not a git checkout (never throws). */
+export function gitToplevel(cwd: string): string | null {
+  try {
+    const out = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 5000,
+    }).trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readdirOrEmpty(dir: string): Promise<Dirent[]> {
+  try {
+    return await readdir(dir, { withFileTypes: true });
+  } catch (e) {
+    if (codeOf(e) === 'ENOENT') return [];
+    throw e;
+  }
+}
+
+async function listWorkflowFilesFs(root: string, workflowId: string): Promise<readonly string[]> {
+  const relBase = `${WORKFLOW_ARTIFACT_ROOT}/${workflowId}`;
+  const found: string[] = [];
+  for (const entry of await readdirOrEmpty(join(root, relBase))) {
+    if (entry.isDirectory() && !entry.name.endsWith('.md')) {
+      for (const inner of await readdirOrEmpty(join(root, relBase, entry.name))) {
+        if (inner.name.endsWith('.md')) found.push(`${relBase}/${entry.name}/${inner.name}`);
+      }
+    } else if (entry.name.endsWith('.md')) {
+      found.push(`${relBase}/${entry.name}`);
+    }
+  }
+  return found.sort();
+}
+
+async function readFileFs(absPath: string, maxBytes: number): Promise<Uint8Array> {
+  const handle = await open(absPath, 'r');
+  try {
+    const stat = await handle.stat();
+    if (stat.isDirectory()) throw fsError('EISDIR', absPath);
+    if (stat.size > maxBytes)
+      throw fsError('EFBIG', `${absPath} has ${String(stat.size)} bytes (max ${String(maxBytes)})`);
+    return await handle.readFile();
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Production deps. `clientDeps` lets a test point the client at its own API (URL, token, project). */
+export function defaultArtifactGateDeps(clientDeps?: ClientDeps): ArtifactGateDeps {
+  const client = (): ClientDeps => clientDeps ?? defaultClientDeps();
+  return {
+    getRepoToplevel: () => gitToplevel(process.cwd()),
+    listWorkflowFiles: listWorkflowFilesFs,
+    readFile: readFileFs,
+    probeWorkflow: (workflowId) => probeWorkflow(workflowId, client()),
+    registerArtifact: (input) => registerArtifact(input, client()),
+    verifyObserved: (workflowId, items, options) =>
+      verifyObserved(workflowId, items, client(), options),
+    loadConstitution: (path) => loadConstitution(path),
+    validateArtifact: validateWorkflowArtifact,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Authorship of the advance (TD-390, D-486 (2), D-485 (1))
+// ─────────────────────────────────────────────────────────────
+
+export type SessionOf =
+  | { kind: 'ok'; advancedBySession: string }
+  | { kind: 'omitted'; why: 'absent' | 'invalid' };
+
+/**
+ * The stdin `session_id` when it is a string inside SESSION_ID_PATTERN; otherwise the field is OMITTED, never sent
+ * (the server would answer 400, and a 400 is a DENY). Authorship is audit data, not the fence: an unmeasured stdin
+ * shape (TD-390 sec. 3: interactive main, sub-agent, --agent) must not block every advance.
+ */
+export function sessionOf(raw: unknown): SessionOf {
+  if (raw === undefined || raw === null || raw === '') return { kind: 'omitted', why: 'absent' };
+  if (typeof raw !== 'string' || !SESSION_ID_PATTERN.test(raw))
+    return { kind: 'omitted', why: 'invalid' };
+  return { kind: 'ok', advancedBySession: raw };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Observation of the disk
+// ─────────────────────────────────────────────────────────────
+
+export interface ObservedFile {
+  readonly rel: string;
+  readonly key: WorkflowArtifactKey;
+  readonly sha256: string;
+  readonly sizeBytes: number;
+  readonly frontmatter: Record<string, unknown> | null;
+}
+
+export type Observation =
+  | {
+      kind: 'ok';
+      workflowId: string;
+      /** The phase being left, lowercase. */
+      phase: string;
+      root: string | null;
+      files: readonly ObservedFile[];
+    }
+  | { kind: 'deny'; reason: string };
+
+const deny = (detail: string): { kind: 'deny'; reason: string } => ({
+  kind: 'deny',
+  reason: `Gate Guardian (RFC-044 F3, workflow artifacts on disk): ${detail}`,
+});
+
+function probeFailure(probe: Exclude<ProbeResult, { kind: 'ok' }>, workflowId: string): string {
+  if (probe.kind === 'not-found') return `workflow ${workflowId} not found by the API.`;
+  const http = probe.httpStatus === undefined ? '' : `, HTTP ${String(probe.httpStatus)}`;
+  return `could not confirm workflow ${workflowId} with the API (cause: ${probe.cause}${http}). ${RUNBOOK}`;
+}
+
+/** Probe (the phase being left), toplevel, listing, reading and parsing. No register, no verify. */
+export async function observeWorkflow(
+  workflowId: string,
+  deps: ArtifactGateDeps
+): Promise<Observation> {
+  try {
+    const probe = await deps.probeWorkflow(workflowId);
+    if (probe.kind !== 'ok') return deny(probeFailure(probe, workflowId));
+    const phase = (probe.currentPhase ?? '').toLowerCase();
+    if (!PHASE_PATTERN.test(phase)) {
+      return deny(
+        `workflow ${workflowId} has no current phase the gate can read (${JSON.stringify(probe.currentPhase)}); the phase being left is unknown.`
+      );
+    }
+    const root = deps.getRepoToplevel();
+    if (root === null) return { kind: 'ok', workflowId, phase, root, files: [] };
+    let rels: readonly string[];
+    try {
+      rels = await deps.listWorkflowFiles(root, workflowId);
+    } catch (e) {
+      return deny(`cannot list ${WORKFLOW_ARTIFACT_ROOT}/${workflowId}: ${codeOf(e)}.`);
+    }
+    const files: ObservedFile[] = [];
+    for (const rel of rels) {
+      const key = parseVaultPath(rel);
+      if (key?.workflowId !== workflowId) {
+        return deny(
+          `${rel} is not ${WORKFLOW_ARTIFACT_ROOT}/<workflow_id>/<phase>/<artifact_type>.md (ADR-031 D2).`
+        );
+      }
+      let bytes: Uint8Array;
+      try {
+        bytes = await deps.readFile(join(root, rel), MAX_ARTIFACT_BYTES);
+      } catch (e) {
+        return deny(`cannot read ${rel}: ${codeOf(e)}.`);
+      }
+      const parsed = parseWorkflowArtifact(bytes);
+      files.push({
+        rel,
+        key,
+        sha256: parsed.sha256,
+        sizeBytes: bytes.byteLength,
+        frontmatter: parsed.frontmatter,
+      });
+    }
+    return { kind: 'ok', workflowId, phase, root, files };
+  } catch (e) {
+    return deny(
+      `unexpected error while observing the workflow (${e instanceof Error ? e.message : String(e)}).`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// RF-020: the adversarial verdict of the file comes first
+// ─────────────────────────────────────────────────────────────
+
+export type FileVerdict =
+  | { kind: 'none' }
+  | { kind: 'invalid'; reason: string }
+  | { kind: 'verdict'; result: AdversarialVerdictResult };
+
+/**
+ * workflows/<wf>/<P>/adversarial_review.md: `verdict` (string) and `iteration` (a non-negative integer). No file
+ * -> none (the caller falls back to the content store). A file without a string verdict is invalid (a DENY, never
+ * a fail-open); an iteration that is not an integer keeps TD-375 (iteration_rejected: PASS proceeds, else DENY).
+ */
+export function fileAdversarialVerdict(
+  observation: Extract<Observation, { kind: 'ok' }>
+): FileVerdict {
+  const file = observation.files.find(
+    (f) => f.key.phase === observation.phase && f.key.artifactType === ADVERSARIAL_REVIEW_TYPE
+  );
+  if (file === undefined) return { kind: 'none' };
+  const fm = file.frontmatter;
+  if (fm === null) return { kind: 'invalid', reason: `${file.rel} has no valid YAML frontmatter.` };
+  const { verdict, iteration } = fm;
+  if (typeof verdict !== 'string' || verdict.length === 0) {
+    return {
+      kind: 'invalid',
+      reason: `${file.rel}: verdict must be a non-empty string, got ${(JSON.stringify(verdict) as string | undefined) ?? 'nothing'}.`,
+    };
+  }
+  if (typeof iteration === 'number' && Number.isSafeInteger(iteration) && iteration >= 0) {
+    return { kind: 'verdict', result: { kind: 'ok', verdict, iteration } };
+  }
+  const detail = (JSON.stringify(iteration) as string | undefined)?.slice(0, 40) ?? 'absent';
+  return { kind: 'verdict', result: { kind: 'iteration_rejected', verdict, detail } };
+}
+
+// ─────────────────────────────────────────────────────────────
+// The ledger step before the ALLOW
+// ─────────────────────────────────────────────────────────────
+
+export interface LedgerContext {
+  workflowId: string;
+  advancedBySession?: string;
+}
+
+export type LedgerOutcome = { ok: true; summary: string } | { ok: false; reason: string };
+
+type Log = (msg: string) => void;
+
+const fail = (detail: string): LedgerOutcome => ({ ok: false, reason: deny(detail).reason });
+
+function listed(lines: readonly string[]): string {
+  const head = lines.slice(0, MAX_LISTED).join('; ');
+  return lines.length > MAX_LISTED
+    ? `${head}; and ${String(lines.length - MAX_LISTED)} more`
+    : head;
+}
+
+function verifyFailure(result: Exclude<VerifyResult, { kind: 'ok' }>, workflowId: string): string {
+  if (result.kind === 'probe-failed') return probeFailure(result.probe, workflowId);
+  if (result.kind === 'rejected') {
+    return `verify-observed rejected by the API (${result.code}, HTTP ${String(result.httpStatus)})${result.detail === undefined ? '' : `: ${result.detail}`}.`;
+  }
+  const http = result.httpStatus === undefined ? '' : `, HTTP ${String(result.httpStatus)}`;
+  return `verify-observed unavailable (cause: ${result.cause}${http}). ${RUNBOOK}`;
+}
+
+const itemOf = (f: ObservedFile): VerifyObservedItem => ({
+  phase: f.key.phase,
+  artifactType: f.key.artifactType,
+  observedHash: f.sha256,
+});
+
+const pathOf = (workflowId: string, phase: string, artifactType: string): string =>
+  vaultPathFor({ workflowId, phase, artifactType });
+
+function describeFailed(workflowId: string, f: VerifyItemFailed): string {
+  const reason = f.reason === undefined ? '' : ` (${f.reason})`;
+  const revision =
+    f.revision === undefined || f.revision === null
+      ? ''
+      : `, ledger revision ${String(f.revision)}`;
+  return `${pathOf(workflowId, f.phase, f.artifactType)}: ${f.code}${reason}${revision}`;
+}
+
+function validateCurrent(
+  current: readonly ObservedFile[],
+  observation: Extract<Observation, { kind: 'ok' }>,
+  deps: ArtifactGateDeps
+): string | null {
+  if (current.length === 0 || observation.root === null) return null;
+  let constitution: ConstitutionVocab;
+  try {
+    constitution = deps.loadConstitution(join(observation.root, CONSTITUTION_REL));
+  } catch (e) {
+    return `cannot load the constitution ${CONSTITUTION_REL} to validate the files of '${observation.phase}' (${e instanceof Error ? e.message : String(e)}).`;
+  }
+  const violations = current.flatMap((f) =>
+    deps
+      .validateArtifact(f.frontmatter, { path: f.rel, constitution })
+      .map((v) => `${v.file} ${v.field}: ${v.message}`)
+  );
+  return violations.length === 0
+    ? null
+    : `the files of the phase being left ('${observation.phase}') violate the workflow-artifact schema (RF-019): ${listed(violations)}.`;
+}
+
+/** Sealed phases: exhaustive verify of the plain files, then the adversarial_review files on their own (D-486 (3)). */
+async function verifySealed(
+  sealed: readonly ObservedFile[],
+  observation: Extract<Observation, { kind: 'ok' }>,
+  deps: ArtifactGateDeps,
+  log: Log
+): Promise<string | null> {
+  const { workflowId, phase } = observation;
+  const plain = sealed.filter((f) => f.key.artifactType !== ADVERSARIAL_REVIEW_TYPE);
+  const adversarial = sealed.filter((f) => f.key.artifactType === ADVERSARIAL_REVIEW_TYPE);
+
+  const first = await deps.verifyObserved(workflowId, plain.map(itemOf), {
+    exhaustive: { excludePhases: [phase] },
+  });
+  if (first.kind !== 'ok') return verifyFailure(first, workflowId);
+  if (first.unobserved === undefined) {
+    return (
+      'verify-observed answered without `unobserved` to an exhaustive request (an API without S3c?). ' +
+      RUNBOOK
+    );
+  }
+  const problems = first.failed.map((f) => describeFailed(workflowId, f));
+
+  const vaultFileAdversarial = new Set<string>();
+  const missing: UnobservedArtifact[] = [];
+  for (const u of first.unobserved) {
+    const onDisk = adversarial.some((f) => f.key.phase === u.phase.toLowerCase());
+    if (u.artifactType === ADVERSARIAL_REVIEW_TYPE && onDisk)
+      vaultFileAdversarial.add(u.phase.toLowerCase());
+    else missing.push(u);
+  }
+  for (const u of missing) {
+    problems.push(
+      `${pathOf(workflowId, u.phase, u.artifactType)}: registered (ledger revision ${String(u.revision)}) and missing from disk in a sealed phase (D-469)`
+    );
+  }
+
+  if (adversarial.length > 0) {
+    const second = await deps.verifyObserved(workflowId, adversarial.map(itemOf));
+    if (second.kind !== 'ok') return verifyFailure(second, workflowId);
+    for (const f of second.failed) {
+      const contentStoreLast = !vaultFileAdversarial.has(f.phase.toLowerCase());
+      if (
+        contentStoreLast &&
+        f.code === 'ARTIFACT_INTEGRITY_VIOLATED' &&
+        f.reason === 'hash-mismatch'
+      ) {
+        log(
+          `skip ${pathOf(workflowId, f.phase, f.artifactType)}: last revision of the key is content-store, not this file (D-486 (3), until S6c)`
+        );
+        continue;
+      }
+      problems.push(describeFailed(workflowId, f));
+    }
+  }
+
+  return problems.length === 0
+    ? null
+    : `the sealed phases do not match the ledger: ${listed(problems)}. Restore the file(s) (e.g. git checkout) and advance again.`;
+}
+
+async function registerCurrent(
+  current: readonly ObservedFile[],
+  observation: Extract<Observation, { kind: 'ok' }>,
+  ctx: LedgerContext,
+  deps: ArtifactGateDeps
+): Promise<{ error: string } | { recorded: number; unchanged: number }> {
+  let recorded = 0;
+  let unchanged = 0;
+  for (const f of current) {
+    const result = await deps.registerArtifact({
+      workflowId: observation.workflowId,
+      phase: observation.phase,
+      artifactType: f.key.artifactType,
+      vaultPath: f.rel,
+      contentHash: f.sha256,
+      sizeBytes: f.sizeBytes,
+      frontmatter: f.frontmatter ?? {},
+      ...(ctx.advancedBySession !== undefined && { advancedBySession: ctx.advancedBySession }),
+    });
+    if (result.kind === 'ok') {
+      if (result.response.status === 'recorded') recorded++;
+      else unchanged++;
+      continue;
+    }
+    if (result.kind === 'rejected') {
+      const detail = result.detail === undefined ? '' : `: ${result.detail}`;
+      return {
+        error: `register of ${f.rel} rejected by the API (${result.code}, HTTP ${String(result.httpStatus)})${detail}.`,
+      };
+    }
+    const http = result.httpStatus === undefined ? '' : `, HTTP ${String(result.httpStatus)}`;
+    return {
+      error: `register of ${f.rel} unavailable (cause: ${result.cause}${http}). ${RUNBOOK}`,
+    };
+  }
+  return { recorded, unchanged };
+}
+
+/**
+ * The single ledger step every ALLOW goes through: validate P, verify the sealed phases, register P.
+ * ok:false is a DENY with the reason; an exception is caught here and is a DENY too.
+ */
+export async function registerBeforeAllow(
+  observation: Extract<Observation, { kind: 'ok' }>,
+  ctx: LedgerContext,
+  deps: ArtifactGateDeps,
+  log: Log
+): Promise<LedgerOutcome> {
+  try {
+    const current = observation.files.filter((f) => f.key.phase === observation.phase);
+    const sealed = observation.files.filter((f) => f.key.phase !== observation.phase);
+    if (observation.root === null)
+      log('git toplevel unknown: the observation is empty, the ledger is still asked');
+
+    const invalid = validateCurrent(current, observation, deps);
+    if (invalid !== null) return fail(invalid);
+
+    const mismatch = await verifySealed(sealed, observation, deps, log);
+    if (mismatch !== null) return fail(mismatch);
+
+    const registered = await registerCurrent(current, observation, ctx, deps);
+    if ('error' in registered) return fail(registered.error);
+
+    return {
+      ok: true,
+      summary: `ledger: phase=${observation.phase} sealed-verified=${String(sealed.length)} recorded=${String(registered.recorded)} unchanged=${String(registered.unchanged)}`,
+    };
+  } catch (e) {
+    return fail(
+      `unexpected error in the ledger step (${e instanceof Error ? e.message : String(e)}).`
+    );
+  }
+}

package/hooks/lib/artifact-producers.ts

@@ -0,0 +1,106 @@
+/**
+ * artifact-producers.ts — ARTIFACT_PRODUCER_AGENTS (RFC-044 F3, S4, PL-ADR-4; ratifies Q-PM-3).
+ *
+ * The agents that R7 of workflow-guard lets write a workflow artifact under
+ * project-guidelines/workflows/<wf>/<phase>/<type>.md: the 30 agents that carried `artifactStore` on their
+ * `tools:` line when F3 was planned (S556, measured again in S557). Bare names: the hook normalizes the
+ * `orchestrator:` prefix (normalizeAgentName) before asking.
+ *
+ * Frozen on purpose. A new producer is an edit of this list in a PR, never a side effect of a `tools:` line;
+ * the unit test asserts this set is a SUPERSET of the agents with `artifactStore` (when F4 removes the tool
+ * from everyone, that assertion turns vacuous and F4 rewrites it).
+ */
+
+const NAMES: readonly string[] = [
+  'adversarial-reviewer',
+  'agentic-architect',
+  'api-extractor',
+  'architecture-mediator',
+  'azure-devops-engineer',
+  'backend-architect',
+  'business-rule-miner',
+  'cicd-platform-engineer',
+  'ciclo-engineer',
+  'code-archaeologist',
+  'contract-architect',
+  'datamodel-architect',
+  'frontend-architect',
+  'frontend-engineer',
+  'harness-architect',
+  'harness-engineer',
+  'implementer',
+  'infra-architect',
+  'legacy-discoverer',
+  'legacy-synthesizer',
+  'methodology-researcher',
+  'operational-artifact-builder',
+  'planner',
+  'presentation-engineer',
+  'python-data-engineer',
+  'researcher',
+  'reviewer',
+  'schema-extractor',
+  'specifier',
+  'task-generator',
+];
+
+function refuser(constant: string): () => never {
+  return (): never => {
+    throw new TypeError(`${constant} is frozen: edit the list in artifact-producers.ts`);
+  };
+}
+
+function frozenSet(values: readonly string[], constant: string): ReadonlySet<string> {
+  const set = new Set(values);
+  const refuse = refuser(constant);
+  Object.defineProperties(set, {
+    add: { value: refuse },
+    delete: { value: refuse },
+    clear: { value: refuse },
+  });
+  return Object.freeze(set);
+}
+
+export const ARTIFACT_PRODUCER_AGENTS: ReadonlySet<string> = frozenSet(
+  NAMES,
+  'ARTIFACT_PRODUCER_AGENTS'
+);
+
+/**
+ * The artifact type the adversarial-reviewer may write. A LITERAL on purpose: artifact-gate.ts exports the same
+ * value (ADVERSARIAL_REVIEW_TYPE) but imports child_process and fs/promises, which would then be bundled into
+ * workflow-guard.mjs. The unit test asserts both are equal.
+ */
+export const PINNED_ADVERSARIAL_REVIEW_TYPE = 'adversarial_review';
+
+function frozenMap(
+  entries: readonly (readonly [string, ReadonlySet<string> | null])[]
+): ReadonlyMap<string, ReadonlySet<string> | null> {
+  const map = new Map(entries);
+  const refuse = refuser('VAULT_ONLY_WRITERS');
+  Object.defineProperties(map, {
+    set: { value: refuse },
+    delete: { value: refuse },
+    clear: { value: refuse },
+  });
+  return Object.freeze(map);
+}
+
+/**
+ * VAULT_ONLY_WRITERS (RFC-044 F3, S6c; R8 of workflow-guard). The agents whose Write is fenced to two holes only:
+ * their artifact under project-guidelines/workflows/<wf>/<phase>/<type>.md of a managed project (then R7 decides),
+ * and their OWN memory dir <project root>/.claude/agent-memory/<slug>/. Anything else is a DENY, before rules 1-7.
+ *
+ * The value is the set of artifact types the agent may write there; `null` = any type R7 accepts.
+ *   - adversarial-reviewer -> { adversarial_review }: R-6 ("MUST NOT write to the artifact under review") held by
+ *     the hook, not only by the charter.
+ *   - methodology-researcher -> null.
+ *
+ * Declared, not inferred from `tools:` ("has Write and no Edit/Bash" catches 9 agents; DV-P3 rejected deriving at
+ * run time). A subset of ARTIFACT_PRODUCER_AGENTS (asserted). Answers TD-392 only for these two; it stays open for
+ * the other 30 agents with Write.
+ */
+export const VAULT_ONLY_WRITERS: ReadonlyMap<string, ReadonlySet<string> | null> = frozenMap([
+  ['adversarial-reviewer', frozenSet([PINNED_ADVERSARIAL_REVIEW_TYPE], 'VAULT_ONLY_WRITERS')],
+  ['methodology-researcher', null],
+]);

package/hooks/lib/gate-logic.ts

@@ -5,7 +5,7 @@
  */
 
 export type RiskLevel = 'HIGH' | 'LOW';
-export type GateStrategy = 'AUTO_APPROVE' | 'ASK_HUMAN' | 'BLOCK_AND_REQUIRE';
+export type GateStrategy = 'ALLOW_LOW_RISK' | 'ASK_HUMAN' | 'BLOCK_AND_REQUIRE';
 
 export interface GateContext {
   workflowId: string;
@@ -38,7 +38,7 @@ export function classifyRisk(targetPhase: string): RiskLevel {
  * Derive the gate strategy based on context.
  * Rules (evaluated in order):
  *   1. HIGH risk → ASK_HUMAN
- *   2. default   → AUTO_APPROVE
+ *   2. default   → ALLOW_LOW_RISK (allowed without an approval check; the hook observes no approval)
  *
  * BLOCK_AND_REQUIRE exists as a type but has no trigger rule yet.
  */
@@ -50,9 +50,10 @@ export function deriveGateStrategy(ctx: GateContext): GateDecision {
     };
   }
 
-  // Default: AUTO_APPROVE
+  // Default: low-risk phases pass without any approval check (TD-373: the label
+  // must not claim an approval this hook never observed).
   return {
-    strategy: 'AUTO_APPROVE',
-    reason: `Phase '${ctx.targetPhase}' is low-risk — auto-approved.`,
+    strategy: 'ALLOW_LOW_RISK',
+    reason: `Phase '${ctx.targetPhase}' is low-risk — allowed without an approval check; no approval observed by this hook.`,
   };
 }