Harden pair workflow state and publication guards

.agents/skills/README.md

@@ -12,9 +12,12 @@ routing source of truth.
 - `component-engineer`: class-based Compose UI components across `core`,
   `proto`, and `client` — the component model, input components, message
   forms, and server-connected components.
+- `model-engineer`: published model Protobuf declarations and Kotlin model
+  extensions in `proto-values`, including schema evolution and package and
+  file organization.
 - `codegen-engineer`: ProtoData codegen plugins, the codegen runtime,
-  generated `MessageField`/`MessageOneof`/`MessageDef` contracts, and
-  Protobuf declarations in `proto-values`.
+  generated `MessageField`/`MessageOneof`/`MessageDef` contracts,
+  plugin-internal Protobuf declarations, and codegen correctness tests.
 - `build-engineer`: root and `codegen/plugins` Gradle builds, `buildSrc`
   dependency coordinates, publishing wiring, version policy, and generated
   report regeneration.
@@ -23,8 +26,8 @@ routing source of truth.
   secret exposure review.
 - `ci-engineer`: GitHub Actions workflow authoring and review for build,
   guard, validation, and publishing pipelines.
-- `code-reviewer`: implementation review for component, codegen, and build
-  changes.
+- `code-reviewer`: implementation review for component, model, codegen, and
+  build changes.
 - `tester`: what to cover and how to verify it across all modules,
   including codegen correctness tests.
 - `kotlin-jvm-tester`: how a test suite is written — JUnit Jupiter

.agents/skills/code-reviewer/SKILL.md

@@ -3,8 +3,8 @@ name: code-reviewer
 description: >
   Reviews Chords implementation changes for correctness, regressions, public
   API breaks, missing tests, and cross-module contract breaks. Use to review
-  component, codegen, or build diffs. Read-only unless explicitly asked to run
-  checks.
+  component, model, codegen, or build diffs. Read-only unless explicitly asked
+  to run checks.
 ---
 
 # Code Review
@@ -29,9 +29,10 @@ unless the task asks for it directly. To judge CI status, read existing results
    behavior, and contract impact require context beyond the diff hunk.
 3. **Trace the owning flow.** For component changes, follow the
    `Component`/`InputComponent` lifecycle (`beforeComposeContent`, `content`,
-   `Props` configuration) and the state properties involved. For codegen
-   changes, follow the generator, the runtime contract, and `codegen/tests`
-   together.
+   `Props` configuration) and the state properties involved. For model
+   changes, follow the Protobuf declarations, Kotlin extensions, generated
+   accessors, and consumers together. For codegen changes, follow the
+   generator, the runtime contract, and `codegen/tests` together.
 4. **Verify claims against source.** Confirm Gradle task names, module paths,
    generated API shapes, and toolchain constraints against the relevant build
    file, README, or workflow.
@@ -77,8 +78,20 @@ duplicate its steps.
   component subclasses consume them. Kotlin explicit API mode applies.
 - Cross-module contract breaks: `core`/`proto`/`client` layering, the
   generated `MessageField`/`MessageOneof`/`MessageDef` contract between
-  `codegen/plugins` and `codegen/runtime`, and Protobuf compatibility in
-  `proto-values`.
+  `codegen/plugins` and `codegen/runtime`, and both source API and Protobuf wire
+  compatibility in `proto-values`.
+- Protobuf model changes: apply `.agents/skills/model-engineer/SKILL.md` to
+  published model declarations and extensions under `proto-values`. Check
+  changed, deleted, or renumbered field tags and confirm retired numbers and
+  names are reserved. Inspect every field type, singular/repeated cardinality,
+  and `oneof` membership change even when its tag is unchanged. Do not treat
+  rebuilt consumers or passing tests as proof that old wire data remains
+  compatible. Inspect message renames and Protobuf package changes, including
+  package changes required by file relocation. Where `(type_url_prefix)` is
+  set, assess changed type URLs against existing `Any` values and Spine
+  type registry resolution. Confirm that every intentional incompatibility is
+  explicitly in scope and that the change reports its external-consumer and
+  data impact.
 - Kotlin-language and toolchain violations: apply
   `.agents/skills/kotlin-engineer/SKILL.md` to the changed Kotlin and report
   what its rules flag. Read it rather than reviewing from memory — several

.agents/skills/code-reviewer/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Code Reviewer"
-  short_description: "Review Chords component, codegen, or build changes"
+  short_description: "Review Chords component, model, codegen, or build changes"
   default_prompt: >
     Use $code-reviewer after reading AGENTS.md, README.md, .agents/project.md,
     and the nearest README for the area being changed to review a scoped

.agents/skills/codegen-engineer/SKILL.md

@@ -3,27 +3,30 @@ name: codegen-engineer
 description: >
   Chords code generation policy. Use for the ProtoData codegen plugins project,
   the codegen runtime library, generated MessageField/MessageOneof/MessageDef
-  contracts, codegen correctness tests, and Protobuf declarations with Kotlin
-  extensions in proto-values.
+  contracts, plugin-internal Protobuf declarations, codegen correctness tests,
+  and codegen Gradle wiring.
 ---
 
 # Codegen Engineering
 
 ## When to Use
 
-Use this skill for code generation and Protobuf model work:
+Use this skill for code generation work:
 
 - ProtoData plugins under `codegen/plugins/` (a separate Gradle project).
+- Plugin-internal Protobuf declarations under
+  `codegen/plugins/codegen-plugins/src/main/proto/**`.
 - The codegen runtime under `codegen/runtime/` (Gradle path `:runtime`):
   `MessageField`, `MessageOneof`, `MessageDef`, and related runtime types.
 - Codegen correctness tests under `codegen/tests/` (Gradle path
   `:codegen-tests`).
-- Protobuf declarations and Kotlin extensions in `proto-values`.
 - The codegen wiring in the root build (`modulesWithChordsCodegen`,
   `publishCodegenPluginsToMavenLocal`, the `io.spine.chords` Gradle plugin
   configuration).
 
-For components that merely consume generated metadata, prefer
+For published model Protobuf declarations and Kotlin model extensions under
+`proto-values`, prefer `.agents/skills/model-engineer/SKILL.md`. For components
+that merely consume generated metadata, prefer
 `.agents/skills/component-engineer/SKILL.md`. For build-only concerns, use
 `.agents/skills/build-engineer/SKILL.md`.
 
@@ -37,10 +40,9 @@ For components that merely consume generated metadata, prefer
   external projects: changes to `MessageField`/`MessageOneof`/`MessageDef`
   shapes are public API changes on both the generator and runtime sides and
   must stay in sync.
-- For Protobuf schema changes in `proto-values`: never delete or renumber
-  existing fields, reserve retired field numbers and names, and keep package
-  names consistent with the existing `spine/chords/proto/value/**` structure
-  under `proto-values/src/main/proto/`.
+- Treat `.proto` files under `codegen/tests/src/test/proto/**` as generator
+  fixtures. Change them only to express a code-generation scenario; published
+  model declarations under `proto-values` belong to `model-engineer`.
 - Keep `codegen/plugins/src/main/resources/codegen-workspace` resources
   consistent with the build logic that copies `buildSrc` and wrapper files
   into them; that workspace is what the Chords Gradle plugin unpacks in

.agents/skills/codegen-engineer/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Codegen Engineer"
-  short_description: "Implement Chords code generation or Protobuf model changes"
+  short_description: "Implement Chords code generation changes"
   default_prompt: >
     Use $codegen-engineer after reading AGENTS.md, README.md,
     .agents/project.md, and codegen/plugins/README.md to implement a scoped

.agents/skills/component-engineer/SKILL.md

@@ -23,9 +23,11 @@ Use this skill for UI component and component-infrastructure work:
 - Server-connected components in `client`: command posting, entity
   subscriptions, and entity-backed components such as `EntityChooser`.
 
-For generated `MessageField`/`MessageOneof`/`MessageDef` contracts or Protobuf
-declarations, prefer `.agents/skills/codegen-engineer/SKILL.md`. For Gradle
-build logic, use `.agents/skills/build-engineer/SKILL.md`.
+For published model Protobuf declarations and Kotlin model extensions under
+`proto-values`, prefer `.agents/skills/model-engineer/SKILL.md`. For generated
+`MessageField`/`MessageOneof`/`MessageDef` contracts, prefer
+`.agents/skills/codegen-engineer/SKILL.md`. For Gradle build logic, use
+`.agents/skills/build-engineer/SKILL.md`.
 
 ## Policy
 

.agents/skills/engineer/SKILL.md

@@ -3,9 +3,9 @@ name: engineer
 description: >
   Routes Chords implementation work to the area-specific engineering skill and
   carries the design-restraint policy shared by all of them. Use for mixed
-  component/codegen/build changes or when the owning area is unclear; otherwise
-  prefer the narrowest specialist skill directly, and follow "Design Restraint"
-  below in either case.
+  component/model/codegen/build changes or when the owning area is unclear;
+  otherwise prefer the narrowest specialist skill directly, and follow
+  "Design Restraint" below in either case.
 ---
 
 # Engineering Router
@@ -20,11 +20,14 @@ the code being changed:
   components in `core`, `proto`, and `client`: the component model,
   application shell, input components, message forms, validation display, and
   server-connected components.
+- `.agents/skills/model-engineer/SKILL.md` for published model Protobuf
+  declarations and Kotlin model extensions under `proto-values`, including
+  schema evolution and package and file organization.
 - `.agents/skills/codegen-engineer/SKILL.md` for the `codegen/plugins`
   ProtoData project, the codegen runtime (`codegen/runtime`), codegen
-  correctness tests (`codegen/tests`), generated
-  `MessageField`/`MessageOneof`/`MessageDef` contracts, and Protobuf
-  declarations in `proto-values`.
+  correctness tests (`codegen/tests`), plugin-internal Protobuf declarations,
+  generated `MessageField`/`MessageOneof`/`MessageDef` contracts, and codegen
+  Gradle wiring.
 - `.agents/skills/build-engineer/SKILL.md` for root and `codegen/plugins`
   Gradle build logic, `buildSrc` dependency coordinates, publishing wiring,
   version policy, generated `pom.xml`/`dependencies.md` reports, and the

.agents/skills/kotlin-engineer/SKILL.md

@@ -27,8 +27,10 @@ Each of these owns its area; this skill stays out of them:
 - `.agents/skills/component-engineer/SKILL.md` — the component model,
   `mutableStateOf`-backed state, `PascalCase` composables, module layering,
   KDoc style, and the Compose 1.5.12 ceiling.
-- `.agents/skills/codegen-engineer/SKILL.md` — generated contracts and
-  Protobuf declarations.
+- `.agents/skills/model-engineer/SKILL.md` — published model Protobuf
+  declarations and Kotlin model extensions under `proto-values`.
+- `.agents/skills/codegen-engineer/SKILL.md` — ProtoData plugins and generated
+  runtime contracts.
 - `.agents/skills/build-engineer/SKILL.md` — Gradle Kotlin DSL, `buildSrc`
   coordinates, and publishing.
 - `.agents/skills/kotlin-jvm-tester/SKILL.md` — how a test suite is

.agents/skills/kotlin-jvm-tester/SKILL.md

@@ -28,9 +28,9 @@ restating:
   body is Kotlin, so its null-safety, coroutine scoping, and language
   ceiling obey the same rules as production code.
 - `.agents/skills/engineer/SKILL.md` — the router to the area-specific
-  engineering skill (`component-engineer`, `codegen-engineer`,
-  `build-engineer`, …). Use it to find the skill owning the code under
-  test when you need its API constraints.
+  engineering skill (`component-engineer`, `model-engineer`,
+  `codegen-engineer`, `build-engineer`, …). Use it to find the skill owning
+  the code under test when you need its API constraints.
 
 `AGENTS.md` remains authoritative for Git history, versioning, and
 verification policy.

.agents/skills/model-engineer/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: model-engineer
+description: >
+  Chords Protobuf model and schema policy. Use when adding, changing,
+  reviewing, or removing project-owned `.proto` declarations and Kotlin model
+  extensions located in `proto-values`, organizing Protobuf packages, imports,
+  and files, or evaluating schema-driven generated-accessor effects. Do not
+  use for ProtoData plugin, generator, or codegen-runtime implementation; use
+  `codegen-engineer` for those concerns.
+---
+
+# Model Engineering
+
+## Scope
+
+- Own published model Protobuf declarations under
+  `proto-values/src/main/proto/**`.
+- Own Kotlin extensions for project-owned and external Protobuf types under
+  `proto-values/src/main/kotlin/**`.
+- Keep schema declarations, Kotlin extensions, and schema-driven generated
+  accessors consistent.
+- Use `.agents/skills/codegen-engineer/SKILL.md` for ProtoData plugins,
+  including plugin-internal Protobuf declarations under
+  `codegen/plugins/codegen-plugins/src/main/proto/**`, and for generator
+  behavior, codegen-runtime contracts, and test Protobuf files that exist only
+  as generator fixtures under `codegen/tests/src/test/proto/**`.
+- Use `.agents/skills/component-engineer/SKILL.md` for UI components that
+  consume model types, and `.agents/skills/build-engineer/SKILL.md` for Gradle
+  wiring.
+- Apply `.agents/skills/kotlin-engineer/SKILL.md` to every Kotlin extension.
+
+## Policy
+
+- Treat `AGENTS.md` as authoritative. Prefer additive changes for published
+  APIs. Rely on Chords' experimental status only under the breaking-change
+  authorization below, and report the compatibility impact.
+- Add model declarations and make compatible edits as needed. Make an
+  incompatible change to an existing message, field, field type, cardinality,
+  `oneof` membership, or option only when the current task explicitly requires
+  the break or the user confirms it through the active workflow's prescribed
+  user-input channel. Do not preserve an obsolete declaration solely for
+  source compatibility when an intentional breaking change is in scope.
+- Treat source compatibility and Protobuf wire compatibility separately.
+  Recompiling in-repository consumers and passing tests can prove source usage
+  was updated, but cannot prove that previously serialized or transmitted data
+  still decodes correctly.
+- Evaluate every change to an existing field's type, singular/repeated
+  cardinality, or `oneof` membership, even when its tag stays unchanged.
+  Compare Protobuf wire types and value semantics; a shared tag or wire type
+  alone does not prove compatibility.
+- Evaluate message renames and Protobuf package changes, including a package
+  change required when relocating a file. With `(type_url_prefix)` set, either
+  change alters the fully qualified message name and type URL, which can break
+  existing `Any` values and Spine type registry resolution.
+- Never reuse a retired field number or name. When deleting a field, reserve
+  its old number and name in the owning message. When renumbering, reserve the
+  old number and reserve the old name if the change also retires it.
+  Renumbering remains wire-incompatible: old data keeps the old tag and does
+  not populate the field at its new number. Apply the breaking-change
+  authorization above and report any data or migration consequences.
+- Remember that `proto-values` is published and consumed externally even
+  during the experimental phase. Update all in-repository consumers and tests
+  for an incompatible source change, and separately evaluate existing wire
+  data and external consumers.
+- Keep published model schemas under
+  `proto-values/src/main/proto/spine/chords/proto/value/**`. Make each Protobuf
+  `package` match its directory relative to `proto-values/src/main/proto`, and
+  keep project-owned import paths aligned with the same structure. Never infer
+  the Protobuf package from `java_package`, which controls only generated JVM
+  classes. Before moving an existing file or changing its package, apply the
+  type-URL compatibility check and breaking-change authorization above.
+- Update neighboring Kotlin extensions when a declaration, field, or generated
+  accessor they expose changes.
+- Do not manually edit generated Protobuf or Chords outputs. Change the source
+  model, or use `codegen-engineer` when the generator itself must change.
+
+## Verification
+
+Run the narrowest relevant root command first with JDK 11:
+
+```bash
+.agents/workflows/gradle-root.sh :proto-values:test
+.agents/workflows/gradle-root.sh :proto-values:check
+.agents/workflows/gradle-root.sh clean build
+```
+
+Use `:codegen-tests:test` with `codegen-engineer` when a model change exposes
+or depends on generator behavior rather than only changing published schema.

.agents/skills/model-engineer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Model Engineer"
+  short_description: "Evolve Chords Protobuf models and extensions"
+  default_prompt: >
+    Use $model-engineer after reading AGENTS.md, README.md,
+    .agents/project.md, and proto-values/README.md to make a scoped Chords
+    Protobuf model change.