Part II — The Journey: from rosetta-core to a delivered engagement

This is the chapter to read first if you want to understand what Rosetta is by watching what it does. It follows one continuous story — a practice adopting Rosetta and running a single engagement through it, end to end — and at every stage names the repository, the tool, and the contract doing the work. Every mechanism described here is verified against the codebase as of 2026-08-29; the pointers at the end of each stage tell you where to check.

The cast: a content author (a subject-matter expert whose knowledge becomes canon), an operator (the platform administrator who owns production and ratification), a seller and a delivery team (the humans working the engagement), and a set of AI agents (Claude Code / Cowork sessions driving Rosetta's plugins and MCP tools). The engagement example is Northern Trail Outfitters (NTO) — Salesforce's fictional outdoor retailer, the same demonstration engagement the public docs tour uses, built on simulated data and honestly labeled as such by the platform's own provenance system.

flowchart LR
    A[1 · Author the canon<br/>rosetta-research → db/seeds/] --> B[2 · Stand up the estate<br/>schema + seeds + RGAS + MCP + KMS]
    B --> C[3 · Client & engagement birth<br/>clientUid required]
    C --> D[4 · Build the twin<br/>rosetta-archaeology / twin:apply]
    D --> E[5 · Work the engagement<br/>rosetta_turn · query · canvas · rehearsal]
    E --> F[6 · Govern<br/>DT → PC → ADR · ratify]
    F --> G[7 · Render<br/>Thesis · SOW · Spec Manifest]
    G --> H[8 · Deliver & close the loop<br/>run ledger · retro · promotion]
    H -.->|learnings graduate into canon| A

Stage 1 — Author the canon: rosetta-core creation

Everything in Rosetta descends from one root: the rosetta-core canonical baseline, the graph content rooted at the domain key salesforce:rosetta-core. This is the shared canon every engagement inherits — the vocabulary, the semantic entities, the platform objects and engine functions, the validated context patterns, the business intents they address, and the ADRs that govern them. Before any engagement exists, someone has to author this content, and the way it is authored is the first place Rosetta shows its character: canon is compiled from evidence, not written from memory.

The authoring front-door is the rosetta-research plugin (v0.14.2), a seven-stage pipeline run in a Claude Code / Cowork session against a product family (the current baseline covers Salesforce Data 360):

1. Intake reads the evidence corpus — an inventory CSV in the producer repo whose rows point at source documents — plus gap-filling web research, and emits research notes. A document is "in the corpus" if and only if it has an inventory row; evidence files themselves stay out of git.
2. Extract translates the notes into metamodel-aligned candidate nodes and edges.
3. Author-Nodes emits canonical Cypher for the five shared node types — vocabulary terms, semantic entities, platform objects, engine functions, business intents.
4. Author-Patterns emits the context patterns — the validated implementation plays that are the graph's primary retrieval target — with their edges into all three layers of the model.
5. Provenance emits SourceArtifact nodes and CITED_BY edges tethering every authored node back to a corpus row, plus a ProvenanceEvent recording the run.
6. Author-ADRs emits three to seven baseline ADRs per product family — one per major irreversible architectural decision, each GOVERNS-linked to the patterns it constrains and cited by its sources.
7. Validate runs static analysis: evidence-tether gates, load-time checks, coverage reporting.

The output is not "content in a CMS" — it is Cypher files proposed against rosetta-platform/db/seeds/, landing through an ordinary pull request. The producer repo meets that PR with machinery: make intake-validate pre-flights the five-field identity contract (every canonical node carries domainKey, stableKey, qualifiedKey, displayId, overrideMode — the identity system Chapter 2 describes), and CI runs the invariant gates — 39 numbered checks (INV-D1..D39) that enforce closed enums, edge contracts, evidence tethering, and partition isolation at load time. The current baseline is eight seed files for the Data 360 family — including 20 context patterns, 15 business intents, 12 engine functions, and 89 source artifacts — every one carrying its evidence tether.

Two honest footnotes belong in an assessment. First, the authoring pipeline's output has historically required human patching: two successive plugin releases could not stop the authoring model from inventing non-canonical enum values, so the committed baseline is a hand-corrected derivative of the plugin's output, and the invariant gates — not the plugin — are what actually hold the line (the producer repo records this candidly). Second, external contributors bring content through the same PR lane with a designated- reviewer scheme — the intake is a governed door, not an open write path. Only admin-role actors write to the root domain.

Verify: rosetta-platform/db/seeds/ (8 files), db/README.md, util/plugins/rosetta-research/skills/product-family-research/SKILL.md, scripts/neo4j/d360-invariants.sh, metamodel §5.5 (root domain).

Stage 2 — Stand up the estate

The canon is inert until it is served. Standing up a Rosetta estate is a producer-then-consumer sequence, and the ordering is itself a governed invariant (the producer publishes; consumers read the published contract — never the reverse):

• Graph and relational schema. The producer's 46 schema files are applied to Neo4j (make db-init) and its 28 idempotent, numerically-ordered SQL migrations to MySQL (make mysql-init) — MySQL owns identity and tenancy (users, accounts, API keys, engagement access, platform admins); Neo4j owns knowledge (everything in Chapter 2). Seeds load with make db-seed-all; the composed production lane (make prod-migrate) chains schema, seeds, engagement stacks, the serial invariant gates, API registration, and a ProvenanceEvent ledger entry — a migration that cannot silently skip its own gates.
• The API server. rosetta-app-server (RGAS) — a Go service, Chi-routed, with every Cypher query externalized into versioned files rather than concatenated at runtime — deploys as a scratch-based container on a single VM behind Caddy. Its public /health reports healthy only when both stores answer.
• The agent surface. rosetta-mcp-server wraps the REST contract as 43 rosetta_* MCP tools (38 generated one-to-one from the vendored OpenAPI spec, 5 hand-written composites) behind a deny-by-default tool policy. It ships as static cross-compiled binaries and speaks two transports: stdio for local plugin use, and streamable HTTP (with a full OAuth authorization server) at the hosted connector endpoint.
• Keys and distribution. The enablement agent at rosetta-design.com is the front door: humans register (a fail-closed, data-driven domain allow-gate decides who may), are auto-assigned to their tenant account by verified email domain, and mint an rsk_-prefixed API key in Settings → API Keys (stored only as a bcrypt hash, scope-carrying). The same site serves the KMS-gated install routes — plugin bundles and MCP binaries — so make install-plugins (or the curl | bash shape) can pull a tag-pinned bundle and auto-register the seven-plugin marketplace in the operator's Claude settings.

At the end of stage 2 the practice has: a governed graph, a versioned REST contract, an agent tool surface, and per-human credentials. Nothing engagement-specific exists yet.

Verify: rosetta-platform/Makefile (98 targets; prod-migrate), rosetta-app-server/internal/server/server.go, rosetta-mcp-server/config/mcp/ tool-policy.yaml, rosetta-enablement-agent/app/src/lib/auth/api-key.ts and registration-gate.ts.

Stage 3 — Open a client and an engagement

An engagement cannot exist in a vacuum, and this is enforced at birth: clientUid is required when an engagement is created — the one deliberately breaking change in the REST contract's history (api 1.4.1 → 1.5.0, ratified before it shipped). The client record comes first; the engagement is born linked to it, and an invariant gate (INV-D38) holds the linkage: every engagement carries exactly one incoming HAS_ENGAGEMENT edge from a client, forever after.

Creation itself is a dual write — a Neo4j :Engagement node and a MySQL row — and the creator is atomically granted the lead role on the new engagement (a lesson learned the hard way: an earlier version created engagements their own creator could not see). Access from there is tenancy-shaped: account-wide roles (owner/admin see everything) or per-engagement grants for members; denial is always a 403, never a 404. Engagement identifiers are human-legible slugs (nto-01), not UUIDs — they appear in file paths, Cypher, and conversation, and the system treats them as names.

The seller's team can do all of this three ways: through the console UI, through the REST API, or conversationally through the rosetta-agent plugin's engagement-lifecycle skill — which knows the contract (including the clientUid requirement and the "typo silently mints a new client" trap) and operates under the write-safety contract described in stage 6.

Verify: rosetta-app-server/internal/engagement/store.go, internal/authz/authz.go; util/plugins/engagement-authoring/ (the distilled creation guide); INV-D38 in scripts/neo4j/d360-invariants.sh.

Stage 4 — Build the engagement's Digital Twin

Now the engagement's own knowledge starts accumulating, and Rosetta's central data structure appears: the Digital Twin — a living, structured model of what the customer wants, what exists in their environment, what has been decided and why, and what remains unknown. Structurally, the twin is a leaf KnowledgeDomain in the domain stack: salesforce:rosetta-core at the root, intermediate domains below it, and this engagement's domain at the leaf — inheriting the whole canon, able to override it locally through the five-value overrideMode vocabulary without ever mutating it.

There are two producer paths into the twin, and they meet at the same wire contract:

The archaeology path (brownfield: the engagement already has history to recover). The rosetta-archaeology plugin runs four phases against a discovery dossier and the producer repo: Survey establishes the leaf domain, business intent, and org topology; Excavate builds the evidence inventory; Classify authors the three-layer Context Artifacts and externalizes DecisionTraces from trajectory evidence — each with the state at decision time, the alternatives considered, and a leadership-legible gloss authored at emit review, never boilerplate — plus the 11-dimension readiness verdict compiled to graph data; Preserve identifies promotion candidates and emits the delivery spine (waves → epics → sprints → work packets, each carrying a required plain-English purpose). The output is the engagement Cypher stack under db/engagements/<key>/ — committed to the producer repo as authoritative — and a compiled twin.json in the wire format. Publishing to the live graph is deliberately opt-in (--publish); the default lane is the offline seed load.

The advisory path (greenfield: the twin grows from structured discovery). The Data 360 Advisory Framework — a methodology skill that runs fully file-only when no substrate is present — persists its defining outputs at each phase close through one atomic twin-apply: use-case scores, the seven-domain capability assessment, the data-reliability risk register, the forensic evidence inventory, and the readiness verdict, landing as the five canvas-dimension labels the live scorecard renders from.

The wire contract both paths hit is POST /engagements/{uid}/twin:apply with a TwinDocument: nodes and edges, each node carrying either the five-field identity (for inheritable labels) or a natural key (for engagement-local labels), an optimistic baseRevision guard, atomic or best-effort mode, and idempotency keys — one ProvenanceEvent per apply. What the tour page shows as "the digital twin takes shape" is, mechanically, this document landing.

For NTO the twin holds four context artifacts (unified profiles, loyalty journey, Agentforce deflection, the data foundation), the identity-resolution decision with its guardrails, and the named gaps — including a tracked contradiction (real-time order-status requirement vs. nightly POS freshness) with its scoping resolution recorded, not hidden.

Verify: util/plugins/rosetta-archaeology/skills/digital-twin-archaeology/SKILL.md, db/engagements/README.md and db/engagements/nto-01/, rosetta-app-server/internal/digitaltwin/twin.go (the TwinDocument compiler), d360-advisory-framework/SKILL.md §twin integration.

Stage 5 — Work the engagement

With a twin in place, the engagement becomes a place where people and agents work, and the MCP composites are the verbs:

• rosetta_turn drives one conversation turn end-to-end: idempotent conversation create, turn persist, and a flow-engine decision about what should happen next (retrieve context, ask a clarifying question, complete). Sellers rehearsing an architecture story, implementers asking "how do I…", practitioners exploring — all land here, and the persona classifier scores who it is talking to.
• rosetta_query is stateless retrieval against canon + twin: hybrid vector-and-graph search (reciprocal-rank-fusion merged) returning ranked context patterns with their governing ADRs, semantic entities, and vocabulary inlined. This is the compass and the map — and the Geiger counter: because anti-patterns and governing decisions ride along with every recommendation, a question that embeds an anti-pattern gets caught, not answered.
• rosetta_recall_engagement_memory searches the engagement's own accumulated decisions, artifacts, and known gaps through dedicated vector indexes — the twin as memory, not just model.
• The Engagement Canvas composes one model from live graph state — lifecycle stage, use-case scores, capability heatmap, risk register, readiness — and renders it three ways: JSON for dashboards, Slack-canvas markdown for the channel where the account team actually lives, and an embedded React SPA served by the API server itself.
• The rehearsal lane fills gaps without corrupting the record: the engagement-rehearsal plugin role-plays six personas (seller, implementer, practitioner, exec sponsor, economic buyer, customer admin) through live rosetta_turn conversations against the twin's open-gap inventory. It is read-only by contract — it proposes closures in a review-only document; every emitted value is stamped provenance: simulated with a run id. The operator applies what survives review; nothing simulated can slip in unlabeled.

Notice the design stance across all five: the agent surface is wide for reading and narrow for writing. That stance is enforced one layer down, which is stage 6's subject.

Verify: rosetta-mcp-server/config/mcp/composites.yaml (the five composites), rosetta-app-server/internal/{retrieval,flowengine,canvas,engagementmemory}/, util/plugins/engagement-rehearsal/references/output-contract.md.

Stage 6 — Decide and govern

Every consequential choice in an engagement — and in Rosetta's own development — is supposed to leave the same trail, and the machinery exists to make the honest path the easy one:

Capture. rosetta_record writes a DecisionTrace (idempotent on natural keys): what was decided, in what state, among which alternatives, on what evidence. Agents are first-class authors here — capturing decisions is exactly what they are good at.

The three gates. A DecisionTrace does not become policy by existing. Gate 1 scores completeness and coherence. Gate 2 groups traces into a PromotionCandidate and evaluates volume, coverage, and consensus. Gate 3 is a GovernanceReview — approve, reject, or request revision — and only approval mints an accepted ADR. The rule that gives the ladder its teeth: an ADR is never authored directly as "Proposed" — it is always promoted from a ratified DecisionTrace. Every prefix series in the constellation (platform, app-server, plugins, cross-repo) runs the same discipline.

The two lanes on every twin node. Since metamodel v1.10.0, every twin node carries two orthogonal axes: provenance (confirmed | simulated — the forensic boundary) and reviewStatus (draft → agent-authored → human-ratified | rejected — the authorship ladder, with terminal states and a one-way state machine). Agent output is agent-authored by default — default-deny, never silently trusted.

The human gate is structural, not procedural. Ratification — twin:ratify / twin:reject — is a server act that flips both axes (ratify promotes simulated → confirmed and removes the purge handle; reject keeps the audit trail), and it is excluded from the agent surface three separate ways: the MCP tool policy denies the twin-ratification tag and the two operationIds; the write-safety contract has no confirm-before workaround because the verb simply is not there; and the console's ratify routes refuse API-key principals outright — only a session- authenticated human in the review queue can perform the act, and reviewedBy is always a human identity. An agent cannot ratify its own work even by misbehaving.

The same write-safety contract governs everything else agents write: destructive operations (ADR rollback, governance-review rejections, twin deletes/replaces, client unlinks) require explicit confirmation; simulated payloads must route through the rehearsal endpoint — stripping simulation markers to reach the forensic lane is named in the contract as misrepresentation; and the MCP surface is the only sanctioned write path — raw API or Cypher is never an agent action.

Verify: metamodel §8 (three-gate) and §0.6–0.7 (lanes and state machine); rosetta-mcp-server/config/mcp/tool-policy.yaml (denied: twin-ratification, ratifyEngagementTwin, rejectEngagementTwin); util/plugins/rosetta-agent/core/write-safety.md; rosetta-app-server/internal/handlers/engagement_twin_ratify.go.

Stage 7 — Render the deliverables

Nothing so far has produced a document a customer signs. That is deliberate: in Rosetta, documents are projections of graph state, compiled on demand — never the sovereign artifact (a constellation invariant: the graph is canonical; a divergent document is a bug, and the cure is re-rendering, not hand-editing).

The engagement-codex plugin renders the three-document baton pass — one document per pair of hands in the delivery relay:

• The Solution Thesis (for the seller — the AE as much as the SE) renders in four tones from the same graph state: audit (the internal diagnostic, byte-stable, with the full «TBD» gap inventory), seller, leadership (opens with the decision, not the plumbing), and customer — which hard-fails on gaps: it will refuse to render a customer-facing document over unconfirmed content, keying on provenance == confirmed, not on non-emptiness. For NTO, the leadership render's verdict is "conditionally ready for a bounded proof-of-value; not for production activation until the named gaps close" — with an 11-dimension scorecard behind it that says Not Met out loud where the evidence is thin.
• The Statement of Work (for the contracting seller) renders in procurement and partner tones with three-class provenance on every section: inherited from the thesis, derived from graph state, or operator-authored — and the negotiated commercial sections are preserved verbatim across re-renders, so supersession never destroys negotiated terms. Every deliverable row must trace to a stated outcome and carry an objective acceptance check.
• The Spec Manifest (for the delivery team, human and agent) has no tone parameter — there is one delivery truth. Its nine sections compile preferentially through the engagement-scoped server compile (rosetta_compile_spec_manifest) reading the delivery spine as graph data; every epic, sprint, and work packet must carry its plain-English purpose, and a missing purpose is a hard failure, not a placeholder. For NTO: one wave, four epics, four sprints, fourteen work packets, RFC-2119 commitments with acceptance evidence attached.

The thesis's reservations, the SOW's §11, and the manifest's reconciliation section must agree — a clean cross-document diff is the proof that the seller → contract → delivery handoff actually closed, rather than losing a round of fidelity at each baton pass.

Verify: util/plugins/engagement-codex/skills/{solution-thesis-render,sow-render, spec-manifest-render}/SKILL.md; rosetta-app-server/internal/specmanifest/; the NTO artifacts quoted on the public tour page.

Stage 8 — Deliver, measure, and close the loop

The Spec Manifest is the delivery team's working document: work packets carry status, gate alignment (Foundation Ready → Capability Ready → Activation Ready → POV Complete), explicit dependency ordering (acyclic, enforced), and a context bundle — so each packet compiles at dispatch into a governed working environment for whoever picks it up, human or agent. This is the second stage of the two-stage compilation the platform is named for: the twin compiled into the manifest ahead of time; each work packet compiled fresh at dispatch.

Then Rosetta does the thing that most distinguishes it as an engineering organization: it measures itself and feeds the measurements back through its own governance. Every significant run — an archaeology lap, a codex render cycle, a bake-off — is ledgered in the evidence archive with a pinned toolchain manifest (platform, server, MCP, metamodel, plugin, and rubric versions), locked inputs (hash-pinned; changing an input means a new run, never an edit), scores against a versioned quality rubric with three scoring tiers (mechanical, model-judged, human), and a retrospective. The pattern has teeth in practice: one lap's retrospective produced twelve findings that became ratified decisions and shipped as a coordinated remediation release across three repos; a controlled vanilla-vs-Rosetta bake-off produced the platform's most important known limitation — twins transmit blind spots with authority (a medium-confidence claim hardened into flat fact on its way through the twin) — which is now driving an open cross-repo decision about fact-level bitemporality.

And the loop closes where it began: PromotionCandidates identified during the engagement graduate, through the same three gates, into the rosetta-core canon — new patterns, refined guardrails, another ADR. A separate compiler (d360-distiller) even distills the canon into task-level builder skills for practitioners who will never see a graph. The next engagement inherits all of it. The canon gets better because the engagement happened — which is the entire economic argument for the platform, made structural.

Verify: delivery-spine schema (db/schema/42-45, metamodel §0.5); the evidence archive's charter README and runs/run-001-nto-07-t8/manifest.json; rosetta-meta/eval/codex-quality-rubric.md; DT-RX-033 (the bitemporality response to the bake-off finding).

---

What the journey tells an assessor

Eight observations an architect should carry out of this chapter into the rest of the report:

1. The graph is genuinely the center. Every stage reads or writes graph state; every document is a projection; the one place that discipline is relaxed (operator- authored SOW commercial terms) is explicitly fenced and preserved.
2. Provenance is load-bearing, not decorative. The customer-tone hard-fail, the simulated lane, and the structural ratification gate all consume provenance to change behavior.
3. The write path narrows as consequence rises. Read: 43 tools. Write: fewer, idempotent, confirm-gated. Ratify: humans only, enforced in three independent layers.
4. Contracts are versioned and their history is honest — one breaking change in the REST contract's life, ratified in advance, with the skew tracked openly.
5. The system is self-applied. Rosetta's own development runs on its own twin, manifests, DTs, and ADRs — the strongest available evidence that the machinery is usable.
6. Humans hold exactly the right points: intake review, governance gates, ratification, commercial terms, and production migration.
7. The feedback loop is institutional, not aspirational — ledgered runs, versioned rubrics, retro findings that demonstrably shipped as remediation releases.
8. The known limitations are documented by the system itself — which is precisely what you want to find in a governed platform's evidence base.

Next: Chapter 2 — the domain model explains the graph this journey ran on; Chapter 6 — governance deepens stage 6; Chapter 10 — evaluation weighs what you just read.