artifact-gates

name	artifact-gates
description	Skill for working with artifact contracts — the file-level dependency system that prevents pipeline failures by ensuring tasks produce expected outputs and only start when required inputs exist.
user-invocable	true
disable-model-invocation	false

Artifact Gates — File-Level Pipeline Enforcement

Use this skill when you need to understand or work with the artifact contract system that enforces file-level dependencies between tasks.

What Problem This Solves

Beads task dependencies (bd dep add) ensure tasks start in order, but they don't verify that a task actually produced its expected output files. This causes two classes of pipeline failure:

1. Phantom completion: Task closes in Beads but didn't create expected output files. Downstream tasks launch, find no input, and fail.
2. Premature dispatch: A task that consumes results starts before those results exist because Beads considers it "ready" (all task-level deps closed).

The Three Artifact Properties

Each task can have these properties stored in Beads notes:

Property	Format	Meaning
PRODUCES:file1, file2	Comma-separated paths	Files the task MUST create
REQUIRES:file1, file2	Comma-separated paths	Files that MUST exist before dispatch
GATE:path/to/report.json	Single file path	Validation artifact that must exist AND pass

How to Set Artifact Contracts

During Planning

The orchestrator creates tasks with artifact contracts in Beads notes:

bd update <task-id> --notes "PRODUCES:output/<task-id>/experiment_metrics.json, output/<task-id>/figures/"
bd update <task-id> --notes "REQUIRES:output/data.csv"
bd update <task-id> --notes "GATE:output/<task-id>/validation_report.json"

Manually (for existing tasks)

# Add output contract
bd update bd-42 --notes "PRODUCES:demos/coupled-decisions/output/bd-42/experiment_metrics.json"

# Add input requirement
bd update bd-43 --notes "REQUIRES:demos/coupled-decisions/output/bd-42/experiment_metrics.json"

# Add validation gate
bd update bd-44 --notes "GATE:demos/coupled-decisions/output/bd-42/validation_report.json"

Enforcement Points

1. Pre-Dispatch Check (Orchestrator)

Before dispatching any task, the orchestrator verifies:

• All REQUIRES files exist on disk
• GATE file exists AND contains PASS verdicts
• If either fails, the task is skipped and retried later

2. Merge Verification (Orchestrator)

Before merging any branch, the orchestrator checks:

• Reads PRODUCES from Beads notes
• Verifies each listed file exists in the worktree or project root
• If any PRODUCES file is missing, the merge is deferred and the agent may be retried

3. Agent Prompt (Orchestrator → spawn-agent.sh)

The orchestrator writes each agent's prompt with the artifact contract:

• Agent is told which files it MUST create (PRODUCES)
• Agent is told which files must exist (REQUIRES) — and to report BLOCKED if missing
• Agent is told about any GATE validation check to perform before starting

Working With Artifact Contracts as an Agent

At Startup

1. Read your task notes: bd show <your-task-id>
2. Check for REQUIRES: — verify each file exists
3. Check for GATE: — verify the file exists and contains passing verdicts
4. If anything is missing, report blocked:

   bd update <your-task-id> --notes "BLOCKED: Required artifact missing: <path>"
   

During Work

• Keep track of which PRODUCES files you need to create
• Create output files before closing the task
• Commit output files to your branch

Before Closing

1. Verify all PRODUCES files exist:

   ls -la path/to/expected/output.json
   

2. Only close the task after all artifacts are created
3. If you cannot create a required output, document why and do NOT close the task

Gate File Formats

A GATE file is a JSON validation report. The pre-flight check recognizes these formats:

// Format 1: Top-level verdict
{"verdict": "PASS"}

// Format 2: Per-stage verdicts
{
  "stage_1": {"verdict": "PASS"},
  "stage_2": {"verdict": "PASS"},
  "stage_3": {"verdict": "PASS"}
}

// Format 3: Array of experiment verdicts
{
  "experiments": [
    {"name": "encoding", "verdict": "PASS"},
    {"name": "ablation", "verdict": "PASS"}
  ]
}

If any verdict is not PASS, the gated task remains blocked.

Example: Multi-Phase Pipeline

Task 1: Generate Data
  PRODUCES: output/data.csv, output/policies.json
  REQUIRES: (none)

Task 2: Run Experiments
  PRODUCES: output/bd-42/experiment_metrics.json
  REQUIRES: output/data.csv

Task 3: Validate Results
  PRODUCES: output/bd-43/validation_report.json
  REQUIRES: output/bd-42/experiment_metrics.json

Task 4: Write Paper            ← This is the common failure point!
  PRODUCES: output/bd-44/paper.pdf
  REQUIRES: output/bd-42/experiment_metrics.json
  GATE: output/bd-43/validation_report.json

Task 5: Build Webapp
  PRODUCES: output/bd-45/webapp.html
  REQUIRES: output/bd-42/experiment_metrics.json

Without artifact contracts, Task 4 would start as soon as Task 3 closes in Beads — even if validation_report.json doesn't exist or contains FAIL verdicts. With artifact contracts, Task 4 is held until the file exists and passes.