From 03462b3acfbbee12aba4a18f4d971b0252d3c806 Mon Sep 17 00:00:00 2001 From: Tom Ballard Date: Sun, 5 Jul 2026 09:26:43 +0000 Subject: [PATCH 1/2] docs(decisions): record desktop capture product decision [roadmap:lore-overlay] Ratifies the gate recorded in rac/roadmaps/future/lore-overlay.md: the desktop capture host is a committed product direction. Tauri v2, cross-platform from the outset (macOS + Windows first-class, Linux deferred); admin-provisioned deployment for non-technical authors; own repository (rac-overlay per ADR-092); two-gate write model unchanged (ADR-077, ADR-065). --- .../adr-100-desktop-capture-product.md | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 rac/decisions/adr-100-desktop-capture-product.md diff --git a/rac/decisions/adr-100-desktop-capture-product.md b/rac/decisions/adr-100-desktop-capture-product.md new file mode 100644 index 00000000..a97e63e9 --- /dev/null +++ b/rac/decisions/adr-100-desktop-capture-product.md @@ -0,0 +1,106 @@ +--- +schema_version: 1 +id: RAC-KWRSFV26HZVK +type: decision +--- +# ADR-100: Start the Desktop Capture Product — Cross-Platform Tauri Overlay + +## Status + +Proposed + +## Category + +Product + +## Context + +Capture-at-the-moment is the corpus's recorded absent capability +(`growth-essay-mapping`, Row 6), and the capture architecture is already +settled: under the two-gate write model (ADR-077) an author answers an +interview and confirms fidelity — validation runs mechanically inside the +loop and ratification is an independent pull-request merge — so authoring +never requires writing Markdown or iterating against a validator. What +remained undecided was the host surface that reaches the intended audience: +non-technical knowledge owners, people who will not author through MCP +servers, coding-agent harnesses, or agents in Slack. + +The `lore-overlay` roadmap records a desktop overlay as future intent, +explicitly gated on "the decision to start a desktop product", and a staging +spike (rac-core PR #202) validated the two-gate capture core behind trait +seams. The spike also exposed the real adoption barrier for this audience: +not the capture UX but the setup — a bring-your-own model gateway and a +GitHub App are not things a non-technical author will configure. + +## Decision + +Start the desktop capture product. Specifically: + +- **The gate is ratified.** The desktop host is a committed product + direction, not exploratory intent. Scheduling remains with its roadmap and + execution epic; it must not displace already-scheduled engine work. +- **Tauri v2, cross-platform from the outset.** The product targets + availability across setups, not macOS-first-then-Windows: macOS and + Windows are both first-class targets of the initial release cycle. Linux + stays deferred (portal/compositor unevenness, per the roadmap's + non-goals). +- **Admin-provisioned deployment.** An administrator configures the model + gateway, the GitHub App identity, and the target repository once + (composing with the ADR-088 profile-scaffold pattern); the author-facing + surface is only hotkey → interview → "is this what you decided?". +- **Own repository, engine untouched.** A separate product repository + slugged `rac-overlay` per ADR-092's `rac-*` naming, with the Lore brand + carried at the organisation/marketplace level; the product name + ("overlay") remains a working title. The app is a thin client over the + `rac` contract (ADR-063); no AI enters the engine (ADR-002). +- **The two-gate model is non-negotiable.** The app's GitHub identity + proposes draft pull requests only and can never approve or merge + (ADR-065, ADR-077). + +## Consequences + +- Lore gains a capture surface for the audience the skill and MCP hosts + cannot reach, and a second installable host that proves the + skill-is-brain / host-is-interface model. Whether it works is measurable: + the artifact-completeness benchmark's residual gives a before/after + signal for corpus completeness. +- Cross-platform from day one costs more than the previously drafted + macOS-first path: two signing pipelines (Developer ID notarization and + Authenticode/SmartScreen reputation) and two OS integration surfaces + before the first release, in exchange for not excluding Windows-based + authors at launch. +- Admin-provisioning documentation becomes part of the product's + deliverable, not an afterthought — the product's reach depends on a + technical administrator's one-time setup being genuinely one-time. +- A desktop product carries an ongoing support surface (updates, signing + renewals, OS changes) that a repo-resident skill does not. + +## Alternatives Considered + +- **macOS-first, Windows fast-follow** (the roadmap's prior sequencing) — + rejected: the product's aim is availability across setups; sequencing by + operating system delays exactly the authors it targets. +- **Slack bot first** — reaches some non-technical users but not the stated + audience: people not comfortable with agents in Slack, and organisations + where such bots are restricted. +- **Skill/MCP surfaces only (no product)** — leaves the capture gap open + for everyone who is not already in a coding-agent context. + +## Related Decisions + +- adr-002-ai-optional +- adr-063-non-python-clients-are-thin +- adr-065-artifact-content-untrusted +- adr-068-extension-sdk-and-brand-architecture +- adr-077-two-gate-capture-write-model +- adr-088-enterprise-profile-scaffold +- adr-092-repository-topology + +## Related Roadmaps + +- lore-overlay + +## Related Designs + +- lore-capture-overlay +- lore-capture-surfaces From 5cc36247a8bfd8cb71a7fd76df6c7909c3a77426 Mon Sep 17 00:00:00 2001 From: Tom Ballard Date: Sun, 5 Jul 2026 09:26:43 +0000 Subject: [PATCH 2/2] docs(roadmap): record corpus setup guidance intent [roadmap:corpus-setup-guidance] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements rac/roadmaps/future/corpus-setup-guidance.md. Records the observed adoption gap: inconsistent corpus setup at organisation scale and the mega-doc-of-decisions anti-pattern, with two initiatives — an opinionated setup/structuring guide and a documented mega-doc split path via rac ingest (ADR-006). --- rac/roadmaps/future/corpus-setup-guidance.md | 96 ++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 rac/roadmaps/future/corpus-setup-guidance.md diff --git a/rac/roadmaps/future/corpus-setup-guidance.md b/rac/roadmaps/future/corpus-setup-guidance.md new file mode 100644 index 00000000..de5fab35 --- /dev/null +++ b/rac/roadmaps/future/corpus-setup-guidance.md @@ -0,0 +1,96 @@ +--- +schema_version: 1 +id: RAC-KWRSFWSF7R4T +type: roadmap +--- +# Corpus Setup and Structuring Guidance (Future) + +## Status + +Planned + +Unscheduled — recorded as future intent, not yet on a release. It must not +displace scheduled engine work; each initiative graduates with its own scope +and an ADR-093 execution issue when picked up. + +## Context + +RAC validates artifacts once they exist, but records no opinionated guidance +on how a team should set up and structure a corpus in the first place. +Observed at large-organisation scale (a ~2,500-person org): teams set up +their decision records differently and inconsistently, and default to a +single "mega-doc" of decisions rather than discrete, individually +addressable artifacts. A mega-doc defeats the properties the engine is built +on — per-artifact identity, typed relationships, per-decision lifecycle +status, and retrieval that can serve one decision to an agent instead of a +whole file. + +The pieces that would fix this exist but are not connected as guidance: +`rac init` scaffolds configuration (and profiles, ADR-088) but not +structuring conventions; `rac ingest` can split an existing document into +discrete artifacts (ADR-006, ingestion over rewrite); the onboarding +scaffold writes one starter artifact (ADR-044). Nothing tells a team "one +decision per artifact", how to lay out `rac/`, or how to get from an +existing mega-doc to a well-formed corpus. + +## Outcomes + +- A team adopting RAC lands on a consistent, conventional corpus structure + without needing a human expert in the loop — the same shape whichever team + in the organisation sets it up. +- The mega-doc anti-pattern has a documented, low-effort exit: an existing + decisions document becomes discrete validated artifacts through a + recorded path rather than a manual rewrite. + +## Initiatives + +### Initiative 1 — Opinionated setup and structuring guide + +An authored guide (docs-site + README doorway) recording the conventions the +dogfood corpus already practises: directory layout under `rac/`, granularity +(one decision or requirement per artifact, and why), naming, when to record +an ADR versus a requirement versus a design, and how the corpus composes +with `rac init` / profiles (ADR-088). + +### Initiative 2 — Mega-doc split path + +A documented recipe for converting a single decisions document into +discrete artifacts via `rac ingest` (ADR-006): what the tool does, what the +human reviews, and how the result is promoted through pull-request review +(ADR-065). Documentation-first; any tooling change needs its own scope. + +An advisory structural finding (for example, doctor flagging a single +artifact that contains many decision-shaped sections) is a candidate +follow-on, deliberately not committed here — it needs its own decision +before any gate-adjacent behaviour is added. + +## Success Measures + +- A new team following the guide alone produces a corpus that passes + `rac validate` and `rac relationships --validate` with the conventional + layout, without expert help. +- A real mega-doc has been split into discrete artifacts by following the + recorded recipe end to end. + +## Assumptions + +- ADR-017 and ADR-024 hold: the guidance covers knowledge structure, never + work tracking or content storage. +- `rac ingest` remains the sanctioned conversion path (ADR-006, ADR-072); + the recipe documents it rather than adding a parallel mechanism. + +## Risks + +- Guidance that reads as policy could conflict with how existing corpora + are already laid out; the guide records conventions and defaults, not + validation rules — anything enforceable needs its own decision first. +- Over-specifying granularity could push teams into artificial splitting; + the guide should state the principle (one addressable decision per + artifact) and leave judgement to the author. + +## Related Decisions + +- adr-006-ingest-over-rewrite +- adr-044-onboarding-scaffold +- adr-065-artifact-content-untrusted +- adr-088-enterprise-profile-scaffold