π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr): ADR-409 to 415 β the console's planner, guidance and AIDefence, Claude UI bridge, attention panel, regression system, Loop Manager, Learning page and Optimizer
ruv0cbff87f1338
diff --git a/v3/docs/adr/ADR-409-console-mission-planner-and-lifecycle.md b/v3/docs/adr/ADR-409-console-mission-planner-and-lifecycle.mdnew file mode 100644index 0000000000..35a58525b4--- /dev/null+++ b/v3/docs/adr/ADR-409-console-mission-planner-and-lifecycle.md@@ -0,0 +1,57 @@+# ADR 409: The Mission Control planner and the one lifecycle++Status: Accepted++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console`: `hooks/goap.ts`, `hooks/mission-control.ts`, `hooks/mission-specs.ts`, `hooks/mission-types.ts`, `hooks/mission-text.ts`, `hooks/mission-palette.ts`, `hooks/views/mission-control.ts`, `hooks/views/mission-launch.ts`.++Extends: ADR 406 (mission records, the `session-bound` executor) and ADR 407 (the cockpit). Detail of ADR 408 sections 1 to 8.++## 1. Context++A person types a goal ("add a dark mode toggle to settings"). Ruflo already has a governed mission record (`mission_create`, `mission_plan`) and a task store (`task_create`), but nothing turns a sentence into a plan, and a mission that is only `planned` has no executor: ADR 406 defines `session-bound` tasks, which the primary Claude Code session carries out. The console needs to (a) plan without a model and without writing, (b) create the mission and tasks on one confirm, (c) hand work to Claude one task at a time, and (d) show progress without inventing it.++## 2. Decision++### 2.1 A planner, not a prompt+`goap.ts` is a goal-oriented action planner. The world is a set of facts (`specified`, `architected`, `tested`, ...). An action has preconditions, effects, a cost and an agent role. A* over fact sets finds the cheapest sequence that reaches the goal's facts; the task graph is then read off the preconditions (a step depends on the steps that produced the facts it needs), so independent steps (research beside specification, pseudocode beside architecture) share a *wave*. It is pure and deterministic: the same goal, kind and rigor give the same plan, with no model call and no I/O.++The goal's facts depend on the **kind** of work (feature, bug fix, refactor, security, research; read from the goal's words unless the person picks one) and the **rigor** (lean, standard, thorough).++### 2.2 One lifecycle for every mission+Whatever the kind, standard and thorough plans run the same lifecycle in order: **Research β Create (specification, design, ADRs and the SOP) β Build β Test β Validate β Secure β Benchmark β Learn**. Underneath, SPARC phases (S, P, A, R, C and a cross-cutting gate X) order the work. Lean is the core only; bug fixes skip the ADR and benchmark stages; research missions end in Learn (`learn-findings`). **Learn** needs the work validated first, so it is the last step: it stores the outcome and trains routing on it (the self-optimization step).++Every action carries a *stage* (`stageOf`), shown in the plan (`t4 [Create] Record the decisions as ADRs and write the SOP`) and as a lifecycle strip (`Research β Create Γ4 β Build Γ3 β ...`).++### 2.3 Creating a mission is one confirm+`createSpec` asks once (scope `goal`) and then runs `mission_create` β `mission_plan` (the plan body is the planner's output, accepted by the real tool) β `task_create` per node, tagged `mission:<id>`, `task:<tN>`, `phase:<P>`. The goal is captured when the ask is made: if it changed while the confirm was open, nothing is created. A failure at any step is caught and reported; if a task could not be created, the tasks already made are cancelled and the mission is reported as existing without tasks, so the ledger never holds a mission that can deadlock on a task that does not exist.++### 2.4 The ruflo task store is the authority+Execution state is read, never inferred: a task is *done* when the store says `completed`, *running* when `in_progress`, *failed* or *cancelled* as stored, *ready* when pending with its dependencies done, otherwise *waiting*. The console keeps only a **ledger** (the mission ids, the task map, ordered events `{seq, type, taskId, status, evidenceRef}`, pause and cancel flags) in the plugin store. A mission with no durable executor cannot be paused in ruflo, so pause, resume and cancel are the console's own ledger state: they stop the console handing out the next task, and they do not stop a Claude turn already running (said in the ADR consequences, not hidden).++### 2.5 Handing a task to Claude+`dispatchSpec` asks first (it starts a turn). On yes it re-checks that the mission is not paused or cancelled and that this task is still the next ready one and was not handed over in the last 15 seconds (a manual confirm and auto-run can otherwise both send it), marks the task `in_progress`, and submits one **visible** prompt naming the ruflo task id, the role, what done means, and how to record the outcome (`task_complete` with the evidence in its result, or `task_update` failed). If the prompt cannot be sent, the task goes back to `pending` so the mission does not stall on a task nobody is doing. Auto-run hands over the next ready task when Claude is idle and never survives a restart (the ledger loads with auto-run off).++## 3. Alternatives considered++- **Let Claude plan** (a model call per goal). Rejected for the plan itself: it costs, it is not reproducible, and it cannot be tested. A model is used where judgement helps (the guidance, ADR 410), after the deterministic plan exists.+- **Infer progress from the transcript.** Rejected: it is unreliable and unverifiable. The task store is authoritative and already exists.+- **A durable executor in the console.** Rejected for now: ADR 406 reserves durable executors for a different component; the console only ever delegates to the session.+- **One plan shape for all kinds.** Rejected: a lean bug fix and a thorough security change need different goals from the same action library.++## 4. Consequences++- Plans are cheap, instant and unit-testable; the lifecycle makes every mission end by recording what it learned.+- Pause and resume are advisory (they stop hand-over, not a running turn).+- A planner action added to the library changes plans; `tests/goap.spec.ts` pins the orders and the "every goal fact is given by some step" property.++## 5. Safety++Writes are confirm-gated with the exact argv; the plan is accepted by the real `mission_plan` schema; mission and task text is data (drawn as text, never interpreted); no secret is read or shown; the dispatch prompt is visible in the transcript.++## 6. Tests++`tests/goap.spec.ts` (orders, optimality, parallel waves, every profile and rigor reaches its goal, the lifecycle), `tests/mission-control.spec.ts` (derive, next task, create chain, dispatch, pause, auto-run, aside, guide, skills, band), `tests/mission-review.spec.ts` (the adversarial-review regressions: no double hand-over, stuck task rollback, auto-run reset, stale goal), `tests/missions.test.ts` (the view end to end against a fake CLI).diff --git a/v3/docs/adr/ADR-410-console-claude-guidance-and-aidefence.md b/v3/docs/adr/ADR-410-console-claude-guidance-and-aidefence.mdnew file mode 100644index 0000000000..0a8c38c0fb--- /dev/null+++ b/v3/docs/adr/ADR-410-console-claude-guidance-and-aidefence.md@@ -0,0 +1,50 @@+# ADR 410: Claude's guidance on a mission, and the AIDefence screen++Status: Accepted++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console`: `hooks/mission-guidance.ts`, `hooks/mission-options.ts`, the NEXT STEP to-do in `hooks/views/mission-launch.ts`, the `Mission guidance` setting.++Extends: ADR 409 (the planner). Detail of ADR 408 sections 4 and 9.++## 1. Context++The deterministic plan (ADR 409) says what stages a mission has. It cannot say which of the dozens of ruflo capabilities (plugins, agents, skills, MCP tools) fit this goal, what is risky, or what the plan leaves out. A model can, but a model turn costs money, sees whatever it is given, and may be given hostile text (a goal pasted from an issue). Two decisions follow: how guidance is produced, and how what the person types is screened first.++## 2. Decision++### 2.1 Guidance is one read-only `claude -p` turn+After a goal is planned, `startGuidance` runs `claude -p --output-format stream-json --verbose --include-partial-messages --permission-mode plan --max-budget-usd <Settings budget> [--model <Settings model>]` with a fresh session and the prompt on **stdin** (never an argument). The prompt carries: the goal, the kind and rigor, the plan and lifecycle, **this installation** (the ruflo plugins and slash commands the session lists, the AI settings) and the request: guidance **by lifecycle stage** (what to do for this goal, the acceptance evidence, which exact agents, plugins, skills, MCP tools or ruflo commands to bring in, preferring what is installed and saying plainly what is not), then *Suggestions* (capabilities the plan does not use) and *Risks*, under 700 words. The answer streams into a collapsible section, stripped of escape and control characters, capped at 400 lines and five minutes, with a Stop button.++### 2.2 It asks first, and the setting decides how+It spends, so it asks first, under the goal, with the exact command (scope `goal`); **Always accept AI turns** runs it at once; **Mission guidance** in Settings turns it off. The ask is bound to the goal it was made for: if the goal changed, or its screen verdict became blocking, nothing is sent. Re-asking stops a guidance turn still running rather than orphaning it.++### 2.3 AIDefence screens what the person typed+`screenText` runs `aidefence_is_safe` and `aidefence_has_pii` through `ruflo mcp exec` (local, $0; the detector may install itself once). Verdicts: **unsafe** blocks guidance, creating the mission and slash launches; **PII** blocks guidance (a model would see it) but not creating; **unavailable** (either detector silent, or the tool missing) warns and blocks nothing, because a gate that fails closed on a missing optional dependency would make the console unusable offline. Both detectors must answer for "safe". The text itself is never put in the verdict. A toggle turns the screen off. It screens the **goal** and the **guide** text (and, later, the Ask Claude question and a hand-typed loop task, ADR 411 and 414); text the console wrote itself (presets, the view dump) is not screened.++### 2.4 The NEXT STEP to-do+Everything the person does next sits directly under the goal, in order: goal planned, AIDefence screen, Claude guidance, create the mission, hand tasks to Claude. The first open step is marked and carries a primary button; the confirm each step raises is drawn inside the box. The to-do replaced a layout in which the guidance ask was at the top, the plan in the middle and the create button at the bottom.++## 3. Alternatives considered++- **Guidance on every goal keystroke / automatically.** Rejected: it spends without asking.+- **Resume the user's main session for guidance.** Rejected: it would pollute the transcript and the context window; a separate read-only session costs one bounded turn.+- **Fail closed when AIDefence is unavailable.** Rejected (above): warn, show it in the to-do, let the person decide.+- **Screen everything, including console-written text.** Rejected: it adds two subprocess calls to every action for text that is not the person's input.++## 4. Consequences++- A mission costs nothing until the person agrees to the guidance turn or hand-over.+- The screen adds two local calls per typed goal or guide (cached by nothing; they are quick and local).+- A flagged goal cannot be created from the palette either (the palette routes through the same actions).++## 5. Safety++Plan mode, read-only, budget cap, five-minute cap; text on stdin; escape and bidi characters stripped from the answer; the verdict never echoes the text; the detector's absence is shown, not hidden.++## 6. Tests++`tests/mission-guidance.spec.ts` (argv, prompt contents, asks first, always accept, off, streaming, failure, control characters), `tests/mission-review.spec.ts` (stale ask, half a screen is not a screen), `tests/missions.test.ts` (the to-do under the goal; an injection goal blocks guidance and create; turning the screen off lets it through).diff --git a/v3/docs/adr/ADR-411-console-claude-ui-bridge-ask-launch-plugin-map.md b/v3/docs/adr/ADR-411-console-claude-ui-bridge-ask-launch-plugin-map.mdnew file mode 100644index 0000000000..a5dbb23358--- /dev/null+++ b/v3/docs/adr/ADR-411-console-claude-ui-bridge-ask-launch-plugin-map.md@@ -0,0 +1,50 @@+# ADR 411: The Claude UI bridge: Ask Claude, Launch, and the plugin map++Status: Accepted++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console`: `hooks/host.ts`, `hooks/register.ts` (the bridge), `hooks/ask-claude.ts`, `hooks/plugin-map.ts`, `hooks/views/launch.ts`, `hooks/mission-skills.ts`, `hooks/mission-options.ts` (capabilities).++Extends: ADR 407. Detail of ADR 408 sections 3, 9 and 10.++## 1. Context++The cockpit is a pane inside Claude Code, and the primary Claude Code session is where models run and work gets done. Until 0.13 only Missions could reach it. rUv's requirement is that **every section** can invoke the primary Claude UI, and that every ruflo plugin is reachable from the console. The mod API gives four primitives: `$.prompt.submit` (a prompt as if typed), `$.prompt.fill` (put text in the prompt box), `$.command.run` (run a slash command, including a skill), `$.command.list` (which commands the session offers). Two facts constrain use: the host refuses `submit` and `command.run` from inside a `command.run` hook (it would wait on the turn the hook is holding; `/ruflo yes` is such a hook), and every one of them starts or prepares a billed model turn.++## 2. Decision++### 2.1 One bridge in the host, deferred+`host.submitPrompt`, `fillPrompt`, `runSlash` and `listCommands` are the only way the console touches the session. `submit` and `runSlash` run from a clock tick (`$.clock.after(1, ...)`), a later event of their own, never inside the hook that asked. `fillPrompt` is used instead whenever a turn is active (`state.turnActive`, kept from the prompt bar's render): it only prepares the text and the person presses Enter.++### 2.2 Ask Claude, on every page+A **β¦ Ask Claude** button is in every page's footer, and `/ruflo ask <question>` does the same. `VIEW_ASK` has one row per view (a default question and, where a ruflo plugin fits, its slash command). The prompt is the question followed by the view's own text (what `/ruflo dump <view>` prints), quoted as **data**: every line behind `β`, so none can begin a slash command, with an opening line saying the lines are data, not instructions. Secrets are redacted first (keys, tokens, JWTs, bearer headers, PEM blocks, `NAME=value` of a secret name, capped at 4000 characters). The terminal and Settings share no text (a conversation, setting values). A typed question is screened by AIDefence (ADR 410). It always asks first, with the exact text and a billing note; mid-turn it only fills the box. A `/btw` aside variant exists.++### 2.3 Every plugin has a home+`plugin-map.ts` assigns each directory under `plugins/` to the section that owns it, or says why it is reached from the Plugin Catalog only (domain plugins that can spend or write devices: music, market-data, neural-trader, iot-cognitum; and the console itself). `tests/plugin-coverage.spec.ts` reads the directory and fails on an unmapped plugin, a stale entry, or a home that is not a view. Adding a plugin without deciding where it lives breaks CI.++### 2.4 Launch+Every page ends with a folded **Launch** section listing the slash commands of the plugins that section owns, as the session lists them (`listCommands`, read once at open; the page redraws when it arrives). A button asks first, then runs the command in the main UI (or fills the box mid-turn). A command that is not listed is refused, and a section whose plugins are not loaded draws nothing. Mission Control additionally offers the ruflo-goals skills and every other plugin the session offers as **capabilities** run on the goal, with the same confirm and the same AIDefence block.++## 3. Alternatives considered++- **Call the plugins' MCP tools directly from the console.** Rejected as the default: the point is the Claude UI, where the person sees and steers the work; the console already runs fixed ruflo commands where a command is the right unit (labs).+- **Hand-written per-view prompts.** Rejected: the dump already renders every view as words; a table of defaults plus one helper is smaller and cannot drift from what is on screen.+- **Send the question and the data unquoted.** Rejected: a line of data beginning with `/` or `!` would run as a command.+- **Hotkeys for the new buttons.** Not possible: all 36 digit/letter keys are taken (ADR 408 section 6).++## 4. Consequences++- Every section can reach the primary UI; every plugin has a place; both are enforced by tests.+- The footer gains one button; tall pages gain a folded section.+- A prompt submitted as text starting with `/` is run by the engine as a typed command; the fake test engine cannot observe that, so the exact text is asserted in unit specs.++## 5. Safety++Confirm before any turn starts; billing said on the confirm; data quoted and redacted; typed text screened; commands only from the session's own list and a closed name grammar; deferral prevents a deadlocked hook; nothing is read from a plugin's output as instructions.++## 6. Tests++`tests/ask-claude.spec.ts` (table covers every view, scrubber, quoted data, no leading slash, delivery idle and mid-turn, aside, screening, launch list), `tests/plugin-coverage.spec.ts`, `tests/matrix.test.ts` (every view mounts at two widths and its Ask button sends exactly one clean prompt; the Launch section), `tests/mission-review.spec.ts` (a slash launch asks first and is blocked for a flagged goal).diff --git a/v3/docs/adr/ADR-412-console-attention-answers-open-where-asked.md b/v3/docs/adr/ADR-412-console-attention-answers-open-where-asked.mdnew file mode 100644index 0000000000..72fe41de2b--- /dev/null+++ b/v3/docs/adr/ADR-412-console-attention-answers-open-where-asked.md@@ -0,0 +1,53 @@+# ADR 412: Answers open where they were asked++Status: Accepted++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console`: `hooks/views/attention.ts`, `hooks/register.ts` (`ui.press`, `ui.input`), `hooks/runner.ts` (origin), `hooks/views/pane.ts`, `hooks/views/common.ts` (`confirmRow`, `confirmInline`), the lab views' `slot`, `hooks/memory-lab.ts` (its own panels).++Extends: ADR 407. Detail of ADR 408 sections 5, 11 and 11a.++## 1. Context++The console is a tall scrolling page of sections full of buttons. Each action that asks (a confirm) or answers (a result) used to draw in a fixed place: the confirm above the whole body, the lab result in one block far from the button. A person clicking a row halfway down the page had to scroll up to confirm and down to read, and often did not notice that anything was waiting. rUv reported this for the Memory Lab and then for MetaHarness, and asked for it on every page: either scroll to the area or move it below the click, with a clearer sign that something needs a click.++## 2. Decision++### 2.1 Know where the click came from+The engine raises `ui.press` for a pressed `Button` and `ui.input` for an `Input`, and hooks run **before** the element's own `onPress`. `register.ts` records the pressed key in `state.lastPressed` (a submit for an Input; the confirm keys `confirm`, `cancel`, `remember`, `always` are answers and never move it). `runner.ask`, the single entry for every action, turns it into `state.origin` and clears `lastPressed`. A headless run (the palette, `/ruflo run`) has no press, so no origin.++### 2.2 Place the panel after the child that holds the origin+When an origin is waiting, the page is drawn through a kit whose **column Box** watches for it: the first column holding the origin's element gets the **panel** (the confirm unless the view draws its own, the outcome of the last action, and a lab's result lines) right after that child. Which element holds the origin is learned from keys already on the elements (the same `key` the tests read) and remembered by identity in a `WeakMap`; the engine's element shapes are not otherwise touched. A quiet page (no origin) is drawn with the plain kit, so it costs nothing extra.++### 2.3 Lab results are donated, not duplicated+A lab view hands its result block to the panel (`slot`): the block alone is drawn once to find its rows (reused while the view, width, result, scroll and spinner are unchanged), then the page is drawn with the panel placed and the block hidden. If the origin is not on screen (a hotkey, the palette, a folded section) the confirm falls back to the top and the lab keeps its block at its foot, so nothing is ever lost.++### 2.4 Say that something is waiting+The confirm is headed `βΆ CONFIRM NEEDED β click Yes or press y`, and the status row says `β confirm needed: <what> β y yes Β· n cancel` wherever the confirm sits, so a pending ask is visible without scrolling.++### 2.5 Views that already placed their own+Mission Control, Hive-Mind and Memory Lab place their asks in their own areas (`confirmInline`); the panel skips the confirm for them and still carries outcomes. An ask with scope `ask` (Ask Claude, Launch) is always drawn by the panel.++## 3. Alternatives considered++- **Scroll the pane to the confirm.** Rejected: the pane's scroll belongs to the engine and moves under the person; placing the confirm under the click needs no scroll.+- **Wrap every `Button` to record presses.** Tried; rejected: it cost about 1 s on the Dev Tools sweep (about 30%) because every render wrapped every button. Hooks cost nothing per render.+- **Per-view code in every lab.** Rejected: nine views, nine chances to drift; one mechanism and a one-line `slot` per result block.+- **Draw the confirm in a modal.** Rejected: the mod API has no modal for panes, and a modal hides the context the person is deciding about.++## 4. Consequences++- Every page behaves the same; a new lab gets the behaviour by calling `slot` once.+- The page is drawn twice for a frame in which a lab result is on screen and its inputs changed; steady state is one draw.+- The origin is the last press that raised an ask: an async result arriving much later still draws under that press until the next ask.++## 5. Safety++The panel holds the same confirm the pane always drew (same argv, same note, same Yes/Cancel); it never auto-answers; the fallback is the old location.++## 6. Tests++`tests/attention.test.ts` (MetaHarness and Dev Tools: the confirm is the very next button after the pressed one, the result follows, nothing twice; a folded or headless ask goes to the top), the Memory Lab placement test in `tests/labs.test.ts`, and the kit tests of the Loop Manager, Learning and Optimizer sections, each of which asserts its confirm sits under its button.diff --git a/v3/docs/adr/ADR-413-console-regression-system.md b/v3/docs/adr/ADR-413-console-regression-system.mdnew file mode 100644index 0000000000..7d52f39c05--- /dev/null+++ b/v3/docs/adr/ADR-413-console-regression-system.md@@ -0,0 +1,45 @@+# ADR 413: The ruflo-console regression system++Status: Accepted++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console/tests/**`, `plugins/ruflo-console/scripts/{smoke,e2e,e2e-lib,e2e-smoke}.sh`, `scripts/ci-test-baseline.txt`.++Extends: ADR 407 section 12 (release gates). Detail of ADR 408 section 10.++## 1. Context++The console grew to 28 views, hundreds of buttons, a bridge into the primary Claude UI and several features that interact (the attention panel, the plugin map, the launch rows). Tests existed per feature, each naming the views it touched. A deep review found what that misses: a view added to `VIEWS` but never swept; a hotkey collision; a duplicate element key; a button whose handler did nothing; a plugin added with no place in the console; a crash only at a narrow width. rUv asked for a regression system proving every section works end to end.++## 2. Decision++Five layers, each catching what the one below cannot.++1. **Pure specs** (`tests/*.spec.ts`, vitest, no engine): planner optimality and waves, argv for every palette and lab entry, the scrubber, the screen grammar, the loop grammar, the optimizer's findings, the nav hotkeys (single digit or lowercase letter, unique, none on a reserved key, Missions is 1), `plugin-coverage` (every plugin directory has a home; no stale entry; every home is a view; a catch-only plugin says why), and a guard that **every Optimizer fix is a real palette entry** (a typo is a dead button). `smoke.sh` runs all of them.+2. **Kit tests** (`tests/*.test.ts`, `claude plugin test`, the real engine with fake CLI, fs and session): each feature end to end, and **`matrix.test.ts`**: for every view in `VIEWS`, at 80 and 150 columns, it mounts the pane, forbids `undefined`, `NaN`, `[object`, `TypeError` and `ReferenceError` in the text, requires the view to name itself, forbids two Buttons or Inputs with one key, then presses **Ask Claude** and requires the confirm first and exactly one clean prompt after yes (quoted data, no secret). `sweep.test.ts` presses every button of each lab. Kit tests cannot run under root vitest (the engine package does not resolve there), so `scripts/ci-test-baseline.txt` lists them and smoke step 12 fails when a `*.test.ts` file is missing from it.+3. **Conformance** (`conformance.spec.ts`, `RUFLO_CONFORMANCE=1`): every palette, start and lab argv is checked against the real CLI's `--help` and MCP tool names.+4. **Smoke** (`smoke.sh`, 16 steps): plugin.json and version, hooks.json names one module, no classic hooks, no secrets, every source file under 500 lines, kit tests registered, the marketplace lists the console, all pure specs, the live-smoke script exists and skips cleanly, `VIEW_ASK` covers `VIEWS`.+5. **Live no-spend smoke** (`e2e-smoke.sh`): with `RUFLO_E2E_LIVE=1` it opens every view with `/ruflo <view>` in a real Claude Code under tmux (an isolated config dir with the login copied and shredded on exit, as `e2e.sh` does), fails on a thrown render or a broken frame, and takes **no AI turn and writes nothing**. Without the flag it prints SKIP and exits 0, so CI can run it everywhere.++## 3. Alternatives considered++- **One big end-to-end test against the real CLI.** Rejected for CI: slow, network-dependent and flaky; the live smoke exists for it, off by default.+- **Snapshot tests of every view.** Rejected: the BBS look, animation and data make snapshots churn; the contract (no error text, unique keys, the bridge works) is what matters.+- **Assert a handler on every Button.** Tried in the matrix; the engine keeps `onPress` closures out of the element, so the check was always false. Dead buttons are caught by the sweeps and by specs on the entries buttons run.++## 4. Consequences and lessons++- A new view fails CI until it has a hotkey, an ask row, a plugin home if it owns a plugin, and a matrix entry (derived from `VIEWS`, so automatically).+- Timing is a real constraint: the Dev Tools sweep must finish in the engine's 5 s default test budget (it took 3.3 s; a render change that cost 1 s per sweep was caught and redesigned, ADR 412).+- A GitHub `Test Suite` check that runs network validators (marketplace clone, MetaHarness packages) fails now and then for reasons unrelated to a change; rerunning the failed job is the correct response, and the log is read first.++## 5. Safety++The live smoke never presses Enter in Claude's own prompt except to submit a `/ruflo` slash command; it takes no AI turn, writes no ruflo state, and its credential copy is 0600 and shredded.++## 6. Sources++`plugins/ruflo-console/tests/{matrix,attention,sweep}.test.ts`, `tests/{nav,plugin-coverage,ask-claude,optimizer,loops,learning}.spec.ts`, `scripts/smoke.sh`, `scripts/e2e-smoke.sh`.diff --git a/v3/docs/adr/ADR-414-console-loop-manager.md b/v3/docs/adr/ADR-414-console-loop-manager.mdnew file mode 100644index 0000000000..9076f0a7db--- /dev/null+++ b/v3/docs/adr/ADR-414-console-loop-manager.md@@ -0,0 +1,42 @@+# ADR 414: The Loop Manager++Status: Accepted (ships in ruflo-console 0.15.0)++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console`: `hooks/loops.ts`, `hooks/views/loops.ts` (a folded section of the Automation page).++Extends: ADR 411 (the Claude UI bridge). Detail of ADR 408 section 12.++## 1. Context++Claude Code's `/loop` repeats a prompt on a schedule or self-paces it. Ruflo ships workers (`ruflo-loop-workers`), a scheduler and an autopilot that are meant to run that way. A person had to remember the command, the interval syntax, the worker names and a stop condition; a forgotten stop condition means a billed turn on every tick for up to seven days. rUv asked for a loop manager with a configurator, presets from practical to exotic, and a launcher into the Claude UI.++## 2. Decision++- **Where:** a folded section at the top of Automation, which already owns `ruflo-loop-workers` and `ruflo-autopilot` (ADR 411 plugin map). It is not a new view: every hotkey is taken.+- **Presets (16, three tiers).** *Practical*: watch CI on this branch, keep the tests green, babysit open PRs, the audit and test-gap workers. *Steady*: optimize and consolidation workers, autopilot, a nightly schedule, docs kept in step. *Exotic*: MetaHarness drift watch, the dream cycle (the flywheel evaluates candidates into receipts and **never promotes**), a hive-consensus loop, the long-horizon tracker, ultralearn, swarm self-heal. Each preset states what a tick does and costs.+- **Configurator:** interval (self-paced, 1m, 5m, 10m, 30m, 1h, 4h, 1d), task (a preset's, or typed), stop condition. The stop grammar is closed: `until HH:MM`, `after N runs` (1 to 999), `when done`, or empty. The exact `/loop ...` is shown before anything runs, or the reason it cannot be built.+- **Launcher:** asks first, with the exact text and a note that every tick is a billed Claude Code turn, that a loop expires after seven days, and (when no stop condition is set) that none is set. On yes it submits one visible `/loop ...` prompt to the main UI (mid-turn: fills the box), which the engine runs as a typed command. **List / stop my loops** asks Claude to list `CronList` and pending wake-ups and to ask before stopping any.+- **Input rules.** A task that starts with `/` must be one plugin command the session lists, with at most a few plain words after it (a worker preset needs its plugin: otherwise it says so and asks nothing). Control and bidirectional characters are removed; a task is cut to 400 characters and the whole input is at most 600. A hand-typed task is screened by AIDefence (ADR 410); a preset is the console's own text and is not.++## 3. Alternatives considered++- **Create the cron job directly (`CronCreate`).** Rejected: `/loop` is the user's own mechanism and may self-pace with a Monitor; going through it keeps the transcript the single place the loop is visible and stoppable.+- **Run loops inside the console.** Rejected: the console has no turn of its own and must not hold a session open; the loop belongs to the Claude session that pays for it.+- **Free-form stop text.** Rejected: an unparseable stop condition is a loop that never stops; a closed grammar can be tested.++## 4. Consequences++- A person can start a bounded, understood loop in three clicks; the cost note is on the confirm.+- The fake test engine cannot observe a submitted slash-prefixed prompt; the exact text is asserted in `tests/loops.spec.ts`, and the kit test asserts the confirm sits under the Start button and nothing failed.++## 5. Safety++Confirm first with the cost; no auto-start; a closed stop grammar; plugin commands only from the session's list; typed text screened; list/stop never stops without asking.++## 6. Tests++`tests/loops.spec.ts` (grammar, builder, every preset builds, launch asks first and screens, mid-turn fill), `tests/loops.test.ts` (the folded section in Automation, picking a preset, the exact `/loop`, the confirm under Start, a worker without its plugin asks nothing).diff --git a/v3/docs/adr/ADR-415-console-learning-page-and-optimizer.md b/v3/docs/adr/ADR-415-console-learning-page-and-optimizer.mdnew file mode 100644index 0000000000..fd97de6612--- /dev/null+++ b/v3/docs/adr/ADR-415-console-learning-page-and-optimizer.md@@ -0,0 +1,46 @@+# ADR 415: The Learning page and the ruflo Optimizer++Status: Accepted (ships in ruflo-console 0.16.0 and 0.17.0)++Date: 2026 10 03++Decision owner: Ruflo maintainers++Scope: `plugins/ruflo-console`: `hooks/views/learning.ts`, `hooks/views/learning-pulse.ts`, `hooks/pulse.ts`, `hooks/neural.ts` (the new entries), `hooks/optimizer.ts`, `hooks/views/optimizer.ts` (a section of the Overview).++Extends: ADR 412 (answers open where asked). Detail of ADR 408 sections 13 and 14.++## 1. Context++Ruflo's value compounds when it learns (patterns, the router, memory, vectors) and degrades quietly when it does not. The Learning page showed numbers and three static pictures; learning actions lived in a separate lab; nothing told a person what was thin or broken or how to fix it. rUv asked for better animated charts and graphs, collapsed settings and configuration, more self-learning capabilities, and an optimizer that finds and fixes problems and improves learning, vectors and other advanced features, with options and results to click.++## 2. Decision++### 2.1 Learning page (0.16.0)+- **Learning pulse:** text charts that move while the page is in front: a marker travels RETRIEVE β JUDGE β DISTILL β CONSOLIDATE; the router's model mix is a bar chart with a highlight sweeping each bar; the running success rate over the last 24 routed outcomes is a sparkline with a scanning cursor; SONA's trajectories, patterns and signals are gauges. They draw only what was measured (no data, no chart; `n/a` says so). The frame loop asks for a redraw about three times a second (`pulseDue`, 350 ms) only while the Learning page is shown and focused.+- **Settings & configuration (folded):** `neural.enabled` and `hooks.enabled`, each a confirm-gated `ruflo config set` through the Settings actions.+- **Self-learning actions (folded)**: the Learning Lab's rows on this page plus new entries, all fixed argv through `mcp exec`, none calling a paid model: pretrain at three depths (`hooks_pretrain`: local, reads the repository, writes the intelligence store), consolidate (`agentdb_consolidate`, no options), pattern search (`hooks_intelligence_pattern-search`, a read), teach a pattern (`hooks_intelligence_pattern-store`, a local write). Each is also `/ruflo run nn-...`. Their answers open under the pressed button (ADR 412).++### 2.2 The Optimizer (0.17.0)+A section at the top of the Overview: **findings** from what the console already measured, worst first (nothing learned yet; the router missing under 60% of at least 10 outcomes; no router state; memory unchecked; thin vector coverage; a second memory store; a store large enough to compact; performance unmeasured; every alert the console already raises; the full health check), each with a **fix per button** that is an existing palette entry (so it asks first and adds no new way to write), a **scope** (safe, balanced, deep) limiting which fixes are offered, the metric **before and after** a fix, and **β¦ ask Claude** about a finding. An unread store is a finding to check, never a verdict.++## 3. Alternatives considered++- **Real-time graphs from the daemon.** Rejected: the console reads files and local JSON only; a text pulse driven by the clock over measured data needs nothing new.+- **A new Optimizer view.** Rejected: no hotkey is free; the Overview is where health already lives.+- **One-click "fix everything".** Rejected: each fix writes ruflo's stores and asks; chaining confirms hides what is being agreed to. The scope and per-finding buttons keep each yes small.+- **Auto-optimise on a schedule.** Rejected here; the Loop Manager (ADR 414) can run the optimize worker if a person wants that, with its own cost note.++## 4. Consequences++- The Learning page has life without polling anything new; the redraw costs one invalidate per 350 ms while shown.+- A fix that names a palette entry that does not exist fails a spec: the Optimizer cannot ship a dead button.+- Findings depend on what has been read: opening Memory makes memory findings sharper.++## 5. Safety++No entry calls a paid model; every write asks first with its argv and note; pretrain and rebuilds are local compute that writes ruflo's own stores; model downloads are only in the deep scope; nothing is deleted from here.++## 6. Tests++`tests/learning.spec.ts` (argv, validation, headless ids, the pulse timer), `tests/learning.test.ts` (the pulse moves over real time; the folded sections; a confirm under the pretrain strip), `tests/optimizer.spec.ts` (findings, scopes, every fix a real palette entry, before/after, ask), `tests/optimizer.test.ts` (the section in the Overview; a fix's confirm sits under its finding; nothing runs before yes).