Forge — major processes & flow maps

Diagrams below use ```blueprint-diagram fences on the published handbook; GitHub shows the source as a fenced block.

Guide · Updated · Source

1. Forge iteration lifecycle (high level)

Forge iteration delivery cycle

How forward delivery and inspect-and-adapt feedback run in parallel across one bounded Forge iteration.

  1. Forge iteration lifecycle (high level)Frames the dual-lane view of ceremonies and outcomes inside one iteration.
  2. Lane AThe forward path from intake through ceremonies toward release outcomes.
  3. handoffExplicit transfer when work crosses ceremony or ownership boundaries.
  4. shared outcomeThe traceable increment and evidence the iteration must leave behind.
  5. Lane BThe parallel inspect-and-adapt path across iteration ceremonies.
  6. inspect / adaptCeremonies review progress against acceptance criteria and blockers.
  7. feedbackLearnings loop back into continuous Ore intake and upstream planning.

2. Work unit hierarchy

Product backlog
  └── Ore              (raw, unrefined)
        └── Ingot      (refined, plannable)
              └── Spark (executable, testable)

Daily execution
  └── Charge           (today's selected Sparks)

Time horizon
  └── Forge iteration  (one delivery cycle containing Sparks across phases A–F)
Level Forge term Comparable concept Typical lifespan
Coarsest Ore Epic or feature request (pre-refinement) Days to weeks
Mid Ingot User story or feature (refined, ready) One iteration
Finest Spark Task or sub-task (executable) One focused session (~1–4 hours)
Daily set Charge Daily commitment One day
Cycle Forge iteration Sprint or release cycle 1–2 weeks

Spark = Task (WBS mapping)

In projects with an existing milestone → epic → story → task hierarchy, Forge terms map directly — no parallel namespace:

Existing level Forge equivalent ID example
Epic / feature request Ore M1E3 (pre-refinement)
Story (refined) Ingot M1E3S2
Task (implementation slice) Spark M1E3S2T4

Spark IDs inherit from the WBS scheme. Spark-specific data (state, DoD, journal) lives in forge-logs/, not in the requirements tree. If existing Stories already carry clear acceptance criteria, they are effectively Ingots — no extra ceremony needed.

Exploration spike vs Forge Spark

An exploration spike (also discipline spike) is time-boxed learning—prototyping, feasibility checks, unknowns—whose primary outcome is evidence and a written record, not a shippable increment. It is not a Forge Spark: a Spark is the smallest committed delivery unit (task-level) in the Ore → Ingot → Spark → Charge pipeline.

Exploration spikes often use Versona sessions with work_item_kind spike_discipline or spike_general, live under forge-logs/versona/, and close with outputs/SPIKE-CLOSE.md plus Ember Log when decisions are made. They may spawn new Ore, Ingots, or WBS lines; follow-up work then appears as normal Sparks (often discover: or design: flavored). Full lifecycle: Discipline exploration spike — lifecycle and anchors.

Versona sessions under forge-logs/

Versona invocation context (per-call folders, inputs/outputs, optional transcripts) should live under forge-logs/versona/<actor>/<session-id>/ as the default layout—see Versona framework — kinds, interfaces, processes, sessions §7. Optional enriched artifacts (ledger, JSON manifests, diagram IR, graph append-only logs) extend that model per Versona operating model — process-first layout, artifacts, and tooling split. Teams that keep all Forge state under forge/ may use the alias forge/versona-sessions/ instead; pick one convention per repo and document it in forge/ or sdlc/README.md. Cursor rule templates in blueprints live under Versonas — discipline-focused virtual personas (see Source layout there).

3. State model

Forge work-unit states

How Ore advances through refinement, execution, and release gates to a governed outcome.

  1. State modelFrames the lifecycle states that govern Forge work units on this page.
  2. StartWork enters as raw Ore or returns from retro as new intake.
  3. Core steps (see walkthrough below)Units move through refinement, Charge, Done, and gate review.
  4. OutcomeWork exits as Released after the gate or Rejected with a recorded reason.
  5. Note: | Raw, unrefined input |Anchors Ore as the default entry state for unrefined intake.
State Meaning
Ore Raw, unrefined input
Ingot Refined, plannable work
Spark Decomposed, executable work
In Charge Active in today's daily set
Blocked External impediment prevents progress
Banked Intentionally paused with preserved context (strategic)
Done Evidence gathered, ready for Assay Gate
Released Passed Assay Gate, shipped
Rejected Not viable; closed with reason

4. Refinement flow (Ore → Ingot)

Ore to Ingot refinement

How refinement shapes raw Ore into plannable Ingots ready for iteration planning.

  1. Refinement flow (OreRefinement begins with raw Ore selected for shaping at the ceremony.
  2. Ingot)Refined work exits with enough clarity for planning decomposition.

5. Planning flow (Ingot → Sparks → iteration scope)

Ingot to iteration scope

How planning decomposes Ingots into Sparks and bounds what one iteration will deliver.

  1. Planning flow (IngotPlanning starts from a refined Ingot ready for decomposition.
  2. SparksIngots break into executable, testable Sparks with inherited WBS IDs.
  3. iteration scope)The bounded set of Sparks committed for one Forge iteration.

6. Daily execution loop

Daily Charge execution gate

How daily sync confirms the Charge and routes blockers through refine or escalate paths.

  1. Current stateToday's Charge reflects which Sparks are active in execution.
  2. Checkpoint / gateThe team checks whether each Spark can proceed or needs intervention.
  3. refine or escalateRework scope, unblock, or escalate when the gate does not clear.
  4. Continue flowCleared Sparks proceed through bounded execution toward Done evidence.

7. Assay Gate flow

Assay Gate release decision

How strict release review decides whether Done work may ship as Released.

  1. Current stateSparks marked Done arrive with gathered evidence at the gate.
  2. Checkpoint / gateThe Assay Gate judges evidence quality against release criteria.
  3. refine or escalateRework evidence or escalate when the release bar is not met.
  4. Continue flowPassed work advances to Released with governed ship approval.

8. Versona flow (sessions and discipline work)

Versona session decision gate

How bounded Versona sessions support discipline work at Forge decision points.

  1. Current stateA decision point or discipline question triggers optional Versona invocation.
  2. Checkpoint / gateThe session checks whether discipline input is ready to proceed or merge.
  3. refine or escalateRework inputs or escalate when structured output is insufficient.
  4. Continue flowAccepted session outputs inform the next Forge ceremony or Spark work.

9. Cross-phase mapping (A–F) in one iteration

Phase Where it happens in Forge
A Discover Continuous Ore intake + discover: Sparks
B Specify Refinement (Ore → Ingot) + specify: Sparks
C Design Planning decomposition + design: Sparks
D Build Charge execution + build: Sparks
E Verify Assay Gate + verify: Sparks
F Release Assay Gate pass + release: Sparks

10. Flow details (walkthrough)

Iteration lifecycle — Ore intake is continuous; Refinement shapes selected Ore into Ingots with enough clarity for Planning. Inside the iteration, daily syncs confirm the Charge and surface blockers. Review assesses evidence quality; the Assay Gate makes the strict release decision. Retro captures learning that feeds back as new Ore.

Work unit hierarchy — Forge terms layer on existing WBS conventions. Ore maps to pre-refinement epics/features; Ingots to refined stories; Sparks to tasks. The Charge is a daily view, not a separate backlog. Forge iterations align with milestones in the project's existing structure.

State model — The key distinctions from a simple Kanban board: (1) Banked vs Blocked separates strategic pause from external impediment, (2) Done is not Released until the Assay Gate passes, and (3) Rejected items are closed with a reason rather than silently deleted.

Versonas — Discipline virtual personas are invoked at decision points (refinement, pre-build, pre-release) for §5 structured output or other discipline work—not on every action. When using the §5 report shape, each Versona uses its bridge document to calibrate review depth to the current SDLC phase (Versona framework — kinds, interfaces, processes, sessions §1–2).