Run durable initiatives, Guild Stack

One-off runs remain first-class. Most Guild Stack work should stay simple: you ask for work, Guild Stack runs the lifecycle, and the evidence lands under .guild/runs/.

Use an initiative only when the goal needs durable progress across sessions, branches, releases, or multiple repos. An initiative gives the goal a home under .guild/initiatives/, but it is always opt-in. A plain run never creates or joins an initiative silently.

Try it: /guild:initiative new "unify auth across the apps"

Initiative · D8

map / active

Close only when three independent legs resolve

RunsEvidence landsprovenance.json
Opt inInitiative owns progressFour status axes stay separate.
D8 · 1ExecutionContributing work verified.
D8 · 2ReleaseRelease path and rollback stance resolved.
D8 · 3Docs syncdocs/v2 reconciled or explicit n/a.
CloseArchive honestlyclose decision

A passing run is evidence for the initiative. It is not, by itself, proof that the durable goal is closed.

Run, initiative, close gate

Start with the boundary:

A run produces evidence. An initiative owns progress.

Surface	What it is	Artifact	Audit asks
Run	One execution or analysis pass.	`.guild/runs/<run-id>/`	What was requested, what ran, what changed, what evidence closed the pass?
Initiative	The durable goal those runs contribute to.	`.guild/initiatives/active/<id>/`	What is defined, blocked, released, documented, and still open across sessions?
D8 close gate	The final initiative closure decision.	Initiative work items plus run provenance, release evidence, docs-sync evidence.	Are execution verified, release readiness resolved, and documentation sync resolved as separate facts?

Never collapse “this run passed” into “this goal is done.” A run can pass while its initiative stays open because release readiness, docs sync, or another work item still needs evidence.

When to use one

Use an initiative when a goal is too large for one run to represent honestly:

Audience	What the initiative gives you
Power Users	A durable control surface for progress, evidence, blockers, release state, docs-sync state, and cross-session next actions.
Beginner Users	A clear way to continue important work later without making every small request feel like project management.
Harness Developers	A file-backed lens over runs, provenance, status axes, registry rollups, and the D8 close gate.

The source contract is the v2 initiatives design plus the shipped module map: docs/v2/initiatives.md defines the opt-in durable-goal lens, and docs/v2/architecture/modules/initiatives.md maps it to the validator, status derivation, definition-ledger machinery, activity helpers, work-item helpers, and d8CloseGate in the plugin module.

Opt-in, always asked

A one-off /guild run creates no initiative directory and pays zero initiative cost. Guild Stack offers to attach a run to an initiative only when there is an opt-in signal:

you pass --initiative <id> or --initiative new,
you run a /guild:initiative ... command directly, or
your brief carries a durable-goal signal such as “ongoing,” “continue the prior work,” or “over the next month.”

With no signal and no flag, the run stays one-off. When a signal is ambiguous, Guild Stack asks whether to create, attach, or continue one-off. Incorrect attachment is worse than one clarifying question.

/guild:init has a design-fixed first-initiative offer, but it is opt-in and not forced.

The four status axes

An initiative manifest tracks four separate status axes. They stay separate because “the work is verified,” “the work is released,” and “the docs match the release” are different facts:

Axis	Answers
`definition_status`	Is the initiative clear enough to work on?
`execution_status`	Is the planned work done?
`release_status`	Has the work reached users or the target environment?
`documentation_status`	Do docs reflect the released state?

A human-facing status is derived from those axes. The definition ledger tracks what is known, assumed, blocked, or superseded; an initiative is not ready while a blocking definition item still needs definition.

What ships today

The initiative contract is partly code-enforced and partly manual-capture in v2:

Surface	Shipped state
Manifest contract	`guild.initiative.v1` validation and four-axis status derivation ship in the initiatives module.
Definition ledger	The closed ledger item shape and readiness rule ship; auto-populating ledger entries remains a later automation step.
Activity rows	The `guild.initiative_activity.v1` row schema and append/read helpers ship; command wiring that appends rows from every update remains later automation.
D8 close gate	The pure `d8CloseGate` function ships. The `/guild:initiative close` command dispatches the close flow as prose today, so operators capture the evidence against the frozen contract.
Release/docs work items	Stable work-item shapes and unresolved-leg population helpers ship. Auto-driven release/docs population is not the whole lifecycle engine yet.

That split is deliberate public honesty: the close-gate contract is real, but Guild Stack should not sound like it already auto-runs every initiative lifecycle step.

Where it lives on disk

An initiative is a plain directory under the consuming repo’s .guild/:

.guild/initiatives/active/<id>/
  initiative.yaml        summary.md         definition-ledger.md
  open-questions.md      decisions.md       roadmap.md
  work-items/  sessions/  runs/  artifacts/  release/  docs/  activity.jsonl

Continuity is state, not a prose progress log. Two artifacts carry most of the cross-run story:

Artifact	Role
`.guild/runs/<run-id>/provenance.json`	Per-run source record of which tasks, agents, skills, and decisions a run touched. Written at run close for every run, including one-off. Retained 90 days for one-off runs; until archive when initiative-attached.
`.guild/indexes/initiatives-registry.yaml`	A derived, rebuildable cross-initiative rollup. Deleting it loses no source truth because initiatives and run provenance remain canonical.

The registry is useful for status and list, but it is never the system of record.

Project scope vs workspace scope

By default an initiative is project-scoped: it lives in one repo and groups that repo’s runs. In a workspace, a workspace-scoped initiative (scope: workspace) lives at the workspace root and groups runs across member projects:

# .guild/initiatives/active/auth-revamp/initiative.yaml
id: auth-revamp
scope: workspace              # spans projects; child runs may inherit it
members: [api, web, mobile]
goal: "Unify auth across the three apps"

A lane under a workspace-scoped initiative gets federated recall: context assembly queries each member project’s wiki in place and source-tags every hit. Cross-project knowledge stays cross-project without a second copy. A workspace-scoped initiative is also the only initiative a child project may inherit by default, and only when the workspace’s initiative_default names it.

The close gate - three legs, in order

The D8 close gate has three separate legs. Release readiness and docs sync are not the same thing:

Exec. Contributing runs are verified, and execution_status is done.
Release. The release path is resolved, with release evidence and rollback stance folded into release_status.
Docs sync. Documentation impact is resolved. For feature-shipping initiatives, this includes reconciling docs/v2/** to shipped reality in the same rollout, or recording an explicit docs/v2: n/a <reason>.

The Operations phase supplies release evidence through release runbooks and recorded release/rollback facts. Initiative close still owns the closure decision. A run may pass, a release may be ready, and the initiative can still remain open because docs sync is unresolved.

The close contract is real; automation is bounded

The pure D8 gate logic ships. Some writer and production command wiring around that contract still relies on explicit operator capture, so the page should not be read as a promise of automatic initiative lifecycle management.

Commands

All initiative operations hang off one noun, /guild:initiative <sub-verb>:

Command	What it does
`/guild:initiative new [brief]`	Start the durable-goal flow and definition-ledger capture.
`/guild:initiative status [id]`	With an id: show definition, progress, release, docs, and next action. Without an id: show a cross-initiative rollup.
`/guild:initiative list [--archived]`	List active initiatives, with `--archived` including archived ones.
`/guild:initiative resume [id]`	Attach the current session by choice and load the initiative context.
`/guild:initiative update <id>`	Record progress, a question, a decision, scope change, or ledger update.
`/guild:initiative archive <id>`	Move to `archived/` with a recorded reason.
`/guild:initiative restore <id>`	Move an archived initiative back to active.
`/guild:initiative close <id>`	Apply the D8 exec/release/docs-sync close gate.

Archiving moves the initiative; it does not delete the record.