Decision record — 2026-08-20

In short

This is the written record of one long decision session on 20 August 2026: every point below was put to the owner as a question and answered, so nothing here is assumed. It names the first milestone — one partner’s business running fully on Qren with their old website retired, and our own companies running alongside as the test bed. It settles how we build (a thin but working version of every core system before any one of them goes deep), how far agents are trusted (they begin by proposing and earn the right to act, one capability at a time), and that the old task system is replaced rather than patched. It also decides how people are let in — by invitation, in stages — and how the previous system is wound down and frozen. Everything written later as a decision or a specification is drawn from this page.

The settled design tree from the grilling session of 2026-08-20. Everything here was put to the operator as a question and answered; nothing is assumed. Becomes the spec for the first slice and the source for ADR 0006+. Research behind each decision: vault: knowledge/research/ (memory landscape, design foundation, herdr, RunRec study, brand directions, agent teamwork, work-engine audit, work-backend landscape, vault bloat audit, AOS final-release plan — all dated 2026-08-20).

0. The milestone

Faisal’s RUNREC workspace live on Qren.app, runrec.org retired — with our own companies (Nuchay, Elora Greens, Personal) running as workspaces on this Mini in parallel as the test bed. No deadline; done properly. Built by Hisham + Chief here; Zeeshan / Eddeb sit in and pick up pieces once the core is down.

1. How we build

• Horizontal, in thin slices. Every core system gets a thin but end-to-end-usable version together; nothing goes deep until all of them work on a real workspace (ours). Design doc in docs/design/ → operator approves → build the slice → use it ourselves → next.
• The approved target tree becomes ADR 0006.
• Our own Qren work moves into the new work core the day it works; the old engine is retired for us first.
• The first slice (walking skeleton): app + Supervisor + hidden folder
  • Drive, carrying the workspace/membership layer; work (items, fixed status categories, triage with four verbs, one board, handoff packet); knowledge (markdown folder per workspace, index, one recall command); drive (folder per workspace, listed in app); chat (threads on work items carrying agent turns + approval cards; no channels); companion (import a meeting → meeting record → proposed tasks via approval); connections (exactly one real one: Calendar, read-only); agents (one Lead: triage + morning brief); approval queue (shared); Supervisor running one worker; portal login + invite (exists).
• Engines: Claude Code for the skeleton; Codex proven at the ACP socket right after (a week or two, before any arm). The installer detects installed engines (claude / codex / kimi found on this Mini), shows found / not found, offers sign-in — subscription or key, the client’s choice. Never Claude-only.

2. Migration is the Gardener’s first job

(the Gardener is the agent that proposes what should move over from the old system; a person approves each proposal)

The app installs; the Gardener proposes what crosses (tasks, docs, files); the operator approves from the queue; every approval trains it. The Gardener and the approval queue are therefore foundation, built before the crossing. Our own vault is run one (→ Personal, Nuchay, Elora Greens workspaces). RunRec’s import uses the same mechanism. Same queue, same habit, same audit trail for Gardener actions and agent actions.

3. Agents — graduated trust

(an agent earns the right to act on its own, one kind of task at a time)

Agents do, not just advise — the business sells outcomes. Every agent capability starts propose-only (an approval card) and graduates to acting as approvals accumulate for that capability. Never automated: spending money, messaging a new external contact, deleting data, changing priorities. Insight-only agents are agents whose dial never moved.

Roles (from the teamwork research, to be specified in its design cycle): per-workspace Lead (triage, dispatch, synthesis, no domain tools), standing Function agents, ephemeral read-only Workers, a Reviewer capability, the Ask and Delegate verbs (the only two ways agents talk), and the owner’s cross-workspace Chief of Staff. Steward is not an agent — it is Supervisor system functions. One human accountable and at most one agent acting on every item; handoffs are board operations with a packet; max three per item, then human triage.

4. Work core — replace, not evolve

(the task system: what a piece of work is, and the few things it carries)

Minimal model: one item table, status with fixed categories, one parent, three relation types (blocks / duplicate-of / related), flat labels, one human assignee + optional agent delegate, append-only events, comments, views as data. Goals / areas / key results / inbox / threads tables: cut. Blocked and waiting are derived, not statuses. Triage is a status with four verbs: accept, decline, duplicate, snooze.

Identifiers: titles everywhere; a hidden 7-char short code for links, CLI, chat; an opt-in per-project key (KEY-123) available, off by default; no dotted sub-IDs, no t# ever shown to a person.

Lifecycle defaults (per-workspace tunable, every action a visible event): triage expires 14 d → snooze → decline; stale auto-close 90 d (human-owned) / 30 d (agent-owned), excluding items with a due date, an active cycle, or open children; archive 30 d after done / 7 d after cancelled; trash empties after 30 d.

Sync: appliance-only in v1 (members reach the appliance over portal/tailnet, as they reach runrec.org today); command log built in from day one so the edge read-replica + offline queue are additive later. Compare-and-swap on assignee / delegate / status; last-write-wins for the rest; no CRDTs.

Agent runs on an item record: session state, activities (thought / action / question / response / error), cost, tokens, tool calls, engine/model, artifacts, approval id. Handoff packet is generated from events.

5. Brain

(memory and knowledge — the notes the system keeps, and how it finds them again)

Markdown is canonical; a per-workspace SQLite ledger (FTS + vectors + edges + events + proposals) is derived; QMD’s recipe re-hosted per workspace with a write API; extraction runs inside the engine session at session end (no API key); the Gardener proposes merges / supersessions / expiries (supersede, never delete) to the approval queue. Day-one mechanical list from the audit: 51 duplicate copies, 144 empty stubs, 19 finished initiatives still active, 43 broken links, 18 undocumented types.

6. RunRec — early engagement #1

Their runrec.org is a requirements inventory, never a design; we build our way from the research and import their data. His existing Mini becomes the appliance in place, backups before anything moves; all history imported; Plaud + Fireflies keep feeding via their existing integrations (we improve them, built-in capture replaces them later); a few people move first; runrec.org points at the workspace (custom domain per workspace is a v1 requirement); bookings / sales dashboards most likely parked; Mini cleanup only with his approval; his other businesses and initiatives live in his personal workspace; one Lead agent in v1. Open questions go to him through the discovery interview on his machine (~/Desktop/qren-interview/); answers flow back here. Initiative: vault: knowledge/initiatives/runrec-engagement.md.

7. Ending AOS, admitting people to Qren

• AOS v0.8.0 “clean and freeze” — built, then held. One full update: runner off fleet-wide; purge stale DB backups (dated safety copy first); bulk-close the 4,059 noise threads; fix three defects (incl. the Telegram Created t#… echo; the reconcile check that ignores the disabled list); sentinel / converse / envoy off by default (autonomous comms = future arm); a Qren-readiness step (engine detection, inventory, invite hook). Released only when the Qren installer path is clear. Then AOS is frozen; critical patches only. Telegram notice: “AOS is no longer supported; Qren is coming, invite-only.” Faisal’s Mini is excluded — read-only for us. This Mini’s own cleanup is done (five services off, ios-deploy kept).
• Admission is invite-only and staged: invite → account approved (by Hisham only) → joins the network (portal identity, door/tunnel) → owner grants on their own machine (app install, permissions, engagement credential) → instance live. Existing AOS users are invited as the early partners; everyone walks the same gate.

8. Front door and brand

qren.ai becomes an invite-only front door now: one calm page, “Qren” in plain type, one line, “request an invite” → the approval queue. Brand identity is parked to its own session (see docs/brand/): research done, B Orbit-breathing the working scaffold, E Crest re-admitted by render evidence, wordmark and symbol may be separate, tooling research first. Light and dark first-class; one accent element per surface; the app chrome stays monochrome. Rebrand sweep at the end of core work.

9. Already locked earlier today

Target tree (D1 ai.qren.app; D2 runtime in the bundle; D3 vault → Drive, via the Gardener; D4 one DB per workspace; D5 edge/), secrets stay on the appliance with per-person grants, connections are CLI-first, the app is a client of the Supervisor over control.sock, herdr is a reference not a dependency, design foundation = shadcn on Base UI with a single tokens file and a deleted default palette.

What happens next, in order

1. Specs for the first slice (docs/design/): work core, brain, approval queue + Gardener, agent model, Supervisor + Control API, companion import, connections + secrets. Operator approves each.
2. ADR 0006 (layout) written from the tree.
3. qren.ai invite-only front door.
4. Build the walking skeleton; move our own tracking into it; our vault as Gardener run one.
5. Codex at the socket.
6. Faisal’s interview comes back → RUNREC v1 scope finalised → import.
7. AOS 0.8.0 built in ~/project/aos, held, released when ready.