Workflow Run Contract

A workflow run is complete only when a future agent can see what ran, what was promoted, what was deferred, what state changed, and which generated surfaces were refreshed.

This is the common completion bar for every page in wiki/workflows/. Individual workflow pages own domain-specific sources and decisions. This page owns the invariant that the run leaves proof.

Routing

Open this page when:

running any workflow manually
writing or updating a workflow page
converting a workflow into an automation
deciding whether a workflow result should update durable wiki pages
auditing whether a scheduled job actually completed

Completion Invariant

Every workflow run must make five decisions explicit:

Decision	Required proof
What sources were read?	Source list, command output, URLs, raw files, or repo paths.
What changed?	Changed wiki pages, generated files, code files, or "No durable update needed."
What did not get promoted?	Deferred items, blockers, low-signal findings, or no-op rationale.
What state advanced?	`state.json`, raw cursor files, sync timestamps, scheduler status, or no state change.
What validation ran?	Commands, checks, qmd queries, screenshots, test output, or explicit skipped-check rationale.

Standard Run Shape

Read the workflow page and any canonical automation or skill it references.
Confirm sources, credentials, repo path, and side-effect boundaries.
Run the ordered steps, keeping raw/source material separate from compiled wiki truth.
Write output under outputs/<YYYY-MM-DD>/<slug>/<agent>.md when the workflow is scheduled, long-running, or evidence-heavy.
Promote only facts that pass the page's promotion criteria.
Update state.json only for work that truly completed.
Append wiki/log.md for durable or user-visible work.
Follow Generated Surface Contract for index, qmd, packs, registries, redirects, and stateful ledgers.

Generated Closeout

The closeout depends on what changed:

Change	Minimum closeout
Handwritten wiki page	`npx tsx scripts/build-index.ts`; `qmd update && qmd embed`; log when user-visible.
Workflow, resolver, or routing page	Page closeout plus `npm run routing-doctor`; refresh agent packs when source context changed.
Skill source	`npm run skill-registry`; `npm run skills:check`; routing check; page closeout.
Generated pack/capsule source	`npm run agent-packs:refresh`; `npm run agent-packs:check`; page closeout.
Automation schedule or state model	Check freshness and scheduler surface; update state only through the owning run or script.

If a generated surface changes, say which source or generator made it change. Do not make the generated projection the new authority.

Promotion Rule

Workflow output is not automatically wiki truth. Promote when the finding changes durable context:

a person, project, tool, decision, workflow, or skill changes
repeated friction should become a skill, automation, style rule, or guardrail
a source corrects stale compiled truth
a run proves an operational state that future agents need

Do not promote routine noise, transient reminders, raw private text, or low-confidence findings. Preserve them in output when useful.

State Discipline

state.json should tell the next agent what is fresh. It must not hide partial failure.

State class	Update when
`automations.<slug>`	The scheduled check completed and wrote output/no-op/blocker proof.
`syncs.<source>`	The external source was actually collected or confirmed current.
compile cursors	The source was actually reviewed, promoted, or explicitly deferred through that cursor.
generated-surface timestamps	The owning generator or index command completed successfully.

For sub-daily jobs, use ISO timestamps. Date-only state hides stale four-hour loops.

Failure Handling

If a workflow cannot finish:

Write the blocker in output or the final answer.
Leave source sync or compile state stale when collection/promotion failed.
Do not claim qmd, packs, registry, or redirects are current unless the command ran.
Leave a concrete next action: credential needed, source missing, ambiguity, command failure, or validation gap.

Timeline

2026-07-01 | Added generated closeout classes and removed the self-link from related pages so this contract cleanly points to proof, state, and generated-surface owners. Source: User request, 2026-07-01
2026-07-01 | Created as the shared proof/state/promotion/validation contract for every workflow page. Source: User request, 2026-07-01

Source: User request, 2026-07-01