@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/docs/doctrine/office-tools.md

@@ -0,0 +1,122 @@
+# office.* verbs (F106) -- when + how
+
+The `office.*` namespace gives the brain four cross-platform native
+verbs for Excel + Word IO. They are NOT visible in the lazy manifest
+stub (slice 1) -- the brain fetches THIS doctrine via
+`yujin.doctrine.discover` when the user mentions Excel / Word / .xlsx
+/ .docx / spreadsheet / hoja / planilla / Word document.
+
+## Catalog
+
+| Verb | Use when | Policy |
+|---|---|---|
+| `office.excel.read`  | User wants to peek into or compute over an .xlsx / .xls / .csv | project-root-gated |
+| `office.excel.write` | User wants a fresh workbook (new file). Refuses to overwrite by default | approval-required |
+| `office.word.read`   | User wants text + heading outline from a .docx                  | project-root-gated |
+| `office.word.write`  | User wants a fresh .docx (new file). Refuses to overwrite by default | approval-required |
+
+## Args -- quick reference
+
+```
+office.excel.read   {path, sheet?, range?, header_row?}
+office.excel.write  {path, sheet?, rows[<obj|arr>], overwrite?}
+office.word.read    {path, include_outline?}
+office.word.write   {path, sections:[{kind:'heading'|'paragraph', level?, text}], overwrite?}
+```
+
+## Picking the right verb
+
+The brain MUST NOT use `yujin.fs.read-file` for .xlsx / .xls / .docx
+-- they are binary, the file content will look like noise + waste
+tokens. Always pick `office.excel.read` or `office.word.read`.
+
+The brain MUST NOT shell out to `python -c "import openpyxl..."` or
+similar. The verbs are cross-platform; no shell needed.
+
+## Excel patterns
+
+- **Read with header row (default):**
+  `office.excel.read({path:'data/x.xlsx'})` returns
+  `rows: [{col_a: 1, col_b: 2}, ...]`.
+- **Read raw cells (no header):**
+  `office.excel.read({path, header_row: false})` returns
+  `rows: [['col_a','col_b'], [1,2], ...]`.
+- **Specific sheet + range:**
+  `office.excel.read({path, sheet: 'Q1', range: 'A1:D50'})`.
+- **Write from objects:**
+  `office.excel.write({path:'out.xlsx', rows:[{name:'Ana', age:30}]})`.
+- **Write raw cells:**
+  `office.excel.write({path:'out.xlsx', rows:[['a','b'],[1,2]]})`.
+- **Overwrite existing file:**
+  pass `overwrite: true`. Refuses by default to avoid accidental
+  destruction.
+- **Output format:**
+  driven by extension. `.xlsx` -> xlsx, `.csv` -> csv, `.xls` -> biff8.
+
+## Word patterns
+
+- **Read text:**
+  `office.word.read({path:'docs/notes.docx'})` returns `text +
+  outline` (best-effort heading list).
+- **Outline-only mode:**
+  the outline is best-effort -- mammoth may miss some heading
+  styles. If empty, do not assume the doc has no headings.
+- **Write a structured doc:**
+  ```
+  office.word.write({
+    path: 'docs/notes.docx',
+    sections: [
+      { kind: 'heading',   level: 1, text: 'Title' },
+      { kind: 'paragraph', text: 'Intro paragraph.' },
+      { kind: 'heading',   level: 2, text: 'Section A' },
+      { kind: 'paragraph', text: 'Body.' },
+    ]
+  })
+  ```
+- **Only .docx output.** The verb refuses `.doc` (legacy binary
+  format -- not in the cross-platform path).
+- **Refuses overwrite by default.** Use `overwrite: true` for
+  destructive writes.
+
+## Hard caps
+
+- Read: 16 MB file size.
+- Excel write: 1,000,000 rows; 1024 fields per row.
+- Word write: 50,000 sections; 100,000 chars per section text.
+
+## Don't
+
+- Don't read .xlsx via `yujin.fs.read-file` (binary garbage).
+- Don't shell out to python/openpyxl/docx (cross-platform path
+  already covers it).
+- Don't claim "written" without invoking `office.*.write` first.
+- Don't overwrite without confirming or passing `overwrite: true`.
+
+## Do
+
+- Use `office.excel.read` -> pizarron tab for tabular data >10 rows.
+  Chat-pasting Excel rows is noisy.
+- Use `office.word.read` -> chat summary + pizarron full text if
+  the doc is long.
+- Pair `office.*.write` with R8 modal (policy=approval-required;
+  user confirms before disk write).
+
+## Opening vs reading (desktop.open vs office.*.read)
+
+There are TWO different intents -- pick by what the user wants:
+
+- **OPEN / SHOW it to the user** ("abri la planilla", "open this Excel",
+  "show me the doc") -> `desktop.open({target})`. It launches the file
+  in its native app (.xlsx -> Excel, .docx -> Word, .pdf -> the viewer)
+  or, for a Google Sheets/Docs URL or a `.gsheet`/`.gdoc` shortcut, in
+  the browser. This is the right move when the human wants to SEE it.
+
+- **READ / COMPUTE over the data** ("what's the total", "extract the
+  rows", "summarize the doc") -> `office.excel.read` / `office.word.read`
+  / `office.pdf.read`. These return structured data for YOU to reason
+  over.
+
+NEVER open a binary office file as a pizarron editor tab
+(`forge_open_file_for_editor` / fs.read-file): the bytes render as
+noise and FREEZE the panel (PND-102). The open-file verb now refuses
+office/binary extensions and points here.

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,84 @@
+# 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.
+
+## Long-running commands -> yujin.task.run (MANDATORY)
+
+`yujin.shell.exec` runs SYNCHRONOUSLY: it blocks the turn and the
+child process is killed when the turn ends. So a command that does NOT
+terminate on its own -- a dev server, a watcher, `tail -f`, a tunnel
+(`npm/pnpm run dev|start|serve|watch`, `expo start`, `vite`,
+`next dev`, `nodemon`, `wrangler dev`, `docker compose up`,
+`cloudflared tunnel`, ...) -- MUST be launched with `yujin.task.run`,
+which runs it detached so it SURVIVES the turn. Follow it with
+`yujin.task.status` / `yujin.task.list`; the user stops or deletes it
+from the Tareas tab in the pizarron.
+
+shell.exec ENFORCES this: it refuses such commands and points you to
+`yujin.task.run` (error `long_running_must_use_task`). Only pass
+`allow_long_running:true` in the rare case you truly need it in-turn.
+
+## 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).