# engagement-authoring

The **engagement authoring-reference plugin** — the 7th sibling. It carries two
**reference skills** that teach an agent how to correctly hand-construct the two
engagement-scoped payloads against the `rosetta-app-server` API, before writing
them:

- **`engagement-creation`** — starting a new engagement
  (`POST /api/v1/engagements` / `rosetta_create_engagement`).
- **`twin-authoring`** — authoring the `twin.json` `TwinDocument`
  (`POST /api/v1/engagements/{uid}/twin:apply` / `rosetta_apply_engagement_twin`).

The two are ordered: **create the engagement first, then apply the twin into
it** (twin:apply 404s on a missing engagement).

**Which lane (0.2.0, platform E9-S1-WP2).** twin:apply takes engagement
content; canonical, engagement-less content goes to content:ingest
(`POST /api/v1/domains/{domainKey}/content:ingest`). `twin-authoring` § 9b
tells them apart and lists what has no lane yet. They are the only lanes: from
the DT-RX-036 switch (E9-S2-WP1; ADR-PL-024) nothing is authored in the platform
repo's `db/engagements/` or `db/seeds/`, and `make prod-migrate` is schema-only.
Before the DT-RX-036 switch
no plugin's ingestion target submits to a shared or production app-server,
and no one calls `rosetta_ingest_content` through the hosted connector to
commit.

**Edges and gate fields (0.2.1, platform E9-S1-WP17).** `twin-authoring` § 4.2
is the twin:apply edge allowlist, keyed by triple, with the four triples the
archaeology lane adds; an edge off the list and a gate-owned DecisionTrace
field (`gateStatus`, `completenessScore`, `coherenceScore`, `decisionPoint`)
are refused once the E9-S2 switch is on, and an unchanged echo of a twin read
still applies (app-server `twin-apply-archaeology-lane.md` Q-F-1, Q-L-1).

## What it is (and is NOT)

- **Reference, not doer.** Both skills are advisory knowledge. They author no
  files, call no write tools, and register no MCP server. The actual writes are
  the caller's — via `rosetta-agent`'s MCP surface (`rosetta_create_engagement`,
  `rosetta_apply_engagement_twin`) or a direct REST call.
- **Distilled mirrors of the app-server docs.** The authoritative sources are in
  `rosetta-app-server`: `docs/engagement-creation-guide.md`,
  `docs/twin-json-authoring-guide.md`, and the files they cite
  (`api/rosetta-v1.yaml`, `config/digital-twin/node-types.yaml`,
  `internal/digitaltwin/twin.go`, `internal/handlers/engagements.go`,
  `queries/v1/engagement_create.cypher`). When the API changes, the app-server
  docs move first; these skills are re-synced from them.
- **Companion to the generators and the doer.** `rosetta-archaeology` and
  `engagement-rehearsal` *generate* twin documents; `rosetta-agent`'s
  `engagement-lifecycle` skill *performs* the engagement create over MCP. This
  plugin is the shared **how-to-construct-it-correctly** reference for all of
  them and for hand-authors.

## Command → skill routing

Each command name equals the skill it drives (1:1 capability) — the house
naming rule:

| Command | Skill | Covers |
|---|---|---|
| `/engagement-authoring:engagement-creation` | `engagement-creation` | The create dual-write, required `clientUid`, the `engagementUid`/`engagementId` naming trap, account/authorization defaults, the auto creator `lead` grant, `status` vs derived stage, the 201/403/409/422 map |
| `/engagement-authoring:twin-authoring` | `twin-authoring` | The `TwinDocument`: 11 writable labels, inheritable-vs-non-inheritable identity, five-field identity, natural keys, required props + closed enums, edge-endpoint resolution incl. `REFINES_PATTERN` MATCH-only, DecisionTrace inline children, `baseRevision`, the 422/409 failure codes |

Both skills also auto-load on their `description` triggers (creating an
engagement / authoring a twin.json) without an explicit command.

## Posture

- **Read/reference-only.** No write tool is invoked from either skill; each says
  so explicitly. No `mcpServers` block — the plugin needs no server (it only
  documents the caller's write calls).
- **Self-contained.** The skill bodies embed the full guidance so the plugin is
  useful in a Cowork/Claude session with no rosetta checkout present.

## Governance

Authorized by `dt-pa-007`
(**RATIFIED** 2026-09-25 by Vernon Keenan), promoted to
**ADR-PA-013** (Accepted 2026-09-27). This is
a plugin-author decision (a reference consumer of the already-shipped app-server
API surface, no cross-repo contract change) → the ADR-PA lane, not ADR-RX.