create-byan-agent 2.25.0 → 2.27.0

package/install/templates/.claude/rules/benchmark.md

@@ -0,0 +1,251 @@
+<!-- Generated by byan-sync-rules from _byan/_config/autobench.yaml. Do not hand-edit. -->
+
+# BYAN Auto-Benchmark — Proactive Decision Doctrine
+
+> The user is about to be asked to choose. Before that question reaches them,
+> benchmark the fork: name the options, score them on the criteria that
+> actually diverge, and lead with a recommendation. A choice presented without
+> a benchmark hands the user the work the agent was supposed to do.
+
+This doctrine is PROACTIVE: the agent self-applies it before it writes the
+choice. The reactive Stop hook (`autobench-stop-guard.js`) is the net, not the
+mechanism — see the honest ceiling note at the end.
+
+## The marker protocol (emit this verbatim)
+
+Whenever a turn presents the compact reco table, emit this single-line HTML
+comment IMMEDIATELY BEFORE the table (so it survives even if the table is
+truncated):
+
+```
+<!-- BYAN-BENCH:done g1=<#options> g2=<#divergent-criteria> scope=<internal|external> conf=<assertive|lean> -->
+```
+
+- `g1` must be >= 2 (the option count) and `g2` must be >= 1 (the count of
+  criteria on which the options diverge), or the marker is invalid.
+- For the degenerate / collapsed case — an obvious default, a `never-list`
+  prompt, an already-coherent fork — emit the SKIP marker instead. This is a
+  POSITIVE signal that the fork was considered and deliberately not tabled:
+
+```
+<!-- BYAN-BENCH:skip reason=<obvious-default|never-listed|escape-hatch|already-coherent> -->
+```
+
+The Stop hook treats either marker as satisfied. An unmarked turn that presents
+choice-language (and is not a confirm, not destructive, not escape-hatched) is
+blocked once and forces a single regen.
+
+---
+
+## Brick 1 — TRIGGER: when a turn deserves a benchmark
+
+### The 2-gate rule
+
+A benchmark fires only when BOTH gates hold:
+
+- **G1 — at least 2 non-trivial, non-substitutable options.** Two phrasings of
+  the same thing are ONE option. Two libraries that genuinely differ are TWO.
+- **G2 — divergence on at least 1 weighted criterion.** If every criterion
+  ranks the options identically, there is no real fork. Collapse it.
+
+### The `never-list` (do not benchmark these)
+
+- yes/no and y/n confirmations (`proceed?`, `continue?`, `ok?`, `on continue?`)
+- destructive prompts (`delete`, `drop`, `rm -rf`, `overwrite`, `force push`, `reset --hard`)
+- single trivial acknowledgements (`ok`, `done`, `noted`)
+- a fork already coherent with the locked stack (see anti-redundancy)
+
+A confirm or a destructive prompt is not a fork. Confirm it plainly and emit
+`BYAN-BENCH:skip reason=never-listed` (or `escape-hatch`).
+
+### Internal vs external routing (decides links BEFORE depth decides words)
+
+- **Internal** — the fork stays within the existing repo / stack (which existing
+  module, which local pattern). No external links here. Coherence with the
+  current stack is the dominant criterion. Decide from model-knowledge of the
+  repo.
+- **External** — the fork introduces a new dependency, vendor, or standard.
+  Sourcing is allowed: an evidence level per option, and a URL only if WebFetch
+  opened it this turn.
+
+### Depth dial (stakes x reversibility, applied AFTER routing)
+
+- **Low-stakes, reversible** — one line. `lean X over Y (Y costs an extra dep
+  for no gain here).` No table.
+- **High-stakes, hard-to-reverse** — full compact table + an explicit dissenting
+  view (the strongest case for the option you did NOT pick).
+
+### Obvious-default escape
+
+When one option is the obvious, coherent default and the alternatives are
+strictly worse or `never-listed`, do not table it. Emit
+`BYAN-BENCH:skip reason=obvious-default` so the consideration stays auditable,
+then proceed with the default.
+
+### Choice-language auto-fire
+
+These keywords in the user's text auto-arm the benchmark posture: `should I`,
+`veux-tu que je`, `do you want me to`, `préfères-tu`, `which one`,
+`which approach`, `A or B`, `option 1 or option 2`, `vs`, `ou bien`,
+`soit ... soit`, `pros and cons`, `trade-off`, `trade-offs`.
+
+### Decision tree — verbatim few-shot examples (FIRE vs SKIP)
+
+| # | Situation | Verdict | Why |
+|---|-----------|---------|-----|
+| EX1 | "should I use Redis or Postgres for this session cache?" | **FIRE** | G1 (two non-substitutable stores), G2 (latency / ops-cost / durability diverge). External -> sourcing allowed. |
+| EX2 | "rename the variable foo to userCount, ok?" | **SKIP** | `never-list`: y/n confirm on a trivial reversible edit. `skip reason=escape-hatch`, just do it. |
+| EX3 | "Jest or Vitest for this repo already on Jest everywhere?" | **SKIP** | Obvious-default: stack is on Jest; adding Vitest breaks coherence for no gain. `skip reason=obvious-default`. (No runner yet -> would FIRE.) |
+| EX4 | "auth: JWT-in-cookie vs JWT-in-localStorage vs server sessions" | **FIRE** | G1 (three options), G2 (XSS / CSRF / scalability diverge). Security -> floor L2. High-stakes -> full table + dissent. |
+| EX5 | "delete the legacy migrations folder, proceed?" | **SKIP** | `never-list`: destructive. Do not benchmark a delete. `skip reason=escape-hatch`, confirm plainly. |
+| EX6 | two ways to name a private helper (parseRow vs rowParse) | **SKIP** | G1 fails: substitutable phrasings, no criterion diverges. `skip reason=already-coherent`, pick one. |
+| EX7 | "pick a charting lib for the new dashboard" (repo has none) | **FIRE** | G1 (Chart.js / Recharts / D3), G2 (bundle / API / customization diverge). External -> links only if WebFetch opened them. |
+| EX8 | "debounce of 200ms or 300ms on the search box?" | **SKIP** | Low-stakes, reversible, G2 weak. Collapse to one line ('lean 250ms, tune later'), `skip reason=obvious-default`. |
+| EX9 | "Turborepo vs Nx vs polyrepo for the platform" | **FIRE** | G1 (three structural options), G2 (caching / learning-curve / blast-radius diverge). High-stakes -> full table + dissent. |
+| EX10 | "commit this, on continue ?" | **SKIP** | `never-list`: proceed/continue confirm. Not a fork. `skip reason=escape-hatch`. |
+
+Four FIRE, six SKIP (ten total) — each FIRE pairs with a near-miss SKIP so the
+boundary between "real fork" and "not a fork" is shown, not just asserted.
+
+---
+
+## Brick 2 — SCALER / SOURCING: evidence and confidence
+
+### Routing before depth
+
+Decide internal-vs-external FIRST: it sets whether links are even allowed. Only
+THEN does stakes-x-reversibility set how many words. A verbose table must not
+smuggle in links for an internal fork.
+
+### The 5-level evidence rubric (the Niv column)
+
+| Niv | Score | Sources |
+|-----|-------|---------|
+| L1 | 95% | RFC, W3C, ECMAScript, POSIX, an official spec. |
+| L2 | 80% | A reproducible benchmark, a CVE reference, official product docs. |
+| L3 | 65% | A peer-reviewed article or a recognized technical book. |
+| L4 | 50% | Community consensus (StackOverflow > 1000 votes). |
+| L5 | 20% | Opinion or personal experience. Presented as such, not as fact. |
+
+### Strict-domain floors
+
+| Domain | Floor | Below the floor |
+|--------|-------|-----------------|
+| security | L2 | BLOCKED — CVE or reproducible benchmark required |
+| performance | L2 | BLOCKED — profiler output or reproducible benchmark required |
+| compliance | L1 | BLOCKED — regulatory text required |
+
+A cell below its floor is BLOCKED, not guessed.
+
+### The link rule
+
+A URL appears in the table only if WebFetch opened it this turn. Otherwise cite
+from model-knowledge and tag the claim `[UNVERIFIED]`. Do not fabricate a URL.
+Do not reconstruct a URL from memory and present it as opened.
+
+### Confidence changes the VERB
+
+- **assertive** — evidence at or above the floor for the domain. Phrase the reco
+  as "recommend X" / "go with X".
+- **lean** — evidence below the floor, or model-knowledge only on a strict
+  domain. Phrase the reco as "lean X (low-confidence, verify before committing)".
+
+The verb carries the confidence, not a hidden footnote. This maps to the
+`conf=<assertive|lean>` field in the done-marker.
+
+---
+
+## Brick 3 — FORMAT + ANTI-BLOAT: the output shape
+
+### Default format
+
+One compact table: a row per option, up to 4 criteria columns, a `Niv`
+(evidence level) column, and ONE best-first recommendation line under it.
+
+```
+<!-- BYAN-BENCH:done g1=3 g2=3 scope=external conf=assertive -->
+
+| Option   | Latency | Ops cost | Durability | Niv |
+|----------|---------|----------|------------|-----|
+| Redis    | best    | medium   | weak       | L2  |
+| Postgres | good    | low      | strong     | L1  |
+| In-mem   | best    | none     | none       | L5  |
+
+Recommend Postgres: durability dominates for session data and it is already in
+the stack; Redis only wins if sub-ms latency becomes the binding constraint.
+```
+
+### Hard caps
+
+- options: <= 4
+- criteria: <= 4
+- links: <= 3
+- screens: 1 (the whole benchmark fits in one screen)
+
+### Collapse the degenerate case
+
+If only one option survives the gates, do not render a 1-row table. Collapse to
+one line and emit the skip marker. A table of one is theatre.
+
+### Expanded form — opt-in, named trigger
+
+Only when the user types `[bench:expand]` does the agent render the expanded
+form (more criteria, per-cell sourcing, the full dissent). The default stays
+compact.
+
+### Anti-bloat guards
+
+- **Latency guard** — default to model-knowledge + `[UNVERIFIED]` tags.
+  Auto-WebFetch only for a strict domain (security / performance / compliance)
+  or a volatile fact (current version, current price, current status). Do not
+  fetch to decorate an internal fork.
+- **Escape-hatch** — session: the file `.byan-autobench/off` disables blocking
+  (`touch` to silence, `rm` to re-enable). Cross-session: the config key
+  `escape_hatch.disabled=true` (regenerated from the YAML) disables it
+  persistently. Both still log `satisfied-escape` so misses stay auditable.
+- **No re-benchmark** — do not re-table a fork already decided and coherent with
+  the locked stack unless the user explicitly reopens it. If the architecture
+  already chose Postgres, do not benchmark Redis-vs-Postgres again.
+
+---
+
+## The 14 mantras
+
+- `BENCH-1` Gate Before Table
+- `BENCH-2` Never Benchmark A Confirm
+- `BENCH-3` Route Before Depth
+- `BENCH-4` No Fabricated URL
+- `BENCH-5` Strict-Domain Floor
+- `BENCH-6` Confidence Changes The Verb
+- `BENCH-7` One Compact Table
+- `BENCH-8` Collapse The Degenerate
+- `BENCH-9` Expand Only On Demand
+- `BENCH-10` Latency Guard
+- `BENCH-11` Respect The Escape-Hatch
+- `BENCH-12` Emit The Marker
+- `BENCH-13` No Re-Benchmark
+- `BENCH-14` Honest Ceiling
+
+Full text in `_byan/_config/autobench.yaml`.
+
+---
+
+## The honest ceiling (GH #28273)
+
+Claude Code exposes no pre-display interception hook: there is no event that
+fires BEFORE the assistant's text reaches the user. The benchmark therefore
+cannot be injected into a turn before it is shown. Two mechanisms cover this
+honestly, and neither pretends otherwise:
+
+1. **The proactive doctrine** (this file, mirrored into `CLAUDE.md` and
+   `AGENTS.md` via `byan-sync-rules`) makes the agent
+   self-apply the benchmark before it writes the choice.
+2. **The reactive Stop hook** catches a turn that presented a choice WITHOUT a
+   marker and forces exactly one regen. It is POST-HOC by construction — it
+   cannot rewrite the already-shown text, only block the turn end and require a
+   re-presentation.
+
+Promising pre-display interception would be a lie. This design does not make it:
+the first table the user sees may be unmarked; the hook's job is to ensure the
+NEXT turn corrects it, once, and that every fire and miss is recorded in
+`_byan-output/benchmark-ledger.jsonl`.

package/install/templates/.claude/rules/byan-agents.md

@@ -16,7 +16,6 @@
 | **byan** | Builder | Createur d'agents via interview (12 questions, 64 mantras) — [FC] + [ELO] intégrés |
 | **fact-checker** | Scientifique | Fact-check: assertions, audits de documents, chaines de raisonnement |
 | **agent-builder** | Constructeur | Expert en construction d'agents |
-| **marc** | Specialiste | Integration GitHub Copilot |
 | **rachid** | Specialiste | Deploiement NPM/NPX |
 | **carmack** | Optimiseur | Optimisation tokens |
 | **patnote** | Gestionnaire | Mises a jour et conflits |

package/install/templates/.claude/rules/byan-api.md

@@ -119,3 +119,67 @@ curl -X POST -H "Authorization: ApiKey $BYAN_API_TOKEN" -H "Content-Type: applic
 | Lancer un workflow | `byan_api_workflows_run` |
 | Chercher dans la memoire | `byan_api_memory_search` |
 | Importer un projet local | `byan_import_project` |
+
+## 8. Famille byan_leantime_* (board externe Leantime, distinct de byan_web)
+
+Backend SEPARE de byan_web : ces tools parlent a une instance Leantime
+self-hosted (gestion de projet), pas a l'API byan_web. Le workflow FD les
+declenche pour mirror son cycle de vie sur un board Leantime, en sens unique
+(FD pilote Leantime ; Leantime ne pilote pas FD). Cablage par phase : voir
+`.claude/skills/byan-byan/SKILL.md` section 2.5.
+
+Tu n'appelles pas ces tools a la main : le hook `PostToolUse`
+`.claude/hooks/leantime-fd-sync.js` (coeur pur `lib/leantime-fd-core.js`) fire le
+sync automatiquement apres `byan_fd_advance` / `byan_fd_update`, best-effort
+(sort en 0, n'interrompt pas le tour), idempotent via le sidecar gitignore
+`.byan-leantime/map.json`. Detail : SKILL 2.5 + `docs/leantime-integration.md`.
+
+### Config (env distinct de BYAN_API_URL)
+
+| Var | Role |
+|-----|------|
+| `LEANTIME_API_URL` | Base de l'instance Leantime (host du backend `/api/jsonrpc`, PAS le host de l'UI). Sans `/api` final — le client ajoute `/api/jsonrpc`. |
+| `LEANTIME_API_TOKEN` | Cle API Leantime, envoyee en header `x-api-key`. Generation : voir "Generer le token" plus bas (cle API compte de service OU Personal Access Token). |
+| `LEANTIME_CLIENT_ID` | Optionnel : clientId pour `addProject` (sinon premier client retourne, sinon 1). |
+| `LEANTIME_ASSIGN_USER_ID` | Optionnel : id du user humain a relier au projet cree (visibilite dans son selecteur) + editorId par defaut des taches. Absent -> projet visible du seul compte de service API. |
+
+Les deux premieres sont injectees via `.mcp.json` `${...}` (zero secret tracke).
+Quand la paire est absente, les tools reportent `enabled: false` et le FD avance
+sans bloquer.
+
+### Generer le token
+
+Cle API Leantime (header `x-api-key`), generee dans l'UI Leantime : Company
+Settings -> onglet "Cle d'API" -> "Generate API Key" (role owner/admin requis ;
+la cle a le prefixe `lt_`, affichee une seule fois). Guide d'usage complet
+(config, generation pas-a-pas, troubleshooting, securite) :
+`docs/leantime-integration.md`.
+
+### Authentification (header propre)
+
+Leantime authentifie le JSON-RPC par le header `x-api-key: <token>` — PAS le
+switch `Authorization: ApiKey/Bearer` de byan_web. Reutiliser le scheme byan_web
+enverrait un header que Leantime ignore : l'appel passe non authentifie
+(probablement un 401, ou un fall-through vers la page HTML de login que la garde
+non_json attrape). Le code exact est confirme a F0 (live-verify).
+
+### Tools
+
+| Tool | Usage | Guard |
+|------|-------|-------|
+| `byan_leantime_ping` | Healthcheck : reporte api_url, token_configured, enabled, reachable. Ne throw pas. | aucun |
+| `byan_leantime_project_ensure` | Cree-ou-recupere un projet Leantime (idempotent par nom), retourne l'id | requireLeantime |
+| `byan_leantime_task_create` | Cree une tache (addTicket) depuis un item backlog, retourne l'id tache | requireLeantime |
+| `byan_leantime_task_move` | Transitionne une tache vers une colonne `todo\|doing\|blocked\|review\|done` (resolue en statut Leantime du projet) | requireLeantime |
+| `byan_leantime_task_assign` | Pose l'assignee (editorId) | requireLeantime |
+| `byan_leantime_task_get` | Lit une tache par id | requireLeantime |
+| `byan_leantime_board_get` | Lit le board d'un projet groupe par colonne | requireLeantime |
+
+### Lecon mauvais-host (la garde non-JSON)
+
+Leantime sert l'app HTML ET l'API JSON-RPC sur le meme domaine. Si
+`LEANTIME_API_URL` pointe sur le host de l'UI au lieu du backend, un POST
+`/api/jsonrpc` peut renvoyer 200 + une page HTML de login. Le client rejette ce
+corps en `reason: non_json` avec un hint, plutot que de le lire comme un board
+vide. C'est la meme lecon que `BYAN_API_URL` (UI SSO vs host API). Si un appel
+Leantime renvoie `non_json`, corriger `LEANTIME_API_URL` vers le host backend.

package/install/templates/.claude/rules/fact-check.md

@@ -83,7 +83,7 @@ node bin/byan-v2-cli.js fc sheet [session-id]
 ## Agent dedié
 
 ```
-@fact-checker   # Agent Copilot CLI dédié
+@fact-checker   # Agent dédié
 [FC]            # Sous-menu dans l'agent @byan
 ```
 

package/install/templates/.claude/rules/strict-mode.md

@@ -9,17 +9,17 @@
 Strict mode locks a contract (the scope) at the start of a task, forces the
 agent to self-verify its work against that contract at least three times, and
 blocks the delivery (the commit) until verification is earned. It works on the
-three platforms BYAN targets: Claude Code, Codex, GitHub Copilot.
+2 platforms BYAN targets: Claude Code, Codex.
 
 | Layer | Mechanism | Platforms |
 |-------|-----------|-----------|
-| Scope lock + self-verify + complete | MCP tools (`byan_strict_*`) | all 3 (MCP) |
+| Scope lock + self-verify + complete | MCP tools (`byan_strict_*`) | both (MCP) |
 | In-session blocking | Claude Code hooks (Stop / PreToolUse / UserPromptSubmit) | Claude Code |
-| Context injection | `AGENTS.md` block / `copilot-instructions.md` block | Codex / Copilot |
-| Final net | `.githooks/pre-commit` audit gate | all 3 (commit time) |
+| Context injection | `AGENTS.md` block | Codex |
+| Final net | `.githooks/pre-commit` audit gate | both (commit time) |
 
-Codex and Copilot have no in-session blocking hook. The pre-commit gate is the
-net that catches them: a commit cannot land if a strict session was engaged but
+Codex has no in-session blocking hook. The pre-commit gate is the
+net that catches it: a commit cannot land if a strict session was engaged but
 not completed correctly.
 
 ## Source de verite
@@ -39,7 +39,6 @@ The generator emits (idempotent, between `BYAN-STRICT:BEGIN/END` markers):
 - `.claude/skills/byan-strict/SKILL.md` — the Claude Code skill
 - `.claude/hooks/lib/strict-config.json` — runtime config for the hooks
 - `AGENTS.md` block — Codex
-- `.github/copilot-instructions.md` block — Copilot
 - `src/byan-v2/data/strict-mantras.json` — the MantraValidator ruleset
 
 Do not hand-edit the generated blocks; edit the YAML and regenerate.
@@ -48,8 +47,10 @@ Do not hand-edit the generated blocks; edit the YAML and regenerate.
 
 1. **Lock the scope** — `byan_strict_lock_scope` with a verbatim restatement of
    the request and a non-empty list of testable `acceptanceCriteria`. Optional
-   `allowedPaths` restrict where writes may land. The locked scope is the
-   contract.
+   `allowedPaths` restrict where writes may land. Optional `domain` (e.g.
+   security, performance, javascript) feeds one VALIDATED tick to the ELO loop on
+   a successful completion — pass it when one technical domain dominates the
+   task, explicit only, omit otherwise. The locked scope is the contract.
 2. **Build the full scope** — do not substitute an MVP or a stub. If a part
    cannot be done, surface it as a gap in self-verify; do not cut it silently.
 3. **Self-verify >= 3 times** — `byan_strict_self_verify` with `verdict` `ok`

package/install/templates/.claude/settings.json

@@ -46,6 +46,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/mantra-validate.js"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fact-check-claims.js"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/fd-response-check.js"
@@ -58,6 +62,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/strict-stop-guard.js"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/autobench-stop-guard.js"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/drain-advisory.js"
@@ -91,6 +99,10 @@
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tool-failure-guard.js"
+          },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/leantime-fd-sync.js"
           }
         ]
       }

package/install/templates/.claude/skills/byan-benchmark/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: byan-benchmark
+description: Orchestrating conductor for the native byan-benchmark engine. Detects a real decision fork (>=2 non-substitutable options that diverge on >=1 weighted criterion), runs the autonomous DATA-only matrix engine (.claude/workflows/byan-benchmark.js) via the Workflow tool, renders the compact 1-table best-first, and emits the BYAN-BENCH marker so the auto-benchmark Stop hook is satisfied. Invoke when you are about to present a choice between options, when the user says "benchmark X vs Y", "compare these approaches", "which option", or when the auto-benchmark doctrine arms on a fork.
+---
+
+# byan-benchmark - Conductor (gate outside, engine inside)
+
+You are the human-gated conductor for the native byan-benchmark workflow. The
+autonomous scoring runs in `.claude/workflows/byan-benchmark.js` (the in-CLI
+Workflow tool); YOU own the fork detection, the rendered table, the BYAN-BENCH
+marker, and any FD/strict state. This split is the Hybrid pattern: the engine is
+native and deterministic, the gate stays on a real main-thread turn where the
+BYAN hooks fire.
+
+## Why this skill exists
+
+A launched Workflow script is autonomous: it cannot pause to ask a human, the
+main-thread hooks (including the auto-benchmark Stop hook) do not fire inside it,
+and it must not mutate BYAN state on its own. So the script returns a DATA matrix;
+this skill turns that data into a rendered, gated decision and emits the marker.
+
+## Protocol
+
+### 1. Detect the fork + gates
+
+Apply the 2-gate trigger before launching anything:
+
+- **G1** - there are >=2 non-trivial, non-substitutable options.
+- **G2** - the options diverge on >=1 weighted criterion (if they are coherent
+  with the locked stack, there is nothing to benchmark).
+
+NEVER benchmark a y/n confirm, a destructive prompt (delete/drop/rm -rf/
+overwrite/force push/reset --hard), or a trivial ack. For the degenerate /
+obvious-default case, do NOT table it - emit the skip marker (see step 5b).
+
+Routing decides links BEFORE depth decides verbosity:
+- `scope: internal` (within the existing repo/stack) - NO external links,
+  coherence-first.
+- `scope: external` (a new dependency / vendor / standard) - sourcing allowed,
+  but a URL appears ONLY if WebFetch opened it THIS turn; otherwise `[UNVERIFIED]`.
+
+### 2. Run the engine (dual-path)
+
+Prefer the native script. If `.claude/workflows/byan-benchmark.js` exists, run it
+via the Workflow tool; otherwise fall back to the markdown workflow
+(`_byan/workflow/simple/bmb/byan-benchmark/workflow.md`). The programmatic
+resolver is `resolveWorkflow('byan-benchmark')` in
+`_byan/mcp/byan-mcp-server/lib/workflows-generator.js`.
+
+```
+Workflow({ name: 'byan-benchmark', args: {
+  question: '<the fork as a question>',
+  options:  [{ name: 'Option A', note: '...' }, { name: 'Option B', note: '...' }],
+  criteria: [{ name: 'C1 ...', weight: 2 }, { name: 'C2 ...', weight: 1 }],
+  judges:   [ /* optional opposed-lens panel; omit for a single neutral judge */ ],
+  domain:   'general | security | performance | compliance',
+  scope:    'internal | external'
+} })
+```
+
+The script runs RECON -> SOURCE -> JUDGE -> RECOMMEND and returns DATA only:
+
+```json
+{ "workflow": "byan-benchmark", "question": "...", "scope": "internal",
+  "domain": "general", "options": [...], "criteria": [...],
+  "matrix": [{ "option": "...", "cells": [{ "criterion": "...", "verdict": "...",
+               "level": "L2", "score": 8, "source": "...", "unverified": false }],
+             "total": 0 }],
+  "recommendation": { "best": "...", "line": "...", "confidence": "assertive|lean" },
+  "dissent": { "option": "...", "why": "..." },
+  "degenerate": false, "needsHumanGate": true }
+```
+
+### 3. (BYAN only, opt-in) enrich cells with byan_fc_check
+
+This step is BYAN-only - other platforms skip it. For each cell whose `verdict`
+is a HARD CLAIM (a factual assertion in security / performance / compliance, or
+any absolute), call the MCP tool to raise the cell's authority:
+
+```
+mcp__byan__byan_fc_check({ text: '<the cell claim>' })  ->  { level, score, ... }
+```
+
+Stamp the returned `{ level, score }` onto the cell's `level` column. This makes
+the Niv column an audited evidence level, not a self-graded one. Respect the
+strict-domain floors: a `security`/`performance` claim below L2, or a
+`compliance` claim below L1, stays flagged `[UNVERIFIED]`. Enrichment is opt-in;
+skip it for low-stakes internal forks to keep latency down.
+
+### 4. Render the compact 1-table (best-first)
+
+Render ONE compact table, ordered best-first, within the hard caps:
+
+- **<= 4 options**, **<= 4 criteria**, **<= 3 links**, **1 screen**.
+
+```
+| Option   | C1 ... | C2 ... | C3 ... | Niv |
+|----------|--------|--------|--------|-----|
+| A (best) | ...    | ...    | ...    | L2  |
+| B        | ...    | ...    | ...    | L4  |
+
+Reco: <recommendation.line>   (confidence: <assertive recommend X | lean X, low-confidence>)
+Dissent: <dissent.option> wins on <dissent.why>.
+```
+
+The confidence verb is load-bearing: `assertive` -> "recommend X"; `lean` ->
+"lean X (low-confidence)". A URL appears ONLY if WebFetch opened it this turn;
+otherwise tag the cell `[UNVERIFIED]` and cite from model-knowledge.
+
+### 5. Emit the BYAN-BENCH marker (satisfies the Stop hook)
+
+#### 5a. Real benchmark presented
+
+On the SAME turn that shows the table, emit the marker verbatim on a single
+line, IMMEDIATELY BEFORE the table (so it survives truncation):
+
+```
+<!-- BYAN-BENCH:done g1=<#options> g2=<#divergent-criteria> scope=<internal|external> conf=<assertive|lean> -->
+```
+
+`g1` >= 2 and `g2` >= 1 or the marker is invalid.
+
+#### 5b. Degenerate / deliberate skip
+
+If the engine returned `degenerate: true`, or the fork is an obvious-default /
+confirm / destructive / already-coherent case, do NOT table it - emit the skip
+marker instead (a positive signal that the fork was CONSIDERED and deliberately
+not tabled):
+
+```
+<!-- BYAN-BENCH:skip reason=<obvious-default|never-listed|escape-hatch|already-coherent> -->
+```
+
+### 6. Expanded form (named trigger)
+
+The default is the compact 1-table. If the user types `[bench:expand]`, render
+the expanded form: full per-judge scorecards, every cell's evidence and source,
+and the dissent rationale in full. Still emit the `done` marker.
+
+### 7. Record the run (only after the gate)
+
+After the user acts on the recommendation, if inside an FD or strict session,
+record the outcome through the `byan_fd_*` / `byan_strict_*` MCP tools so the
+audit trail stays in the MCP authority. Do NOT write FD/strict state files
+directly. The auto-benchmark miss-ledger
+(`_byan-output/benchmark-ledger.jsonl`) is appended by the Stop hook, not by
+this skill.
+
+## Invariants
+
+- The script returns DATA; THIS skill owns rendering, the marker, completion and
+  state. (Enforcement contract: see `docs/native-workflows-contract.md`.)
+- The human gate stays on a real main-thread turn, outside the script.
+- Dual-path: native `.js` preferred, markdown fallback. No silent downgrade.
+- No fabricated URL: `[UNVERIFIED]` unless WebFetch opened it this turn.
+- Strict-domain floors: security/performance L2+, compliance L1.
+- Escape-hatch respected: if `.byan-autobench/off` is present (or the
+  cross-session opt-out is set), the doctrine does not force a benchmark.
+- No emoji in outputs (IA-23). Comments/notes justify the WHY only (IA-24).