# Workflow kinds (PND-094)

Forge has THREE workflows, not one. Forcing the 18-step greenfield
methodology onto a live project produces fiction ("phase complete"
when the phase never applied). Pick the right one.

## The three kinds

- **greenfield** -- a NEW app from zero. The canonical 6 phases /
  18 steps (full doctrine: `workflow`, `workflow-phases`).
- **corrective** -- FIX a defect in a live project. Compact 6
  stages: triage -> reproduce + root-cause -> implement -> validate
  (iterative) -> **refresh docs** -> close.
- **evolutive** -- EXTEND / improve a live project. Compact 6
  stages: triage -> design/fit -> implement -> validate (iterative)
  -> **refresh docs** -> close.

corrective + evolutive BOTH require the docs-refresh stage: update
README / ARCHITECTURE / DESIGN / manual + the graph for whatever
changed. No doc drift.

## How Forge decides + acts

The orchestration is DETERMINISTIC code (`src/workflow/orchestrator.ts`),
not LLM judgement. You drive it through verbs:

1. **Open a workflow with `yujin.workflow.start({request})`.** It
   classifies the kind (regex over the request + whether the project
   has code -- `src/workflow/select.ts`). When the result is
   `needs_confirm:true`, ASK the user "greenfield, correctivo o
   evolutivo?" and call again with `{kind}`. Do NOT silently assume.
   `start` then creates the instance (WFL-NNN) + **spawns one pending
   per canonical task, in mandatory order**. Several workflows can
   coexist (keyed by name) -- a fix and a feature run side by side.
2. **Stages are NOT pendings; tasks are.** Work the task pendings in
   order. The `yf pending close` gate REFUSES to close a task while an
   earlier-order task is still open (override: `--force-order`). When
   every task closes, the workflow **auto-closes** -- you do not close
   it by hand.
3. **Add tasks at discretion.** If the user OR you decide a
   corrective/evolutive task is needed mid-workflow, add it with
   `yujin.workflow.add-task({code, title})` -- it appends at the end of
   the order (flagged `ad_hoc`).
4. **Edit the phases/tasks on request.** `yujin.workflow.configure({patch})`
   rewrites the project's editable definitions
   (`.forge/workflow-config.json`); the code default stays recoverable
   (`yf workflow config --reset`).
5. **Log the evolution.** As you cross stage/step boundaries, call
   `yujin.workflow.log-step(...)` -- it writes `docs/WORKFLOW_LOG.md` +
   `workflow.evolution[]` so the project records its own workflow
   history. Greenfield detail = the 18-step flow (`workflow`,
   `workflow-phases`); never force it on a live project.

## Relation to the request lifecycle

The pending request-lifecycle (add -> note -> close with history) is
the MICRO level (per task). The workflow is the MACRO level (per
project, with stages). They are now the SAME store: a workflow task IS
a pending item (with a `workflow` link). The instance names the stages;
its tasks are pendings closed in mandatory order.

## Canonical steps source

The canonical step definitions live in `src/workflow/definitions.ts`
(the immutable DEFAULT + disaster-recovery source). A project may
override them in `.forge/workflow-config.json` (edited via
`yujin.workflow.configure`); a `.default.json` snapshot keeps the
default recoverable. The worker-canonical layer plugs in later, same
pattern as doctrines + lessons.
