@open-domain-specification/skill 0.1.11 → 0.3.0

package/skill/references/dsl-api.md

@@ -17,11 +17,11 @@ independently of the name.
 | `Subdomain` | `addBoundedcontext(name, { description, bigBallOfMud?, team? })` | a context serving this subdomain |
 | `BoundedContext` | `serves(subdomain)` | adds a served subdomain |
 | `BoundedContext` | `ownedBy(team)` | sets the owning team |
-| `BoundedContext` | `upstreamOf(other, { type?, upstreamRoles?, downstreamRoles?, description? })` | directed relationship, this side upstream; `type` defaults to `"upstream-downstream"`, or `"customer-supplier"` |
+| `BoundedContext` | `upstreamOf(other, { type?, upstreamRoles?, downstreamRoles?, description?, comments?, disposition? })` | directed relationship, this side upstream; `type` defaults to `"upstream-downstream"`, or `"customer-supplier"` |
 | `BoundedContext` | `downstreamOf(other, options)` | the same, this side downstream |
-| `BoundedContext` | `partnerOf(other, description?)` | partnership |
-| `BoundedContext` | `sharesKernelWith(other, description?)` | shared kernel |
-| `BoundedContext` | `separateWaysFrom(other, description?)` | separate ways |
+| `BoundedContext` | `partnerOf(other, { description?, comments?, disposition? })` | partnership |
+| `BoundedContext` | `sharesKernelWith(other, options)` | shared kernel |
+| `BoundedContext` | `separateWaysFrom(other, options)` | separate ways |
 | `BoundedContext` | `addAggregate(name, { description })` | an aggregate |
 | `BoundedContext` | `addService(name, { type, description })` | a service; `type` is `"application" \| "domain"` |
 | `BoundedContext` | `addPolicy(name, { description })` | a policy; chain `.on(...events).then(...operations)` |
@@ -31,8 +31,8 @@ independently of the name.
 | `Aggregate` | `addEntity(name, { description, root? })` | an entity |
 | `Aggregate` | `addValueObject(name, { description })` | a value object |
 | `Aggregate` | `addInvariant(name, { description })` | an invariant; chain `.constrains(...entities, valueObjects or attributes)` |
-| `Aggregate`, `Service` | `provides(name, { type, description, pattern?, internal?, schema? })` | a consumable; `type` is `"event" \| "operation"`, `pattern` is `"open-host-service" \| "published-language"` |
-| `Aggregate`, `Service` | `consumes(consumable, { pattern? })` | a consumption; `pattern` is `"conformist" \| "anti-corruption-layer"` |
+| `Aggregate`, `Service` | `provides(name, { type, description, pattern?, internal?, schema?, comments?, disposition? })` | a consumable; `type` is `"event" \| "operation"`, `pattern` is `"open-host-service" \| "published-language"` |
+| `Aggregate`, `Service` | `consumes(consumable, { pattern?, comments?, disposition? })` | a consumption; `pattern` is `"conformist" \| "anti-corruption-layer"` |
 | `Consumable` | `raises(...events)` | the events an operation raises |
 | `Entity`, `ValueObject`, `DataSchema` | `addAttribute(name, { type, description?, identity?, valueobject? })` | an attribute; `type` is free text |
 | `Entity`, `ValueObject` | `uses(target, label, cardinality?)` | a `uses` relation |
@@ -41,5 +41,13 @@ independently of the name.
 | `Entity`, `ValueObject` | `addRelation(target, { relation, label?, cardinality? })` | any relation explicitly |
 | `Entity` | `.attributes.get("name")` | look an attribute up, e.g. to constrain it |
 
+Every relationship, consumable and consumption also takes the evidence pair from
+RFC-002: `comments` is a list of `{ text, link? }`, where a link is
+`{ kind, url, label? }` and `kind` is
+`"code" | "contract" | "adr" | "runbook" | "dashboard"`; `disposition` is
+`"by-design" | "tolerated" | "refactor"` and defaults to `by-design`, which is never
+written to JSON. Read one back with `dispositionOf(element)`, and list the intents
+nobody has documented with `intentsWithoutComments(workspace)`.
+
 `cardinality` is `"1" | "0..1" | "*" | "1..*"`. Chainable methods (`raises`, `on`, `then`,
 `constrains`, `embody`, `serves`, `ownedBy`) return their receiver.

package/skill/references/interview-playbook.md

@@ -61,6 +61,7 @@ job is to get the model out of their head without making them learn the vocabula
 - "Does the upstream side publish a documented API, or a documented message format?" →
   `open-host-service` / `published-language`. Goes on `upstreamRoles` and on each exposed
   consumable's `pattern`.
+- Then the two evidence questions (see below), once for the relationship you just recorded.
 
 ## Phase E: inside one context (produces Aggregates, Entities, Value Objects, Invariants, Glossary)
 
@@ -100,9 +101,39 @@ Repeat for each context the user wants detailed. Ask which one to start with.
   with a downstream `pattern`.
 - Close: "Which of the words we used should I define, and does each map to one of the things
   we modelled?" → glossary terms with `embodiedBy`.
+- Ask the two evidence questions (see below) for each consumable or consumption that came out
+  of this phase with a `pattern` on it.
 
 ## Phase G: validate and reflect
 
 Run validation. Explain each diagnostic in one plain sentence, propose the fix, and ask before
 applying fixes for warnings. Then summarise what changed, in the user's words, and ask what to
 model next.
+
+## The two evidence questions
+
+Every strategic intent — a relationship, a consumable that leaves its context, a consumption —
+gets exactly these two, and only when it is new:
+
+- "Is that how you want it, or is it something you are living with?" → `disposition`. "How we
+  want it" is `by-design`, which is the default and is never written down. "Living with it, and
+  nobody is going to change it" is `tolerated`. "It should not stay like that" is `refactor`;
+  follow up with "what should it become?" and put the answer in the comment.
+- "Where does that live — a file, a repo, an API doc, a decision record?" → the first `comment`,
+  with its `link`. Take a path or a URL, whichever they give; `kind` is `code`, `contract`,
+  `adr`, `runbook` or `dashboard`. If they have nothing to point at, still record what they
+  said as a comment with no link.
+
+Rules for asking them:
+
+- Once per intent, never per role. A relationship with an `open-host-service` upstream role and
+  an `anti-corruption-layer` downstream role is still one relationship and gets one pair of
+  questions, not two.
+- Never for an internal consumable. It does not cross a boundary, so there is no strategic
+  claim to back up.
+- Never for an intent that already carries comments. Read first, ask second, as everywhere else.
+- Do not ask them before the intent itself is settled; they are the follow-up to "so I'd note a
+  ... right?", not a replacement for it.
+
+If the codebase is at hand, offer to answer the second question yourself instead of asking:
+that is reconciliation, and it is in `reconciliation.md`.

package/skill/references/model-reference.md

@@ -19,6 +19,7 @@ Represents a workspace in the Open Domain Specification (ODS).
 | `logoUrl` | string | no |  |
 | `name` | string | yes |  |
 | `odsVersion` | string | yes |  |
+| `options` | [WorkspaceOptions](#workspaceoptions) | no | Switches for behaviour that is not part of the model, such as opt-in rules. |
 | `primaryColor` | string | no |  |
 | `relationships` | array of [ContextRelationship](#contextrelationship) | yes |  |
 | `teams` | map of id to [Team](#team) | yes |  |
@@ -75,13 +76,38 @@ Represents a bounded context in the Open Domain Specification (ODS).
 
 No other fields are allowed.
 
+## Comment
+
+A short grounded statement about the real system behind a strategic intent, optionally backed by one link.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `link` | [CommentLink](#commentlink) | no |  |
+| `text` | string | yes |  |
+
+No other fields are allowed.
+
+## CommentLink
+
+Where the evidence for a comment lives: the code, the contract, the decision record, the runbook or the dashboard.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `kind` | "adr" | "code" | "contract" | "dashboard" | "runbook" | yes |  |
+| `label` | string | no | What to show instead of the raw URL. |
+| `url` | string | yes |  |
+
+No other fields are allowed.
+
 ## Consumable
 
 Represents a consumable in the Open Domain Specification (ODS).
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
+| `comments` | array of [Comment](#comment) | no | Grounded statements about the real system behind this consumable. |
 | `description` | string | yes |  |
+| `disposition` | "by-design" | "refactor" | "tolerated" | no | What the architecture thinks of this consumable. Absent means `by-design`. |
 | `internal` | boolean | no | True when the consumable stays inside its context: an event only local policies react to, or an operation only local callers issue. Internal consumables may not be consumed from another context. |
 | `name` | string | yes |  |
 | `pattern` | "open-host-service" | "published-language" | no | The upstream role this consumable is offered under. Absent on internal consumables. |
@@ -97,7 +123,9 @@ Represents a consumption in the Open Domain Specification (ODS).
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
+| `comments` | array of [Comment](#comment) | no | Grounded statements about the real system behind this consumption. |
 | `consumable` | `{ "$ref": string }` | yes |  |
+| `disposition` | "by-design" | "refactor" | "tolerated" | no | What the architecture thinks of this consumption. Absent means `by-design`. |
 | `pattern` | "anti-corruption-layer" | "conformist" | no | The downstream role the consumer adopts for this consumable. |
 
 No other fields are allowed.
@@ -126,7 +154,9 @@ An upstream/downstream relationship between two bounded contexts.
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
+| `comments` | array of [Comment](#comment) | no | Grounded statements about the real system behind this relationship. |
 | `description` | string | no |  |
+| `disposition` | "by-design" | "refactor" | "tolerated" | no | What the architecture thinks of this relationship. Absent means `by-design`. |
 | `downstream` | `{ "$ref": string }` | yes |  |
 | `downstreamRoles` | array of "anti-corruption-layer" | "conformist" | yes |  |
 | `type` | "customer-supplier" | "upstream-downstream" | yes |  |
@@ -210,6 +240,16 @@ A reaction: when these events happen, issue these commands.
 
 No other fields are allowed.
 
+## RuleOptions
+
+Opt-in validation rules. A rule listed here is off unless the workspace turns it on.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `commentsRequired` | boolean | no | Warn on every context relationship that carries no comments. Off by default. |
+
+No other fields are allowed.
+
 ## Service
 
 Represents a service in the Open Domain Specification (ODS).
@@ -242,7 +282,9 @@ A relationship between two bounded contexts with no upstream or downstream side.
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
+| `comments` | array of [Comment](#comment) | no | Grounded statements about the real system behind this relationship. |
 | `description` | string | no |  |
+| `disposition` | "by-design" | "refactor" | "tolerated" | no | What the architecture thinks of this relationship. Absent means `by-design`. |
 | `participants` | array of unknown | yes |  |
 | `type` | "partnership" | "separate-ways" | "shared-kernel" | yes |  |
 
@@ -273,6 +315,16 @@ Represents a value object in the Open Domain Specification (ODS).
 
 No other fields are allowed.
 
+## WorkspaceOptions
+
+Per-workspace switches for behaviour that is not part of the model itself.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `rules` | [RuleOptions](#ruleoptions) | no |  |
+
+No other fields are allowed.
+
 ## Ref grammar
 
 Every cross-link is an object `{ "$ref": "<path>" }`. Paths are JSON pointers into the workspace, built from the ids that key each collection:

package/skill/references/reconciliation.md

@@ -0,0 +1,184 @@
+# Reconciliation
+
+A model is a claim about a real system. Reconciliation is checking the claim: for each strategic
+intent, go and look in the repository for the evidence behind it, then write down what is
+actually there. The result is `comments` on the intent — grounded statements, each backed by a
+link — and, where the code disagrees with the model, a proposed `disposition`.
+
+Strategic intents are the three things evidence hangs off: a **relationship** between two
+contexts, a **consumable** that crosses a boundary, and a **consumption** of one. Internal
+consumables never cross a boundary, so they are not strategic and are never reconciled.
+
+## When to reconcile
+
+- The user asks: "check the model against the code", "is the ACL actually there", "reconcile".
+- After the interview, for the intents just created, if the codebase is at hand.
+- On opening a workspace whose intents carry no comments: offer it, once, and let the user
+  choose. Do not start a reconciliation nobody asked for.
+
+The worklist is every intent with no comments — the "No comments" list on the health report,
+and `intentsWithoutComments(workspace)` in the DSL. Work it in the order the report shows and
+stop when the user says enough.
+
+## What to look for, per pattern
+
+The pattern names the thing that should exist. Search for that thing, in the code of the side
+that owns it. Terms below are starting points, not a script: read the repository's own
+vocabulary first and search in it.
+
+| Pattern | Owned by | What should exist | Where to look |
+|---|---|---|---|
+| `anti-corruption-layer` | downstream | An adapter or translator on the downstream side: a mapper between the upstream payload and the downstream model, so no upstream type reaches the domain | The downstream context's code. Names like `adapter`, `translator`, `mapper`, `acl`, `client`, `gateway`; a function taking an upstream DTO and returning a domain type |
+| `conformist` | downstream | Direct use of the upstream types: the upstream's own classes, DTOs or generated client, imported into the downstream domain, with no mapping | Imports in the downstream context from the upstream package, module or generated client |
+| `open-host-service` | upstream | A published contract: an OpenAPI, GraphQL, gRPC or AsyncAPI document that others build against, versioned and documented | The upstream context's repository root and its `docs/`, `api/`, `contracts/`, `proto/` folders; a published API reference |
+| `published-language` | upstream | A shared interchange format independent of either side: a JSON Schema, Protobuf, Avro or industry format the events are emitted in | A schema registry, a `schemas/` or `proto/` folder, a package holding only message definitions |
+| `shared-kernel` | both | A shared package, library or schema both sides depend on, small and jointly owned | A workspace package both contexts declare as a dependency; a shared database schema or migration folder |
+| `partnership` | both | Joint planning and release: one pipeline, one release cadence, or features that land in both at once | Release workflows, a shared changelog, commits that touch both sides together |
+| `customer-supplier` | upstream | The downstream's requirements visible on the upstream side: contract tests, a consumer-driven test suite, downstream tickets in the upstream backlog | Contract test folders (`pact`, `contract`, `consumer`), the upstream's issue references |
+| `upstream-downstream` | downstream | A directed dependency, and nothing on the upstream side that plans for the downstream | The downstream's dependency on the upstream, and the absence of the customer-supplier evidence above |
+| `separate-ways` | neither | Nothing: no dependency, no shared package, no calls between the two | Search for the dependency and report that there is none. Finding one is the interesting result |
+
+## The three outcomes
+
+Every intent you look at ends in exactly one of these. Write a comment in all three cases; a
+reconciliation that says nothing is worse than one that says "I looked and found nothing".
+
+**It is there.** Write one comment saying what you found and where, with a link to it. Leave the
+disposition alone; an absent disposition already means `by-design`.
+
+**It is not what the model says.** Write one comment saying what is there instead, with a link,
+and propose a disposition:
+
+- `tolerated` — the code disagrees with the pattern, the reason is understood, and nobody plans
+  to change it. A compromise someone is living with.
+- `refactor` — the intent should be removed or replaced, and someone means to do it. Say in the
+  comment what it should become.
+
+Propose, never apply. The disposition is the author's judgement about their own architecture:
+show the comment and the disposition you would set, say why in one sentence, and wait.
+
+**You cannot tell.** Write one comment naming what you searched for and where, and propose no
+disposition. Then ask the user where it lives. "No adapter or translator found in the Sales
+context; searched for a mapper between the Catalog pet payload and Sales' own types" is useful
+evidence. A guess is not.
+
+## Writing the comment
+
+A comment is `{ text, link? }`. The text is one or two sentences, in the present tense, saying
+what is in the system — not what you did, and not what the pattern means in general. The link is
+`{ kind, url, label? }` with `kind` one of `code`, `contract`, `adr`, `runbook`, `dashboard`.
+
+- Cite what you actually opened. A path or a URL, never a guess at where a file probably is.
+- One statement per comment. Two findings are two comments; the report lists them separately.
+- `label` is what a reader should see instead of the URL: the repo-relative path, the endpoint,
+  the ADR's title.
+- Use the repository's own words for its own parts, and the model's words for the model's.
+- Never delete or rewrite a comment an author wrote. Add yours next to it.
+- A comment with no link is still evidence when there is nothing to link to; a link you cannot
+  justify is not.
+
+In the DSL, `comments` and `disposition` go in the options of `upstreamOf`, `downstreamOf`,
+`partnerOf`, `sharesKernelWith`, `separateWaysFrom`, `provides` and `consumes`:
+
+```ts
+salesBC.downstreamOf(catalogBC, {
+	type: "customer-supplier",
+	upstreamRoles: ["open-host-service"],
+	downstreamRoles: ["anti-corruption-layer"],
+	description: "Sales needs pet availability; Catalog commits to the summary contract",
+	disposition: "tolerated",
+	comments: [
+		{
+			text: "Sales calls the Catalog summary endpoint directly from its order service; there is no translator, so the Catalog pet payload reaches the Sales domain unchanged.",
+			link: {
+				kind: "code",
+				url: "https://github.com/example/petstore/blob/main/sales/src/orders/service.ts",
+				label: "sales/src/orders/service.ts",
+			},
+		},
+	],
+});
+```
+
+In JSON, both are optional fields on the relationship, the consumable and the consumption:
+
+```json
+{
+  "relationships": [
+    {
+      "upstream": { "$ref": "#/boundedcontexts/catalog" },
+      "downstream": { "$ref": "#/boundedcontexts/sales" },
+      "type": "customer-supplier",
+      "upstreamRoles": ["open-host-service"],
+      "downstreamRoles": ["anti-corruption-layer"],
+      "description": "Sales needs pet availability; Catalog commits to the summary contract",
+      "disposition": "tolerated",
+      "comments": [
+        {
+          "text": "Sales calls the Catalog summary endpoint directly from its order service; there is no translator, so the Catalog pet payload reaches the Sales domain unchanged.",
+          "link": {
+            "kind": "code",
+            "url": "https://github.com/example/petstore/blob/main/sales/src/orders/service.ts",
+            "label": "sales/src/orders/service.ts"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+A consumable carries the same two fields beside its `pattern`, and so does a consumption:
+
+```json
+"provides": {
+  "get_pet_summary": {
+    "name": "GetPetSummary",
+    "description": "GET /pets/{id}/summary",
+    "type": "operation",
+    "pattern": "open-host-service",
+    "comments": [
+      {
+        "text": "The summary endpoint is in the published Catalog OpenAPI document and is versioned with the rest of the API.",
+        "link": {
+          "kind": "contract",
+          "url": "https://github.com/example/petstore/blob/main/catalog/openapi.yaml",
+          "label": "GET /pets/{id}/summary"
+        }
+      }
+    ]
+  }
+}
+```
+
+```json
+"consumes": [
+  {
+    "consumable": {
+      "$ref": "#/boundedcontexts/catalog/services/pet_app/provides/get_pet_summary"
+    },
+    "pattern": "anti-corruption-layer",
+    "disposition": "refactor",
+    "comments": [
+      {
+        "text": "No adapter or translator found in Sales; searched the order service and its client folder for a mapper between the Catalog pet payload and the Sales order model.",
+        "link": {
+          "kind": "code",
+          "url": "https://github.com/example/petstore/tree/main/sales/src/orders",
+          "label": "sales/src/orders"
+        }
+      }
+    ]
+  }
+]
+```
+
+`by-design` is the meaning of an absent `disposition` and is never written to the file. Writing
+`"disposition": "by-design"` is the same as leaving it out; leave it out.
+
+## Reporting back
+
+When the pass is done, summarise in the user's words, not in DDD words: how many intents you
+looked at, how many now have evidence, which ones you would mark `tolerated` or `refactor` and
+why, and which ones you could not resolve and need them to answer. Then validate: the health
+report and the opt-in `comments-required` rule both read what you just wrote.

package/skill/references/strategic-relationships.md

@@ -0,0 +1,98 @@
+<!-- Generated by packages/skill/scripts/generate.mts from @open-domain-specification/core (PATTERNS); do not edit. -->
+
+# Strategic relationships
+
+What each strategic pattern means. Explain one to the user in these words: the diagram legend, the hover summaries and the generated documentation all read the same table, so your explanation and what they are looking at agree. The value in the left column is what goes in the model.
+
+## Relationship types
+
+The `type` of a context relationship. Exactly one per relationship.
+
+### `upstream-downstream` — Upstream/Downstream (U/D)
+
+One context depends on another; the upstream does not plan around the downstream.
+
+A directed dependency with no customer commitment: the upstream evolves on its own schedule and the downstream adapts through its roles.
+
+- Upstream keeps full autonomy
+- Downstream carries the integration risk
+
+### `customer-supplier` — Customer/Supplier (C/S)
+
+Upstream plans for and prioritizes downstream requirements.
+
+An asymmetric relationship where downstream needs act as customer requirements and upstream delivery commitments factor in downstream deadlines.
+
+- Predictable alignment between collaborating teams
+- Upstream velocity can be constrained by downstream dependencies
+
+### `shared-kernel` — Shared Kernel (SK)
+
+A shared subset of domain model and code, co-owned by both teams.
+
+A strictly bounded shared library, schema, or database subset. Neither team alters the kernel without joint consultation and continuous test verification.
+
+- Prevents duplicate modeling and translation costs
+- High coordination friction; degrades autonomy if it grows beyond a small subset
+
+### `partnership` — Partnership (P)
+
+Mutual co-operation where teams coordinate development and releases.
+
+Two contexts succeed or fail together. Features spanning both are planned, co-designed, and released in synchronized cycles.
+
+- Tight strategic cohesion across organizational boundaries
+- Requires close communication and joint release cadences
+
+### `separate-ways` — Separate Ways (SW)
+
+A deliberate decision to forego integration and develop independently.
+
+Both contexts solve their requirements without technical links, accepting possible domain overlap to keep complete operational independence.
+
+- Maximum operational autonomy with no cross-team dependencies
+- Possible duplication of data and business logic
+
+## Upstream roles
+
+How the upstream side exposes what it provides: a relationship's `upstreamRoles`, and a consumable's `pattern`.
+
+### `open-host-service` — Open Host Service (OHS)
+
+A public, stable protocol or API provided by an upstream context.
+
+The upstream context commits to maintaining a standardized, backward-compatible interface so multiple downstream subsystems can integrate without bespoke integration logic.
+
+- Reduces coupling across multiple consumers
+- Increases upstream maintenance overhead and versioning obligations
+
+### `published-language` — Published Language (PL)
+
+A well-documented shared interchange format.
+
+An explicit schema standard (JSON Schema, Protobuf, an industry XML) that expresses domain operations and events independently of either context's internal representation.
+
+- Enables polyglot integrations and widespread consumption
+- Requires governance over schema evolution
+
+## Downstream roles
+
+How the downstream side protects itself: a relationship's `downstreamRoles`, and a consumption's `pattern`.
+
+### `anti-corruption-layer` — Anti-Corruption Layer (ACL)
+
+A translating boundary isolating a downstream model from external concepts.
+
+A translating mechanism (adapters, facades, mappers) that keeps foreign domain concepts, schema changes, or vendor anomalies from leaking into the downstream model.
+
+- Maximum isolation and autonomy for the downstream context
+- Cost of maintaining translation logic and data mappings
+
+### `conformist` — Conformist (CF)
+
+Downstream adopts the upstream domain model without translation.
+
+The downstream team accepts the upstream model as-is, dropping translation layers when the upstream model fits well or translation overhead is unjustified.
+
+- No translation and a simpler codebase
+- Exposed to breaking upstream schema changes

package/skill/references/translation-table.md

@@ -17,9 +17,9 @@ element lives in a workspace file; `DSL` is the core call that creates it.
 | "the old system", "legacy", "nobody understands its schema" | big ball of mud | `"bigBallOfMud": true` | `bigBallOfMud: true` |
 | "A depends on B", "A calls B", "A reads B's data" | upstream-downstream (B upstream) | `relationships[]` `type: "upstream-downstream"` | `a.downstreamOf(b, {...})` |
 | "they ask us before changing", "we're their customer" | customer-supplier | `type: "customer-supplier"` | `a.downstreamOf(b, {type: "customer-supplier", ...})` |
-| "both teams change it together", "we release together" | partnership | `type: "partnership"`, `participants` | `a.partnerOf(b)` |
-| "we share the same tables / library / code" | shared kernel | `type: "shared-kernel"` | `a.sharesKernelWith(b)` |
-| "we deliberately don't integrate" | separate ways | `type: "separate-ways"` | `a.separateWaysFrom(b, why)` |
+| "both teams change it together", "we release together" | partnership | `type: "partnership"`, `participants` | `a.partnerOf(b, {description})` |
+| "we share the same tables / library / code" | shared kernel | `type: "shared-kernel"` | `a.sharesKernelWith(b, {description})` |
+| "we deliberately don't integrate" | separate ways | `type: "separate-ways"` | `a.separateWaysFrom(b, {description: why})` |
 | "we use their API as-is", "we take whatever they send" | conformist | consumption `pattern: "conformist"`; relationship `downstreamRoles` | `agg.consumes(c, {pattern: "conformist"})` |
 | "we copy and reshape their data", "we wrap their API" | anti-corruption layer | `pattern: "anti-corruption-layer"` | `agg.consumes(c, {pattern: "anti-corruption-layer"})` |
 | "we expose a documented API", "there's a REST endpoint" | open host service | operation `pattern: "open-host-service"`; relationship `upstreamRoles` | `svc.provides(name, {type: "operation", pattern: "open-host-service"})` |

package/skill/references/validation-rules.md

@@ -75,3 +75,11 @@
 **Why it matters:** A context that serves no subdomain has no place in the problem-space view, so nobody can see which part of the business it exists for.
 
 **Usual fix:** Add the subdomain the context serves to its subdomains list.
+
+## `comments-required` (warning)
+
+**Requires:** Every context relationship carries at least one comment. Opt-in: set options.rules.commentsRequired on the workspace.
+
+**Why it matters:** A relationship is a claim about how two teams meet; without a note saying where that shows up in the real system, nobody can tell whether the map is still true.
+
+**Usual fix:** Add a comment to the relationship saying what backs it in the code, or turn options.rules.commentsRequired off while the evidence layer is still being written.