@nac3/forge-cli 0.2.0-alpha.59z.123 → 0.2.0-alpha.59z.158

package/docs/doctrine/default-design-system.md

@@ -0,0 +1,120 @@
+# Default design system -- Yujin DS first
+
+Fetch when the user discusses UI / component design / look-and-
+feel (signals: "componente", "modal", "sidebar", "card", "view",
+"icon", "color", "fuente", "diseno", "interfaz", "UI", "form",
+"button", "table", "kanban", "tabs"). Auto-injected on every
+turn whose intent matches the UI heuristic.
+
+## Rule (single source of truth)
+
+The default front-end design system for any Forge-generated
+project is **Yujin Design System** (`yujin-design-system/`). The
+package ships with 258 DTCG-compliant tokens, 30 NAC3-attributed
+component templates, 170 sumi-e icons + a kanji wordmark
+catalog, and font references (Google Fonts CDN, no bundled
+binaries).
+
+When the user asks for a UI element, agents MUST:
+
+1. Consult `yujin.design.list-templates` to see which Yujin
+   components cover the kind of element being requested.
+2. Use `yujin.design.get-template({slug})` to retrieve the HTML
+   + CSS + `nac3_attrs` + variants for the picked component.
+3. Splice the template into the project; do NOT hand-roll an
+   equivalent layout from scratch.
+4. Iconography: only pick from `yujin.design.list-sumie` (170
+   canonical icons). Use `yujin.design.get-icon({slug})` to
+   inline the SVG. Do NOT generate or import third-party icons
+   (no Material, no Font Awesome) unless the user explicitly
+   asks (override flow below).
+5. Colors / typography / spacing: only via tokens from
+   `yujin.design.tokens()`. Do NOT hardcode `#3A4DBC` or
+   `font-family: Inter`; use `var(--color-accent)` and
+   `var(--font-family-sans)`.
+
+## Override flow
+
+The user CAN override the default ("usa shadcn", "use Material",
+"this app needs Tailwind only", "I want my own brand colors"):
+
+- Agent invokes `yujin.design.override({system_id, reason})`.
+- This is `policy: 'approval_required'` so R8 opens a modal.
+- The user confirms (or rejects); the choice persists in
+  `tenant_config.design_override`.
+- Subsequent turns honor the override + the doctrine becomes a
+  soft suggestion ("Yujin DS is the Forge default, but this
+  tenant has overridden to <system>").
+
+## Why this is the default
+
+- Coherent visual language across every Forge-generated product
+  -- the user does not need to re-learn the look-and-feel per
+  product.
+- 30 components are enough to compose every standard SaaS UX
+  (CRM, admin panel, marketing site, e-commerce, dashboard,
+  task tracker, settings).
+- NAC3 attributes pre-applied -- every Yujin component is
+  voice-controllable + accessibility-ready out of the box.
+- 170 sumi-e icons cover virtually every business concept
+  (finance, sales, support, manufacturing, quality, HR, mobile,
+  AI, comms, document, geo, weather, animal). One coherent
+  illustration style.
+
+## Files in the package
+
+```
+yujin-design-system/
+  manifest.json                 catalog + version + license
+  tokens/
+    yujin-tokens.json           258 DTCG W3C tokens
+    yujin-tokens.css            generated CSS (same source-of-truth)
+  components/
+    _index.json                 list of 30 components by category
+    button.yujin.json           one file per component
+    card.yujin.json
+    ...                         (30 total)
+  icons/
+    sumie/
+      manifest.json             170 icons with tags
+      branch-sakura.svg         one SVG file per icon
+      ...                       (170 total)
+  fonts/
+    README.md                   reference-only policy (Google Fonts CDN)
+```
+
+## Six NAC3 verbs
+
+| Verb                            | Returns                                            | Policy             |
+|---------------------------------|----------------------------------------------------|--------------------|
+| `yujin.design.list-templates`   | `[{slug, category, description, variants}]`       | safe               |
+| `yujin.design.get-template`     | full ComponentTemplate (html, css, nac3, props)   | safe               |
+| `yujin.design.list-sumie`       | `[{slug, tags, file}]` (filtered by tag if given) | safe               |
+| `yujin.design.get-icon`         | inline SVG string                                  | safe               |
+| `yujin.design.tokens`           | full DTCG token tree                               | safe               |
+| `yujin.design.override`         | persists tenant_config.design_override            | approval-required  |
+
+## What this doctrine does NOT cover
+
+- Framework choice within TypeScript (Vue vs React vs Svelte).
+  See `docs/doctrine/language-sovereignty.md` -- the user
+  decides per slot, and the doctrine table records the choice.
+- Build tooling (Vite vs Webpack vs esbuild). Out of scope.
+- Theme switching per tenant. The override flow above persists
+  one choice per tenant; multi-theme support is a separate
+  feature.
+
+## What the WORKERS (Analyst, Coder, Director) do with this
+
+- **Analyst**: when extracting a spec that mentions UI elements
+  (forms, dashboards, modals), tag each one with the matching
+  Yujin component slug in `plan.components[]`. The Coder then
+  knows which template to pull.
+- **Coder**: before writing ANY UI file, invoke
+  `yujin.design.list-templates` + `yujin.design.get-template`
+  for the components in the plan. Splice the templates. Apply
+  variants from the spec. Do NOT hand-write `.css` from
+  scratch.
+- **Director**: when the user explicitly requests an override
+  ("use shadcn"), invokes `yujin.design.override` instead of
+  silently accepting. The R8 modal confirms.

package/docs/doctrine/language-sovereignty.md

@@ -0,0 +1,143 @@
+# Language sovereignty -- the user picks, the Director suggests
+
+Fetch when the user discusses programming language choice in
+architecture / RFP / Arch / Design phases (workflow phases II
+and III), OR when an Analyst extracts a spec that mentions a
+language explicitly (signals: "in node", "with django", "react
+native", "pure rust", "java backend", "swift app").
+
+## Rule (single source of truth)
+
+The user picks the programming language for each component. The
+Director SUGGESTS during architecture (phase III specs / RFP)
+but NEVER imposes. If the user insists on a language different
+from the one the Director suggested, the Director performs a
+SWITCH and persists the choice in `workflow.language_choices`
+via `yujin.workflow.set`.
+
+The ONLY exception is when the language the user requested is
+not conducive to the component being developed (technical
+incompatibility documentable from the table below). In that
+case the Director replies with the exact row from this doctrine
++ the valid alternatives + waits for the next user decision. No
+"I deny because I dislike", only "I deny because <component-kind>
+cannot run on <language> because <technical reason>".
+
+## Suitability table
+
+The table is the single source of truth. The Director MUST read
+from it and MUST NOT add opinions on top.
+
+| Component kind          | Conducive languages                                            | NOT conducive (with reason)                                                                       |
+|-------------------------|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
+| spa-web-frontend        | ts, js, wasm-target (rust, go, c#), htmx-fragments              | python, java, php, ruby (server-side runtimes, not a browser runtime)                              |
+| mobile-native           | swift (ios), kotlin (android), dart (flutter), ts+rn (expo)     | python, php, c# (no fluid native mobile runtime); html-only (not native)                          |
+| mobile-cross-platform   | dart (flutter), ts+rn (expo), kotlin-multiplatform              | jvm-only languages (not a mobile target), php, perl                                                |
+| backend-api             | ts, js, python, go, rust, java, kotlin, c#, php, ruby, elixir   | bash, asm (do not scale to productive HTTP servers); assembler (no http stack)                    |
+| backend-realtime        | go, rust, elixir, ts (node), kotlin, c# (signalr)               | python (gil bottleneck for sustained ws), php (request-response model)                            |
+| kernel-driver           | c, rust, asm                                                    | ts, python, java, c# (managed runtimes do not touch metal)                                        |
+| embedded-firmware       | c, rust, c++, micropython (mid-range), zig                      | java, ts, php (heavyweight runtimes for typical mcus)                                              |
+| data-pipeline           | python, scala, java, go, sql, kotlin                            | js (poor batch ecosystem), php (no parallel data tooling)                                          |
+| ml-training             | python, julia, r, c++ (kernels)                                 | ts, php, ruby (no mature ml ecosystem comparable)                                                  |
+| ml-inference            | python, ts, c++, rust, go (onnx)                                | php, perl (no inference runtime)                                                                   |
+| db-stored-proc          | sql, pl/pgsql, t-sql, pl/sql (oracle)                           | any general-purpose language (not the db engine model)                                            |
+| db-migration            | sql + migration runner (any: rails, alembic, prisma, flyway)   | --                                                                                                |
+| cli-tool                | go, rust, ts (node), python, c (oneshot)                        | -- (almost any general-purpose lang works)                                                         |
+| static-analysis-plugin  | language of the target compiler                                 | any unrelated language (no compiler integration point)                                            |
+| infra-as-code           | terraform/hcl, pulumi (ts/python/go), cloudformation/yaml, cdk  | bash one-offs (do not represent desired state)                                                    |
+| iot-edge                | rust, c, go, python (rpi-class), elixir (nerves)                | jvm-only (mostly too heavy), php                                                                  |
+| build-system            | go, rust, ts (node), make, bash                                 | -- (almost any works; nuance is in ergonomics, not correctness)                                   |
+| docs-site               | markdown + static site gen (any), mdx (react)                   | dynamic backends (overkill; not conducive to content-as-code)                                     |
+
+## Algorithm (Director executes this)
+
+1. User input: "quiero X en LANG".
+2. Director: `yujin.doctrine.discover({slugs:["language-sovereignty"]})`.
+3. Director: lookup the row for `X` (component-kind). If
+   ambiguous, ASK the user one clarifying question (which kind
+   of component is X?) before proceeding. Do NOT guess.
+4. If `LANG` is in `row.conducive`:
+   - switch: set `workflow.language_choices[X] = { lang: LANG,
+     decided_at: NOW, decided_by: "user" }` via
+     `yujin.workflow.set`.
+   - Reply briefly: "Listo, X en LANG. Sigo con el plan."
+   - Do NOT discuss the choice further unless the user asks.
+5. If `LANG` is NOT in `row.conducive`:
+   - Reply with the exact row from this doctrine:
+     "LANG no es conducente para X porque <row.NOT_conducive_reason>.
+      Las opciones validas son: <row.conducive>. Cual preferis?"
+   - Do NOT switch. Wait for the next user decision.
+6. If the user counter-argues with NEW technical information
+   ("hay un transpiler de LANG a JS / WASM target / etc"):
+   - Director re-evaluates. If the new info is verifiable +
+     consistent with the table semantics (e.g. WASM target for
+     the kind), update the conducive set in memory for THIS
+     turn + switch.
+   - If the info is opinable / not verifiable, hold the negative
+     + explain the gap (mismatched runtime model, no compiler
+     integration, etc).
+
+## Defaults when the user has NOT expressed preference
+
+When the user has not yet declared a language for a component
+slot, the Director may suggest a default. Defaults are NOT
+prescriptions; they exist so the conversation can move forward
+without a 12-question survey.
+
+| Slot                | Default suggestion           |
+|---------------------|------------------------------|
+| frontend            | ts (react / typescript)      |
+| mobile              | ts (react native + expo)     |
+| backend             | ts (node) for crud-heavy; go for perf-sensitive; python for ml-heavy |
+| data-pipeline       | python                       |
+| infra               | terraform + hcl              |
+| db                  | postgres + sql migrations    |
+| ml                  | python                       |
+
+The Director surfaces the default as a SUGGESTION ("propongo TS
+para frontend y Python para el pipeline; te sirve?") and
+proceeds if the user accepts or stays silent on it (silence is
+acceptance of the default). The persisted `decided_by` field
+records `"director_suggested"` so a future audit can distinguish
+explicit choices from accepted defaults.
+
+## Where the decision lives
+
+```
+yujin.forge.json -> workflow.language_choices: {
+  frontend:      { lang: "ts",     decided_at: "...", decided_by: "user" },
+  backend:       { lang: "go",     decided_at: "...", decided_by: "user" },
+  mobile:        { lang: "dart",   decided_at: "...", decided_by: "director_suggested" },
+  data_pipeline: { lang: "python", decided_at: "...", decided_by: "user" },
+  infra:         { lang: "tf+hcl", decided_at: "...", decided_by: "director_suggested" }
+}
+```
+
+Read via `yujin.workflow.state`. Write via `yujin.workflow.set
+{path: "language_choices.<slot>", value: {...}}`.
+
+## What this doctrine does NOT cover
+
+- Frameworks within a language (vue vs react vs svelte for ts
+  frontend). That is a separate user decision the Director
+  surfaces but does not constrain via this doctrine.
+- Library choices (express vs fastify vs hono for ts backend).
+  Same: user decides.
+- Build tooling (vite vs webpack vs esbuild). Same.
+
+## What the WORKERS (Analyst, Coder, Tester, Scaffolder) read from this doctrine
+
+- **Analyst**: when extracting a spec, capture explicit language
+  signals into `plan.language_signals[]`. The Director processes
+  them via the algorithm above.
+- **Coder**: read `workflow.language_choices` before proposing
+  files. Match the chosen language; do NOT default to TS if the
+  table chose Go.
+- **Tester**: detect the test framework FROM the chosen language
+  + project manifest (`package.json` -> Vitest/Jest, `pyproject.toml`
+  -> pytest, `go.mod` -> go test, `Cargo.toml` -> cargo test,
+  `composer.json` -> PHPUnit). Do NOT prompt the user for the
+  framework when the manifest already says.
+- **Scaffolder**: respect file extensions + import statements of
+  the chosen language stack. Do not write `.ts` files into a Go
+  module.

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.