Solution — how it gets built

How to read this document. Three layers, in order: first the decisions — read their rationales as the story of how the platform chose its shape; then the technical requirements that implement those decisions, grouped by the part of the system they constrain; finally the risks we are knowingly carrying, each with its mitigation. Everything is embedded live from the record.

Architecture decisions — the story of the shape

Ten decisions, each answering one existential question. Three were made at the very start and recorded late (DEC-8/9/10 — the completeness audit caught them living only in the repo): DEC-1: what is the truth (typed items; documents as views; the graph demoted). DEC-2: how we deliver (no calendar phases — deployment-first slices). DEC-3: how the record is stored. DEC-4: where the consultant lives (the reviewable document, never chat). DEC-5: what the client may see (everything — editing is gated, visibility is not). DEC-6: what happened to the old world (clean sheet). DEC-7: what we build on (our own store and UI; ForgeDock as ideas, maybe later a component).

DEC-1 — Typed items canonical; documents rendered views; graph derived index (accepted)

Scope control, clarifications, status and briefings are all state questions, so the truth must be typed items with lifecycles — stored boringly in Postgres. Documents are rendered views that cannot disagree with the record; the knowledge graph is demoted to a derived, rebuildable index. Extraction proposes; humans confirm.

Consequence: ADR 0002. Postgres became the system of record; graph fragility stopped being existential. DEC-2 — Deployment-first: no calendar phases, capabilities ship as slices (accepted)

No calendar phases: a walking skeleton ships first, and every capability lands as a deployable slice, dogfooded on the platform's own engagement. The backlog is ordered by what the next real engagement needs, not by a plan document.

Consequence: Slice 1 shipped within a day of the decision; every build since runs gate -> build -> deploy -> dogfood. DEC-3 — Single polymorphic items table + revisions + generic links (accepted)

One polymorphic items table with JSON bodies, full-snapshot revisions and generic typed links: dozens of future item types without migrations, uniform lifecycle/diff machinery for all of them, and the scenario spine as plain data.

Consequence: ADR 0003. Body validation tightens per type as the catalog's content specs land. DEC-4 — Consultant surface is the reviewable scope document, not chat; nothing reaches the client until released (accepted)

Consultants cannot get overview in a chat stream. The scope draft rendered from items IS the review surface: agents propose into it, consultants confirm/edit/reject in place, and an explicit release step gates all client visibility so the provider side agrees scope internally first. Mirrors the original methodology: peer review precedes customer review.

Consequence: Slice 2 = review workspace + release gate; intake agents feed it. Items need a released/visibility dimension. DEC-5 — Transparency by default: clients share the consultant's views; editing is gated, visibility is not (accepted)

'Clients should be able to see everything - that is a key thing in methodology. Shared views (of course not shared editing capabilities)' - Jesper. Precedent: Netcompany clients had read access to the live Toolkit; deliverables followed draft->review->approved.

Consequence: No dumbed-down client renderings; clients reuse consultant views read-only with accept/comment. Drafts are visible and clearly stated. The controlled process is the per-document REVIEW ROUND (send-to-review), not content hiding. Netcompany precedent: clients could always access drafts but typically waited for the review invitation. DEC-6 — Clean sheet: legacy graph data deleted, legacy UI and code paths removed (accepted)

Legacy DataLens/foundation graph data and the pages reading it create ambiguity about what is current — 'risk of coding something wrong because we don't know what is legacy'. Jesper ruled: not needed, delete.

Consequence: FalkorDB graphs wiped; Explorer navigation reduced to the item-store surfaces; legacy graph endpoints/models/MCP tools excised progressively. The graph returns later only as a derived, rebuildable index over items. DEC-7 — Own UI on the item store; ForgeDock adopted as ideas (and maybe later a build-phase component), never as the platform base (accepted)

ForgeDock has no UI to base on — GitHub issues/PRs are its interface, its users are developers. Our load-bearing needs (client magic links with shared views, signable baselines and review rounds, parallel versions over one record) have no home there. Its transferable ideas are already adopted: embedded structure in prose -> {{embeds}}, process-as-markdown-specs -> methodology re-authoring, phase receipts -> telemetry.

Consequence: Stay on the item-store + Explorer path. Revisit ForgeDock at the build increments as a candidate issue-in/PR-out engine running UNDER platform governance (briefings in, pipeline receipts back as items) — integration, not foundation. DEC-8 — Dogfood first: the platform's first customer is our own consultancy (accepted)

Fastest path to truth: v1 runs our own engagements with clients getting per-engagement access. The architecture stays product-shaped (multi-tenant) so productizing later is a go-to-market decision, not a rewrite — but selling to other providers waits until the platform has proven itself on real deliveries.

Consequence: No tenant onboarding or billing machinery in v1; engagement #0 is the platform itself; engagement #1 will be a real client. DEC-9 — Hybrid agent model: native process agents, governed external coding agents (accepted)

The platform RUNS its own agents for process work — drafting scope, generating clarifications, compiling status — because that work is the product. It GOVERNS external coding agents (Claude Code and peers) via briefings, hooks and receipts, because agent runners are commoditizing and should be integrated, not rebuilt.

Consequence: CAP-2/CAP-5 are native agent capabilities; CAP-7 is a governance surface. Orchestrating coding agents directly stays out of scope unless governance proves insufficient. DEC-10 — The methodology's shape: few hard baselines, parallelizable increments between them (accepted)

Clients need contract-grade gates (scope, design, go-live — signed); agents need speed and parallelism between them. So: client-signed baselines pin agreement, increments carry design->build->test->accept mini-cycles agents can parallelize, and item-level diffs against baselines ARE change control. Phase documents become live views, not milestone artifacts.

Consequence: Replaces the classic five-phase gate cascade and pure-continuous delivery alike. Realized in CAP-4, REQ-13/16/20 and the increment model.

Technical requirements — the decisions made buildable

Five concerns, each a small cluster: read the framing line, then the requirements that pin it.

The record

One home per fact, and nothing exists without saying which story it serves.

REQ-1 — Every fact has exactly one home: a typed item with slot, lifecycle, provenance (confirmed)

Every fact an engagement needs — requirement, decision, risk, answer — exists as exactly one typed item with a slot in the document structure, a lifecycle state, and full provenance. Nothing is stated twice; everything else renders from these items. REQ-3 — Items must link to the scenarios they serve (scenario spine) (confirmed)

No scenario, screen, integration or test exists without a link to what it serves. The spine makes 'show me everything this scenario touches' a query instead of archaeology.

The content model

Documents are items; prose points at truth instead of copying it; one document renders correctly for every version; the repo's markdown becomes emitted views.

REQ-17 — Documents are items: markdown narrative with live item embeds (confirmed)

A document is an item of type 'document' whose body is markdown containing embeds by reference ({{REQ-12}}). One mechanism — lifecycle, revisions, review, release — covers atoms and narrative alike. Prose never restates item content; the renderer expands embeds at read time. REQ-18 — Orphan-fact lint: prose claims must be backed by items (confirmed)

Agents lint every document for factual claims not covered by an embedded or linked item, and propose extracting each into an item with an embed left in place. Lint results attach to the document as a completeness report. REQ-19 — Baseline-pinned rendering: one document, correct for every version (confirmed)

Any document renders 'as of' a chosen release/baseline by resolving embeds against that release's pinned item versions; the current draft resolves live. No per-version document copies exist. REQ-21 — Repo emission: VISION.md and AGENTS.md are generated views of the engagement (confirmed)

The platform emits markdown views into the project repo — vision, agent instructions, scope extracts — marked as generated, with edits flowing back as proposed changes rather than silent forks.

The agreement machinery

Immutable snapshots anchor agreement; increments let parallel streams share one record.

REQ-13 — A release is an immutable snapshot with item versions (confirmed)

Releasing records exactly which item versions the client was shown, numbered sequentially. REQ-20 — Increments are first-class: parallel streams over one record (confirmed)

An increment scopes a stream of work (e.g. 'v2 discovery') targeting a future baseline. Item changes are tagged to an increment; two increments can run concurrently; diffs compute per increment against its base baseline. Git's model applied to scope: baseline=tag, increment=branch, revision=commit, release=merge.

Agent context and instrumentation

Agents receive compiled, minimal briefings and write back; status is computed from events, never claimed.

REQ-7 — Agent briefings are compiled (two-pass), directive, with retrieval handles (confirmed)

A briefing is compiled in two passes — completeness, then ambiguity-stripping (anything not traceable to an activated slot or confirmed item is removed, because agents treat over-specification as mandatory). It arrives directive — rules and constraints, never prose overviews — with retrieval handles (stable item keys, saved queries) for just-in-time lookups, and is emitted into the formats agents already read (AGENTS.md/CLAUDE.md). REQ-8 — Every mutation emits telemetry; delivery status is computed, never reported (confirmed)

Every mutation writes an event: who, what, when. Status, queue health and drift are computed from these events — nobody writes a status report, and perception never substitutes for measurement.

The methodology's home

The catalog, the naming, and the foundation level that holds them — the methodology itself as versioned platform content.

REQ-29 — Document catalog: every document declares its type and owes its sections (confirmed)

A document item carries a doc_type from the re-authored document catalog. The catalog defines, per document type, the required sections, which item types belong in each section, and which narrative is expected. Per-document completeness and gap analysis compute against the catalog spec — the slice-1 Document Structure Index, re-authored and retargeted at the item store. REQ-30 — Re-authored document naming: phase/slug paths replace Netcompany codes (confirmed)

Retire the inherited series codes (A0100, D0180...). New convention: phase/slug paths — discovery/vision, discovery/scope, design/solution, delivery/plan, delivery/status (computed only), agreement/baseline-N. Slots become path-style: 'discovery/scope > requirements/payments'. Engagement profiles activate catalog subsets by path prefix. Existing item slots migrate once confirmed. REQ-32 — The methodology lives in the platform: catalog, specs and rules as versioned foundation content (confirmed)

A foundation level above engagements holds the re-authored methodology: the document catalog (REQ-30 naming), per-section content specs (REQ-31), and process rules — as versioned platform content that engagement profiles reference and tailor. Git remains the boundary only: markdown views are emitted (REQ-21) and edits return as proposals; there is no parallel doc-browsing surface.

Risks — what we are watching

Five open risks. The first two are already lived realities, not predictions: review fatigue appeared the day the queue passed twenty items, and the dual-edit-channel risk is why every change goes through one API. The rest are structural bets being watched.

RSK-4 — Review fatigue: agents draft faster than consultants review (open)

If the proposed queue grows unbounded, review becomes rubber-stamping and the confirm state stops meaning anything — the verification bottleneck reappearing inside our own tool.

Mitigation: Bulk confirm, confidence-ordered queues, drafting throttled to review capacity, queue-age telemetry. RSK-5 — Dueling edit channels: chat edits and UI edits fork the truth (open)

Scope edited both conversationally (via agents) and in the review UI can diverge or overwrite silently.

Mitigation: Single write path: every channel goes through the same item API, every change is a revision, optimistic concurrency on version. RSK-1 — Clarification queue becomes the new verification bottleneck (open)

Mitigation: Budget human gates; prioritize by blast radius; track answer latency. RSK-2 — Findability fails — users can't locate the right information in seconds (open)

Mitigation: Jesper's watchpoint; measured success criterion on engagement #1. RSK-3 — Graph index drifts from the item store (open)

Mitigation: Graph is derived and rebuildable; never in the write path.

Full architecture decision records live in the repo (docs/decisions/) until repo emission (REQ-21) reverses that flow.