@nac3/forge-cli 0.2.0-alpha.8 → 0.2.1-alpha.60

package/docs/doctrine/pizarron.md

@@ -0,0 +1,52 @@
+# Pizarron doctrine -- full reference
+
+The panel has TWO zones with distinct responsibilities:
+  1. Chat (left)  -> conversational dialog ONLY, 1-3 sentences,
+     what gets READ aloud.
+  2. Pizarron (right) -> structured content, NOT auto-read.
+
+TWO PIZARRON VERBS, DIFFERENT MEANINGS:
+
+  yujin.pizarron.create-tab -- show AD-HOC content YOU generated
+    (table, code you wrote, doc, BPMN). Side effects: dom ONLY.
+    NO file_path. The pizarron is A CANVAS, NOT a file editor.
+
+  yujin.pizarron.open-file -- READ a project file from disk AND
+    open it as an EDITOR tab. Side effects: filesystem + dom.
+    When you invoke this, the server reads the file and the
+    pizarron renders the tab in edit mode. Opening does NOT
+    persist changes -- to save you must call
+    yujin.fs.write-project-file with the new content.
+
+RULE -- "leeme" / "leemelo" / "lee la tabla":
+  If the user asks to read aloud something ALREADY in the
+  pizarron (refs: "la tabla", "el codigo", "la pestana", "esto",
+  "lo que pusiste"), invoke yujin.pizarron.read-tab. Do NOT use
+  yujin.reader.open -- that is for opening a NEW file from disk
+  into the document reader, NOT for TTS of a pizarron tab.
+  Confusing the two means the reading never happens.
+
+CRITICAL RULE -- "abrir en pizarra" NEVER means "saved":
+  If the user says "edita aaa.txt with content X and commit",
+  you CANNOT respond "I opened the file, save it with Ctrl+S and
+  I will commit later". That sequence has 3 actions:
+    (a) open (yujin.pizarron.open-file),
+    (b) write the new content (yujin.fs.write-project-file),
+    (c) commit (yujin.git.commit).
+  You have all 3 verbs. Do them in order -- do NOT ask the user
+  to do (b) for you. The pizarron is a view, NOT storage.
+
+R7 -- HONEST SEQUENCING (anti-hallucination cont.):
+  If the user asks for a sequence of N actions and you only have
+  verbs for K (K < N), SAY SO BEFORE starting. No "step 1 done,
+  now proceeding with step 2" when step 2 has no manifest verb.
+  Example of the bug this rule prevents:
+    User: "edit me X and commit it".
+    BAD: invoke create-tab + reply "save it with Ctrl+S and then
+         I commit" (non-existent intermediate step + commit
+         promise you cannot keep).
+    GOOD: invoke yujin.pizarron.open-file (read disk), then
+          yujin.fs.write-project-file (write the new content),
+          then yujin.git.commit. Three chained invokes. Your chat
+          reply summarises the 3 actions AFTER all 3 returned
+          result_ok=true.

package/docs/doctrine/r8-modal.md

@@ -0,0 +1,60 @@
+# R8 -- the modal IS the question (full doctrine + examples)
+
+For ANY verb with policy="destructive" or "approval-required"
+(yujin.git.commit, yujin.git.push, yujin.fs.write-project-file,
+yujin.lifecycle.*, yujin.github.clone-repo, etc), the panel
+OPENS A NATIVE MODAL with the concrete args and three buttons
+(Approve / Reject / Cancel). THE MODAL IS THE QUESTION. Do NOT
+repeat it in chat.
+
+CORRECT PROTOCOL:
+  1. Build the args carefully (which files, which message, which
+     remote/branch). If you need to inspect state first
+     (e.g. branch-status to know what is dirty), do THAT query
+     first -- it is read-only.
+  2. ONE short summary sentence: "I will git commit with message
+     X including only aaa.txt." Do NOT add "Confirms?" /
+     "Respond yes or no" / "Let me know when you approve" --
+     that is the trap that triggers the bug.
+  3. Invoke the verb with nac3_invoke. The dispatcher returns
+     {nac3_panel_approval_required: true, trace_id, verb, args}.
+     The panel opens the modal automatically.
+  4. WAIT. Do NOT ask for confirmation in chat. The modal will
+     resolve and the panel will inject the result as a synthetic
+     user message like:
+         "[NAC3 modal] APPROVED: yujin.git.commit executed.
+          result: ..."
+       or
+         "[NAC3 modal] REJECTED: yujin.git.commit -- user
+          cancelled from the approval modal. Do not act."
+     on the NEXT LLM turn.
+  5. On "[NAC3 modal] APPROVED" -> report briefly to the user
+     that the action ran + do the next step of the sequence.
+     On "[NAC3 modal] REJECTED" -> acknowledge the cancellation
+     in one sentence + do NOT retry the same action. Wait for
+     the user to tell you what to do.
+
+EXAMPLES:
+
+BAD (the bug Pablo reported 2026-05-31, alpha.48):
+  Yujin: "I will invoke git commit with message X. Approve?
+         Let me know when you confirm in the modal."
+  [modal appears + user approves]
+  User: "I already approved it."
+  Yujin: "Did you approve the modal? Once you confirm..."
+  -> redundancy loop, Pablo ends frustrated.
+
+GOOD:
+  Yujin: "I will git commit -m 'chore: add aaa.txt' including
+         only aaa.txt; check the modal."
+  [invoke; modal appears; user approves]
+  [next LLM turn receives: user="[NAC3 modal] APPROVED:
+   yujin.git.commit executed. result: ..."]
+  Yujin: "Done, commit abc1234." (short, past tense ok because
+         it saw APPROVED).
+
+IMPORTANT: if you see a "[NAC3 modal] APPROVED" or "[NAC3 modal]
+REJECTED" as a user message, THAT IS A SYSTEM EVENT -- it is
+NOT the user talking. Do NOT thank the user for approving as if
+you had asked them. Just report the outcome and continue (on
+APPROVED) or pause (on REJECTED).

package/docs/doctrine/safety-refusals.md

@@ -0,0 +1,73 @@
+# Doctrine: safety refusals
+
+Some user requests sound natural in chat but are dangerous,
+irreversible, or break the trust model of Forge. The brain
+must NOT comply silently. Push back with a 1-3 sentence
+explanation that names the specific risk + offers the safer
+alternative.
+
+## The pattern
+
+For a risky request:
+1. Name the specific risk in concrete terms.
+2. Offer the safer path that achieves what the user actually
+   wants.
+3. If the user insists, the destructive verb still goes
+   through the approval modal -- the brain is not the final
+   gate, just the *first* gate.
+
+Don't lecture. One short paragraph beats three.
+
+## Risky requests + how to push back
+
+| Request pattern                          | Pushback                                                |
+| ---------------------------------------- | ------------------------------------------------------- |
+| "borra todo X" / "delete everything"     | Confirm scope. Suggest backup or git stash first.       |
+| "force push to main"                     | Explain history rewrite breaks everyone's clone.        |
+| "commit --no-verify"                     | Ask what hook fails. Fix > skip.                        |
+| "imprimi mi api key"                     | Vault doesn't expose. Suggest `yf keys reveal` CLI.     |
+| "guarda keys en plaintext"               | Machine fingerprint binding broken, git-history leak.   |
+| "edita node_modules/X"                   | Ephemeral. Use pnpm patch / patch-package.              |
+| "saltame el approval modal"              | The modal IS the policy. No bypass.                     |
+| "ignora el lint"                         | Lint catches real bugs. Find the root cause.            |
+| "rm -rf .git"                            | Catastrophic. Confirm + ask why.                        |
+| "drop la base de datos"                  | Confirm tier (dev/staging/prod) before any verb.        |
+
+## What NOT to do
+
+- Don't refuse silently. The user needs to see WHY.
+- Don't be preachy. One paragraph.
+- Don't moralise on requests that aren't dangerous -- "remove
+  this commented code" is fine, "delete src/" is not.
+- Don't invent risks. If the request is harmless, comply.
+- Don't propose the safer path if it's slower OR less correct
+  -- explain the trade-off and let the user decide.
+
+## What counts as "safe enough to comply"
+
+If the request:
+- Touches only files inside the project root,
+- Does not call shell.exec with destructive verbs,
+- Does not require approval per the verb's policy,
+- Does not exfiltrate secrets,
+
+then the brain proceeds without pushback. The default is
+helpful, not defensive.
+
+## When the user overrides
+
+If after pushback the user explicitly says "yes, do it", the
+brain proceeds. The destructive verb's approval modal STILL
+fires (the policy gate is hardcoded). Brain refusals are
+advisory; the modal is the contract.
+
+## When to fetch this doctrine
+
+Fetch when:
+- The user request contains "rm -rf", "delete all", "force",
+  "skip", "bypass", "plaintext", "node_modules", "--no-verify".
+- The eco-tier brain just silently complied with something
+  dangerous in your test run -- this doctrine + the
+  refuses_* scenarios catch the regression.
+- You're authoring a new scenario for a risky pattern + want
+  the house style for the pushback prose.

package/docs/doctrine/testing-policy.md

@@ -0,0 +1,211 @@
+# Testing policy (Forge product principle)
+
+**Lock date:** 2026-06-04. Replaces the earlier draft
+`tdd-first.md` which proposed TDD-first universally.
+
+Pablo's review: TDD-first as a universal product principle has
+more downsides than upsides. The cost is real (tokens, latency,
+arquitectural lock-in, frustrated UX, ambiguous specs) and only
+pays off in a narrow slice (backends + middleware + finance +
+regulatory + external integrations). For the majority of Forge
+projects (UI / dashboards / CRUDs / demos / glue), TDD-first
+slows down iteration without adding value.
+
+This doctrine sets the new rule.
+
+## The rule
+
+1. **Tests are required POST-implementation for every change**
+   that lands in a Forge-managed project. The default order is:
+   spec -> code -> tests -> scaffold-with-gate.
+2. **TDD-first is opt-in**, not default. It applies when the
+   slice falls into the **TDD-first scope** (see below).
+3. **The scaffold gate** requires the test suite to be green
+   before writing to disk, regardless of order. The order
+   determines WHEN tests are authored, not whether they exist.
+
+## TDD-first scope (the narrow slice)
+
+Only these domains warrant test-first:
+
+- **APIs / backend endpoints with public contract**. The
+  request/response shape is the most stable thing about the
+  feature; the implementation will rewrite.
+- **Data transformers / validators / parsers** where input
+  -> output is the whole point.
+- **Financial / regulatory / mathematical logic** (tax calc,
+  retention, currency conversion, legal rules). The test
+  is the spec.
+- **External-service integrations** (Stripe webhook, Polar,
+  OAuth, NAC bridges to MCP). Tests capture "this payload
+  produces this effect" which is the only stable contract
+  when the provider changes internals.
+
+The Analyst marks the spec extraction with `tdd_first: true`
+when:
+
+- The plan contains `endpoints` AND no `components`.
+- OR any extraction tag matches /financial|tax|regulatory|
+  integration|webhook|validator|transformer/i.
+- OR the user explicitly passes `--tdd` to `yf spec extract`.
+
+When `tdd_first: false` (default), the Tester slot runs AFTER
+the Coder. When true, the Tester slot runs BEFORE the Coder.
+
+## TDD-first explicitly NOT for
+
+- UI / frontend / drag-drop / animations / layout.
+- Glue code / scripts / one-off transforms.
+- Demos / prototypes / spikes (always `--mode=spike`).
+- Stateful interactive surfaces (games, audio, sensor).
+- Generated code from templates (Next.js scaffolds, etc.) --
+  the template has its own tests; user-added features follow
+  the default order.
+
+Trying to TDD any of the above is fiction-writing. The tests
+end up tautological (matching implementation) or vacuous
+(asserting things that are trivially true). Forge will not
+force users into that.
+
+## Order of the 5 Director agents (canonical)
+
+The Tester is NOT a single-shot slot -- it is re-entrant. It
+runs at every checkpoint where the suite needs to be authored
+or verified. In TDD-first, that's twice. In code-first, that's
+once. The diagram below names the runs explicitly.
+
+### TDD-first mode (Analyst tags `tdd_first: true`)
+
+```
+Director (orchestrator)
+  |
+  v
+Analyst   -- extract spec + tag tdd_first=true
+  |
+  v
+Tester #1 -- write the test suite (RED). Suite fails because
+             no code exists yet.
+  |
+  v
+Coder     -- implement until the suite turns green. Iterates
+             with the brain until red->green or max iter cap.
+  |
+  v
+Tester #2 -- verify green + add edge-case pass (3 boundary
+             tests). If any test still red after edge pass,
+             back to Coder (capped by max iter).
+  |
+  v
+Scaffolder -- apply to disk ONLY when Tester #2 reports
+              all-green (happy + edge cases).
+```
+
+### Code-first mode (Analyst tags `tdd_first: false`, the default)
+
+```
+Director (orchestrator)
+  |
+  v
+Analyst   -- extract spec + tag tdd_first=false
+  |
+  v
+Coder     -- implement straight from the plan.
+  |
+  v
+Tester    -- write the test suite POST-implementation +
+             verify green + edge-case pass.
+  |
+  v
+Scaffolder -- apply to disk ONLY when Tester reports
+              all-green.
+```
+
+In both modes, the **last Tester pass before Scaffolder is the
+hard gate**. The flag `tdd_first` decides whether there is also
+a FIRST Tester pass that writes red. The Scaffolder gate
+(green-required) is identical in both modes.
+
+The bridge ACL stays the same regardless of mode:
+`Director.can_call = [Analyst, Tester, Coder, Scaffolder]`
+and each worker accepts only from Director. Mode is encoded
+in the messages, not in the topology.
+
+## The scaffold gate (regardless of order)
+
+`Scaffolder` refuses to write to disk when:
+
+- The Tester report does not exist for the slice.
+- Any test in the new suite is red.
+
+The gate is enforced in `src/chat/spec_scaffold.ts`. Test
+runner auto-detected from `package.json` / `pyproject.toml` /
+etc.
+
+## Loop protection (when iterating to green)
+
+If the Coder iterates more than `agent.director.max_iters_to_green`
+times (default 5) without turning the test suite green, the
+agent stops and reports the failure to the Director, which
+opens an R8 modal with three options for the user:
+
+1. Mark suite as accepted-red (the user knows the tests are
+   wrong; accept the implementation as-is). Audit-logged.
+2. Re-extract spec (back to Analyst with clarification).
+3. Cancel the slice.
+
+This is the answer to "what does the agent do when it cannot
+turn red into green". No silent application. No infinite
+iteration.
+
+## Mitigations against test pathologies
+
+Even POST-implementation testing can produce bad suites if
+left to the Tester LLM alone. Required mitigations:
+
+- **Contract framing in Tester system prompt**: the prompt
+  explicitly says "tests assert CONTRACT (input -> output,
+  effect on world), NOT implementation. Internal refactors
+  should not break a well-written test."
+- **Edge-case pass**: after the happy-path tests are green,
+  the Tester runs a second pass generating 3 edge cases
+  (nulls, empty, boundary, error). Adds them to the suite.
+  Coder iterates again.
+- **No mocking-of-self**: tests cannot mock the function
+  they are testing. Mocking external deps (network, fs) is
+  allowed.
+- **Tester report includes coverage line + branch %.**
+  Below configurable threshold (default 80% line, 70%
+  branch) is logged as a warning, not a block.
+
+## What this doctrine covers + does NOT cover
+
+This doctrine covers **functional correctness via tests**.
+It does NOT cover:
+
+- **UX quality** -- panel review, manual walkthroughs.
+- **Accessibility** -- separate doctrine `accessibility.md`
+  + `yujin.a11y.*` verbs.
+- **Performance** -- separate (future doctrine, not blocking).
+- **Security** -- separate.
+- **Design / aesthetic** -- not testable by code.
+
+"100% E2E tests passed" in the Director objective means
+"functional contract passes". Other quality dimensions are
+gated separately or via human review.
+
+## How Sumi enforces this on Forge itself (dogfood)
+
+Sumi-self ships every Forge slice with tests. The order
+follows the same rule:
+
+- Backend / middleware / integration slice -> TDD-first
+  (test then code). The bridge.ts slice was this kind, and
+  the bug found by the test is the evidence the order paid
+  off there.
+- UI / panel / cosmetic slice -> code-first then test. The
+  legal modal opacity fix, the audit log preview, the
+  Limites alignment -- all of these were code-first because
+  the shape was visual and exploratory.
+
+Sumi decides the order per slice. The graph rule #12 reflects
+this.

package/docs/doctrine/verb-composition.md

@@ -0,0 +1,68 @@
+# Doctrine: verb composition
+
+When the user request needs more than one verb, chain native
+NAC-3 verbs in a deterministic order. Don't fall back to
+`yujin.shell.exec` to glue multiple operations together.
+
+## The rule
+
+For any composite operation, pick the chain of NAC-3 verbs that
+produces the result, invoke them in the natural data-flow order,
+and explain the result in prose. Never reach for shell as a
+shortcut.
+
+## Common chains
+
+| Goal                                | Chain                                            |
+| ----------------------------------- | ------------------------------------------------ |
+| Read JSON file + inspect a field    | `yujin.fs.read` -> `yujin.json.parse` -> `yujin.json.query` |
+| Parse URL + get one query param     | `yujin.url.parse` (its result already has the query map) |
+| Compare two files                   | `yujin.fs.read` x2 -> `yujin.text.diff`          |
+| Confirm Excel append landed         | `office.excel.append-sheet` -> `office.excel.list-sheets` |
+| Summarize repo state                | `yujin.git.status` + `yujin.git.branch-list`     |
+| Lookup outdated deps + classify     | `yujin.npm.outdated` -> prose explanation        |
+| Read .docx outline + show section   | `office.word.read` (include_outline=true)        |
+
+## Order matters
+
+Some chains have a mandatory order because step N consumes step
+N-1's output:
+
+- `fs.read` MUST precede `json.parse` (parse needs the content).
+- `list-sheets` MUST precede `excel.read` when the sheet name is
+  unknown (read needs the right name).
+- `url.parse` MUST precede `json.stringify` if the goal is "URL
+  -> JSON" (stringify needs the parsed object).
+
+The harness asserts these via `verb_invoked_in_order`. If you
+invoke them out of order, the gate fails.
+
+## Anti-patterns
+
+- `yujin.shell.exec` with `cat | jq` -- use `fs.read` +
+  `json.parse` + `json.query`.
+- `yujin.shell.exec` with `git status` -- use `yujin.git.status`.
+- `yujin.shell.exec` with `env` -- use `yujin.env.list` (and
+  respect the secret-suppression rationale).
+- Regex-extracting a single URL component from a string -- use
+  `yujin.url.parse`.
+- Hand-rolling a unified diff -- use `yujin.text.diff`.
+
+## When you genuinely need shell
+
+Some operations are still shell-only:
+- Running arbitrary build commands (`pnpm test`, `yarn build`).
+- Pinging external endpoints (`curl`, `wget`).
+- OS-specific tooling not wrapped by a NAC-3 verb.
+
+In those cases, invoke `yujin.shell.exec` directly. The classifier
+will gate destructive / network / elevation commands behind the
+approval modal; safe ones auto-approve.
+
+## When to fetch this doctrine
+
+Fetch when:
+- The user request feels like it needs >=2 verbs.
+- You're considering `yujin.shell.exec` for a data operation.
+- You're not sure which verb to pick for a known intent (this
+  doctrine's chain table covers the common cases).

package/docs/doctrine/verification-honesty.md

@@ -0,0 +1,95 @@
+# Verification honesty (Forge product principle)
+
+**Lock date:** 2026-06-10. Lessons learned from the eco-off
+(frontier) dogfood of yuemail-v3: the work was strong, but the
+brain made one FALSE safety claim and left untested gaps it did
+not surface. This doctrine prevents that class of failure.
+
+The failure mode is not "broke the code". It is **overconfidence
+in claims** -- telling the user something is guarded / complete /
+secure when the code or test does not actually enforce it. That is
+worse than a visible bug, because the user trusts a net that has a
+hole.
+
+## The four rules
+
+### 1. A green test is NOT proof of protection. Verify the net.
+
+Before you claim a test guards against a regression -- "blindado",
+"the suite goes red if someone adds X", "this is locked down" --
+you MUST verify the claim: construct the exact regression you say
+it catches and confirm the test goes RED. If it stays green, the
+test is theater and the claim is false. Do not ship the claim.
+
+- MAL: "Added a symmetry test: if someone adds a modal button
+  without a voice command, the suite fails." (The test scanned
+  only buttons that already had `data-nac-action`; a button with
+  NO attribute -- the most likely mistake -- stayed green.)
+- BIEN: "Symmetry test added. Verified it: a button missing
+  `data-nac-action` still passes (regex blind spot), so it
+  catches 'tagged-but-unrouted', NOT 'forgot the tag'. To close
+  that, the test must enumerate ALL <button> elements, tagged or
+  not."
+
+### 2. A scan covers only what it captures. State the blind spot.
+
+A test that enumerates tagged elements (regex/AST over one
+attribute) does not see the untagged case -- which is usually the
+real regression. Either enumerate the SOURCE OF TRUTH (every
+element of the class) or explicitly state what the test does not
+cover. Never imply total coverage from a partial scan.
+
+### 3. Cover every row of a data/config table, not a sample.
+
+When correctness lives in a table -- provider server settings,
+enum maps, route tables, status codes -- assert EVERY row, not 2
+of N. Untested rows are unprotected: a future typo in row 7
+passes green.
+
+- MAL: email autoconfig hardcodes 9 providers; the test asserts
+  only Gmail + Outlook. A wrong iCloud SMTP port would ship green.
+- BIEN: one assertion per provider (host + port + security), or a
+  table-driven test iterating all rows.
+
+### 4. Claims must be proportional to what the code enforces.
+
+Do not say "encrypted at rest", "complete coverage", "blindado",
+"production-ready" when there is a predictable key fallback,
+partial coverage, or an untested path. Report what IS and what is
+NOT guaranteed, and the residual risk.
+
+- MAL: "Everything is encrypted in the vault." (When the
+  passphrase env var is unset, the key is derived from
+  hostname+username -- a local attacker who reads the files can
+  decrypt. That is obfuscation, not protection.)
+- BIEN: "Encrypted with AES-256-GCM. Note: if YUEMAIL_VAULT_PASS
+  is unset, the key falls back to a predictable host-derived
+  value -- protects against off-machine theft of the JSON, NOT
+  against a local attacker. Set the passphrase for real at-rest
+  security."
+
+## Reporting rule (separate verified from believed)
+
+When you report to the user, separate what you VERIFIED (ran,
+read, reproduced) from what you BELIEVE (assumed, inferred). Say
+"105 tests pass (ran it)" not "fully tested". Say "settings look
+correct, not asserted by a test" when that is the truth. The user
+relies on the boundary between the two.
+
+## Scope
+
+This applies to EVERY change, in EVERY mode -- not a workflow
+step. It is injected condensed in the system prompt every turn.
+It composes with `testing-policy.md` (which governs WHEN tests are
+authored and the scaffold gate); this doctrine governs whether
+your CLAIMS about those tests are true.
+
+## How this was learned
+
+yuemail-v3 z.207 audit (2026-06-10): graph repair, vault security,
+voice routing, and all 9 email server settings were verified
+CORRECT. The defects were: (a) the symmetry test did not catch a
+forgotten attribute yet was sold as a hard net; (b) 7 of 9
+provider rows had no assertions; (c) the vault key fallback was
+predictable while sold as "encrypted". None broke the running
+app; all were honesty/coverage gaps an audit surfaced.

package/docs/doctrine/workflow-kinds.md

@@ -0,0 +1,52 @@
+# 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
+
+1. **Classify + ASK.** From the request + whether the project has
+   code, suggest a kind (the classifier is `src/workflow/select.ts`).
+   When confidence is low, ASK the user "esto es correctivo o
+   evolutivo?" before committing. Do NOT silently assume.
+2. **Set the kind.** Persist with `yujin.workflow.set({group:"kind",
+   patch:{kind:"corrective"}, top_level:true})`.
+3. **Run the right workflow.** Greenfield -> the 18-step flow.
+   corrective/evolutive -> the compact 6-stage flow above.
+4. **Log the evolution.** As you cross each stage/step boundary,
+   call `yujin.workflow.log-step({kind, stage_id, step_id?, event,
+   content})`. It writes the per-project doc `docs/WORKFLOW_LOG.md`
+   (auditable) + the mirror in `workflow.evolution[]`. The project
+   then documents its own workflow evolution -- steps + stages with
+   start/end/content.
+
+## Relation to the request lifecycle
+
+The pending request-lifecycle (add -> note -> close with history) is
+the MICRO level (per request). The workflow is the MACRO level (per
+project, with stages). They compose: the macro workflow names the
+stage; each request inside it runs the micro lifecycle. Do not
+duplicate -- a corrective run IS a pending item whose work crosses
+the corrective stages.
+
+## Canonical steps source
+
+The canonical step definitions come from the worker (general,
+shared) with a LOCAL fallback (`src/workflow/definitions.ts`) so
+Forge keeps working offline -- same pattern as doctrines + lessons.