effort-lifecycle.md

type	ProcessSpec
summary	Defines what an effort note must preserve while work is active and how it closes.
id	SPEC-0002
spec-status	active
last-updated	2026-05-19
aliases	SPEC-0002

Effort lifecycle

Summary

Efforts are bounded execution records against a frozen set of specs. They are the durable home for plan, execution notes, deviations, and closure — everything that would otherwise get lost in chat or commit messages.

Goals

• make active work legible at a glance
• preserve deviations and execution evidence
• give closure, audit, backport, and compounding work an explicit but lightweight home

Non-Goals

• replacing specs with implementation detail
• using effort notes as permanent design documentation
• tracking day-to-day chatter; keep execution notes load-bearing

Requirements

Must

• Every effort note lives under docs/efforts/ and is named YYYY-MM-DD-HH-MM-<slug>.md.
• Frontmatter contains:
  • id
  • name
  • created-at
  • plan-approved-by (blank until real human approval)
  • status
  • summary
• Body contains, in order:
  • Scope
  • Spec Set (Frozen) — wikilinks to every governing SpecLike note plus its spec id; links in this section are indexed as the canonical frozen-spec relation
  • Stories In Scope (Frozen) — wikilinks to embedded story nodes using canonical SPEC-####.US# display text, plus selected acceptance-criterion wikilinks using canonical SPEC-####.US#.AC# display text; links in this section are indexed as canonical frozen-story / frozen-criterion relations to embedded graph nodes
  • Spec Coverage Checklist — one item per selected story / acceptance criterion, reusing the same durable story / criterion wikilinks from Stories In Scope (Frozen)
  • Plan — populated by plan and approved before execution
  • Original Intended Delivery — what the frozen stories said this effort intended to ship
  • Actual Delivered — what the effort actually shipped, deferred, or changed
  • Execution Notes — appended during work as the effort-local journal; never rewritten historically
  • Deviations — each deviation names what changed and why
  • Compounding Follow-ups — repeated friction, missing support, capability gaps, and smallest durable fixes
  • Closure Checklist — one checklist item for implementation complete, audit run, backport complete, and compounding triage complete
  • Status — current effort status using the repo's effort-status vocabulary
• plan-approved-by is set only by a real human name. Placeholders (user, owner, <pending>, handles, shorthand) are forbidden.
• created-at is the canonical effort creation/start timestamp. Filename timestamp remains naming/discovery metadata only.
• created-at, plan-approved-at, and each timestamped Execution Notes entry use UTC DateTime format with minute precision, e.g. 2026-05-19T18:42Z. Bare dates are for spec last-updated, not effort event history.
• id uses the EFF-XXXX format and is mirrored into aliases:.
• Starting an effort includes choosing which ready user stories and criteria are in scope now, then linking each selected embedded node from Stories In Scope (Frozen) with a durable block-target wikilink.
• Efforts own story execution relations by linking selected story and acceptance-criterion nodes in Stories In Scope (Frozen); stories do not carry live effort links.
• Effort-local task lists, coverage checklists, rationale notes, and execution notes should reuse those durable story / criterion wikilinks when they point at selected scope. Plain labels like [SPEC-0007.US1] are readable but not graph edges.
• Execution Notes entries are the effort-local log for human decisions, agent surprises, new conclusions, validation evidence, blockers, handoffs, and resume points. Use this shape: - 2026-05-19T18:42Z [decision] Colthorp approved the narrower scope because ....
• Required Execution Notes entry kinds are [decision], [surprise], [learning], [validation], [blocker], [handoff], and [resume]. Use [note] only for load-bearing execution evidence that does not fit another kind.
• Human decisions and agent surprises stay in the effort unless they change durable spec truth, code behavior, or reusable operating guidance. In that case, backport the changed truth to the owning spec, reference, code doc, or skill, and keep the timestamped effort entry as the provenance trail.
• If a selected story is not fully delivered when the effort closes, record the carry-forward in Actual Delivered / Deviations and move the story back to an appropriate non-complete state rather than forcing closure in the spec.
• Deviations are recorded as they happen, not backfilled at closure.
• An effort closes only after:
  • every coverage checklist item is [x],
  • every open deviation is resolved or explicitly carried forward,
  • required audits have run,
  • durable learnings that changed authoritative contracts have been backported via backport,
  • repeated friction and missing agent capabilities have been triaged via compound, and
  • every Closure Checklist item is [x].

Should

• One effort per focused change; split multi-subsystem work into separate efforts.
• Cross-reference related efforts instead of merging their scopes.
• Small efforts may keep required sections terse, but should still preserve frozen spec/story/criterion scope and the closure gates.

May

• Link to external tickets or PRs from Execution Notes.
• Keep terse effort-local rationale in Execution Notes even when no spec, reference, or code doc update is warranted.

Effort lifecycle states

The full EffortStatus vocabulary is enumerated in .rhizome/ontology/schema.graphql. Use these values in status: truthfully:

• planned — the effort exists and scope is frozen, but active execution has not started yet. Use this between effort-new and plan finishing, and between plan-approval and the first execution edit.
• active — execution is currently live. Keep status, Execution Notes, and Deviations current while work is underway.
• complete — the bounded slice is finished and the effort stands as the completed delivery record. See the closure procedure below; do not flip to complete until every closure gate is satisfied.
• archived — historical effort retained for provenance. Use this for retired or cancelled efforts that should remain discoverable but should not be treated as live execution surface. Cancellations land here only after a Deviation entry records why.

SpecStatus (proposed, active, superseded, archived) and UserStoryStatus (draft, ready, satisfied) are independent of effort status. A complete effort can target an active spec whose stories have been promoted to satisfied, while a planned effort can target a proposed spec only if the effort is explicitly story-shaping work.

Closure procedure

A complete effort is a closure that survives audit, backport, and compounding triage. To close, run these in order. Steps 2–4 MUST be invoked as separate sub-agents, each using the named skill (alignment-audit, backport, compound) and receiving the effort note path plus the supporting inputs called out below. Name the skill by name and let the harness resolve it. The phases do not run inline inside the implement conversation, and the implement-phase agent does not flip status: complete itself.

1. implement lands the last code/test/doc edits. Append Actual Delivered against the existing Original Intended Delivery baseline (do not rewrite the baseline). Carry-forward any partially delivered story by recording it in Actual Delivered and Deviations, and move the story back to a non-satisfied state. The implement-phase agent's last action on a closing effort is to spawn a sub-agent that uses the alignment-audit skill (step 2) with the effort note path.
2. alignment-audit (sub-agent uses the alignment-audit skill). Inputs: effort note path, frozen Spec Set wikilinks, frozen Stories In Scope wikilinks, touched code paths, recorded deviations. Produces typed findings against the effort's frozen scope, the spec set, the linked references, and the touched code. The audit emits findings only; it does not mutate specs or close the effort. Tick the audit item in Closure Checklist only after required audits have run and blocking findings are resolved or carried forward.
3. backport (sub-agent uses the backport skill). Inputs: effort note path, audit findings from step 2, deviations marked for spec/reference/code-doc reconciliation, and timestamped [decision], [surprise], or [learning] execution notes that changed authoritative truth. Applies edits surfaced by the audit: spec bodies updated to match delivered reality, reference docs refreshed, code docs tightened where needed, and carry-forward work recorded where needed. Tick each Spec Coverage Checklist item only when it is actually true. Reconcile any remaining gap between Original Intended Delivery and Actual Delivered. Tick the backport item in Closure Checklist when durable reconciliation is complete.
4. compound (sub-agent uses the compound skill). Inputs: effort note path, contents of Compounding Follow-ups, repeated-friction / missing-evidence / missing-access / agent-blocker observations from execution. Triages each into the smallest durable home (test, script, skill, capability request, follow-on effort). Tick the compounding item in Closure Checklist when triage is complete.
5. Flip status to complete only when all closure gates are satisfied:
   • every Spec Coverage Checklist item is [x],
   • every open Deviations entry is resolved or explicitly carried forward,
   • every Closure Checklist item is [x].

After closure the effort note is historical record. See SPEC-0051 lifecycle immutability for the rules governing post-closure edits and how follow-on efforts pick up where prior efforts closed.

Open Questions

• whether the repo wants mandatory approver fields beyond plan-approved-by