@sumrco/cli 0.3.0 → 0.3.1

package/ai/modules/kontract/resources/authoring/spec-layout.rf.md

@@ -0,0 +1,492 @@
+---
+category: reference
+name: spec-layout
+title: Spec File Layout
+description: "Required folder and file conventions for Kontract API and async schema source files."
+label: Spec Layout
+when: Creating or moving API spec files, adding a shared base spec, or debugging why a spec is not picked up
+order: 10
+---
+
+# Spec File Layout
+
+Kontract discovers specs by filename convention under the configured schema
+directory (default `schema/`).
+
+```text
+schema/
+  recipes.api.yml           ← one independent API schema doc per service/surface
+  recipes.async.yml         ← one independent async schema doc per surface, when messaging exists
+  shared/
+    enums.yml                   ← repo-level shared enums/scalars promoted after reuse
+    errors.yml                  ← repo-level shared API components promoted after reuse
+    pagination.yml              ← repo-level shared API components promoted after reuse
+  base.yml                      ← shared components, referenced via $ref
+  bookstore/
+    bookstore.api.yml           ← simple API schema root entrypoint
+    bookstore.async.yml         ← async schema root entrypoint only when messaging exists
+    catalog.api.yml          ← optional API schema sub-area grouped under bookstore
+    events.async.yml         ← optional async schema surface grouped under bookstore
+    shared/
+      enums.yml                 ← capability-local components promoted after reuse
+      components.yml            ← capability-local components promoted after reuse
+```
+
+## Rules
+
+- API schema specs end in `*.api.yml` / `*.api.yaml`.
+- async schema specs end in `*.async.yml` / `*.async.yaml`.
+- Public source files declare `api: <version>` or `async: <version>`.
+  Kontract normalizes those markers to the internal format required by its
+  validators and bundlers.
+- Discovery is recursive; `base.yml` is skipped as an entry point.
+- Service output paths mirror nested spec paths under the configured source
+  input directory. Moving a root spec is therefore a generated namespace/import
+  migration, not only a documentation cleanup.
+- A root `*.api.yml` or `*.async.yml` may reference plain `.yml`
+  fragments for paths, messages, parameters, and schemas. Kontract bundles the
+  root before generation when it finds external `$ref` links.
+- Do not infer async schema files from an API-only repo. Only produce async schema
+  roots, channels, message folders, or NATS examples when the repo has async schema
+  sources/targets or the user asks for messaging contracts.
+- Do not split a simple API schema root into `paths/` fragments by default. Start
+  with one focused root file and local `components.schemas`; use fragments only
+  when the root is too large, mixes independently owned surfaces, or repeats
+  component definitions.
+- API schema and async schema roots may share model fragments only when the
+  shapes mean the same thing for HTTP and messaging. This is most common for
+  enums, scalar value objects, IDs, slugs, and shared payload fields. Keep
+  protocol-specific path, operation, parameter, response, channel, and message
+  metadata in separate fragments.
+- Nested `*.api.yml` files are grouped by their first folder. This supports a
+  product-capability layout where the folder owns the contract package and each
+  file is a focused API surface:
+
+  ```text
+  schema/
+    recipes/
+      catalog.api.yml        ← API schema
+      publishing.async.yml   ← async schema
+  ```
+
+  Both files generate under `contracts/recipes/`.
+- Use `folder/folder.api.yml` for a simple product capability root that
+  should generate under the folder namespace, for example
+  `schema/bookstore/bookstore.api.yml` generates under `contracts/bookstore/`.
+- Do not confuse resource-area fragments inside a product-capability folder with
+  a repo-wide `by-resource-area` schema layout style. For example,
+  `schema/recipes/paths/ingredients.yml` is still a `recipes` capability
+  fragment, not a top-level `ingredients` resource-area root. Use
+  `design-profile/schema-layout-styles.rf.md` for canonical layout trees
+  before recommending file moves.
+- Use nested capability/surface paths when one root file would mix independently
+  owned API surfaces; see the scope and splitting reference for line-count
+  thresholds and naming rules.
+- Use comments only as editor navigation markers. Use uppercase noun labels such
+  as `CATALOG PATHS`, `COMPONENTS`, or `RESPONSE SCHEMAS`; they must
+  not explain endpoint behavior or replace `summary` / `description`.
+  When a root file has both `paths:` and `components:`, add a short visual
+  marker before `components:` too so the components block is easy to find.
+- Keep schemas in the owning root or surface first. Promote a schema to a
+  capability-local `shared/` folder only when multiple surfaces in that
+  capability reuse the same product concept. Promote it again to
+  `schema/shared/` only when multiple capabilities share the same meaning and
+  owner.
+- Share promoted schemas through `$ref` into `base.yml`, `schema/shared/`, or a
+  capability-local `shared/` folder when the meaning is identical. Do **not**
+  duplicate schemas across specs and do **not** merge by hand-mutating parsed
+  JSON.
+- Prefer `schema/shared/` only for cross-capability components such as common
+  parameters, error responses, pagination, scalar constraints, response envelope
+  fragments, schedules, and reusable config objects with stable semantics.
+- The async contract namespace comes from the async schema `info.title`, not the filename —
+  set `info.title` deliberately.
+- Multi-file specs are bundled automatically; keep `$ref` paths repo-relative.
+
+## Protocol scenarios
+
+Choose the protocol scenario first. Then apply the selected
+`schemaLayoutStyle`.
+
+| Scenario | Use when | Shareable pieces |
+|---|---|---|
+| API-only | The repo only defines HTTP contracts. | HTTP components, parameters, responses, request/response schemas. |
+| async-only | The repo only defines messaging contracts. | Message payload schemas, message enums, scalar value objects. |
+| API + async | The repo defines both HTTP and messaging contracts. | Neutral components with identical meaning, especially enums, IDs, slugs, scalars, and shared payload objects. |
+
+Do not share protocol layers. API schema paths, parameters, request bodies,
+responses, and async schema channels, operations, and messages stay in their own
+files.
+
+## API-only layout
+
+For a simple API-only repo, prefer one focused root file per product
+capability, API surface, resource area, workflow, or service owner. Do not add
+`*.async.yml`, `messages/`, or channel examples unless messaging is part of
+the actual contract.
+
+```text
+schema/
+  bookstore/
+    bookstore.api.yml       # simple API schema root entrypoint
+    shared/                     # only if multiple bookstore surfaces reuse it
+      enums.yml
+  orders/
+    main.api.yml             # api: 3.0.3; grouped under orders/http
+    public.api.yml
+    lifecycle.api.yml
+    shared/                     # capability-local promoted components only
+      enums.yml
+      components.yml
+  shared/                       # cross-capability promoted components only
+    errors.yml
+    pagination.yml
+```
+
+```yaml
+# schema/bookstore/bookstore.api.yml
+api: 3.0.3
+info:
+  title: Bookstore API
+  version: 1.0.0
+paths:
+  /books:
+    get:
+      operationId: listBooks
+      summary: List books
+      responses:
+        "200":
+          description: Paginated book list.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BookPage"
+# ----- COMPONENTS ---------------------------------------------------------
+components:
+  securitySchemes:
+    bearerAuth:
+      $ref: ../shared/security.yml#/securitySchemes/bearerAuth
+  schemas:
+    Book:
+      type: object
+      required: [id, title]
+      properties:
+        id:
+          type: string
+          format: uuid
+        title:
+          type: string
+          minLength: 1
+    BookPage:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/Book"
+        page:
+          $ref: ../shared/pagination.yml#/PageInfo
+```
+
+Use the `*.api.yml` suffix when one product-capability folder should
+group several API schema surfaces into one generated package:
+
+```text
+schema/
+  orders/
+    main.api.yml             # api: 3.0.3; generates under orders/http
+    public.api.yml           # api: 3.0.3; generates under orders/http
+    lifecycle.api.yml        # api: 3.0.3; generates under orders/http
+    shared/
+      enums.yml                 # promoted only after more than one surface needs it
+      components.yml
+```
+
+Keep this layout until a real split trigger appears. A simple API schema spec does
+not need a `paths/` directory only because Kontract supports multi-file specs.
+Also do not move every component into `shared/` preemptively. Local components
+are the default; shared files are a promotion step after real reuse appears.
+
+## async-only layout
+
+For an async-only repo, prefer one focused messaging root per product
+capability, API surface, workflow, service owner, or message family. Do not add
+API schema roots or `paths/` folders unless HTTP contracts are part of the repo.
+
+```text
+schema/
+  shared/
+    message-enums.yml
+  bookstore/
+    bookstore.async.yml      # async schema root entrypoint
+    messages/
+      book-commands.yml         # channels, operations, messages
+      book-events.yml
+    models/
+      books.yml                 # message payload schemas
+      enums.yml                 # capability-local message enums
+```
+
+```yaml
+# schema/bookstore/bookstore.async.yml
+async: 3.0.0
+info:
+  title: Bookstore
+  version: 1.0.0
+channels:
+  reserveBook:
+    $ref: ./messages/book-commands.yml#/channels/reserveBook
+operations:
+  reserveBook:
+    $ref: ./messages/book-commands.yml#/operations/reserveBook
+# ----- COMPONENTS ---------------------------------------------------------
+components:
+  messages:
+    ReserveBookCommand:
+      $ref: ./messages/book-commands.yml#/messages/ReserveBookCommand
+  schemas:
+    ReserveBookPayload:
+      $ref: ./models/books.yml#/ReserveBookPayload
+    BookFormat:
+      $ref: ./models/enums.yml#/BookFormat
+```
+
+## API + async with shared components
+
+When a repo has both protocols, keep the roots and protocol-specific layers
+separate. Share only components with identical semantics across both
+protocols. In practice that usually means enums, scalar value objects, IDs,
+slugs, and carefully named payload objects.
+
+```text
+schema/
+  bookstore/
+    bookstore.api.yml       # HTTP root
+    bookstore.async.yml      # messaging root
+    paths/
+      books.yml                 # API schema Path Item fragments
+    messages/
+      books.yml                 # async schema channels, operations, messages
+    models/
+      books.yml                 # payload schemas
+      enums.yml                 # shared enums used by both protocols
+```
+
+Do not put API schema paths, parameters, responses, async schema channels, operations,
+or messages into shared model files.
+
+## Split root-entrypoint layout
+
+Use this layout when one product capability should generate as one contract
+package, but the root files are getting too large:
+
+```text
+schema/
+  bookstore/
+    bookstore.api.yml
+    components/
+      parameters.yml
+    paths/
+      books.yml
+      authors.yml
+    models/
+      shared.yml
+      books.yml
+      authors.yml
+```
+
+If the same capability also owns messaging contracts, add the async schema root and
+message fragments explicitly:
+
+```text
+schema/
+  bookstore/
+    bookstore.async.yml
+    messages/
+      books.yml
+      authors.yml
+```
+
+The root files stay small and readable. Fragment files are plain `.yml` because
+they are not standalone API schema or async schema documents.
+
+If a root file needs many visual section markers to stay readable, split the
+internals into capability/surface fragments before adding more comments.
+For API schema path fragments, prefer one Path Item Object per file so the root can
+reference `./paths/books.yml` directly. Only use JSON Pointer paths such as
+`#/paths/~1books` when a single fragment intentionally contains a full `paths:`
+map with several paths.
+
+```yaml
+# schema/bookstore/bookstore.api.yml
+api: 3.0.3
+info:
+  title: Bookstore Contracts
+  version: 1.0.0
+paths:
+  /books:
+    $ref: ./paths/books.yml
+# ----- COMPONENTS ---------------------------------------------------------
+components:
+  schemas:
+    Book:
+      $ref: ./models/books.yml#/Book
+    PaginatedBooks:
+      $ref: ./models/books.yml#/PaginatedBooks
+```
+
+```yaml
+# schema/bookstore/paths/books.yml
+get:
+  operationId: listBooks
+  responses:
+    "200":
+      description: Paginated book list.
+      content:
+        application/json:
+          schema:
+            $ref: ../models/books.yml#/PaginatedBooks
+```
+
+```yaml
+# schema/bookstore/bookstore.async.yml
+async: 3.0.0
+info:
+  title: Bookstore
+  version: 1.0.0
+channels:
+  listBooks:
+    $ref: ./messages/books.yml#/channels/listBooks
+  listBooksReply:
+    $ref: ./messages/books.yml#/channels/listBooksReply
+operations:
+  listBooks:
+    $ref: ./messages/books.yml#/operations/listBooks
+# ----- COMPONENTS ---------------------------------------------------------
+components:
+  messages:
+    ListBooksQuery:
+      $ref: ./messages/books.yml#/messages/ListBooksQuery
+    PaginatedBooksReply:
+      $ref: ./messages/books.yml#/messages/PaginatedBooksReply
+  schemas:
+    ListBooksQuery:
+      $ref: ./models/books.yml#/ListBooksQuery
+    PaginatedBooks:
+      $ref: ./models/books.yml#/PaginatedBooks
+```
+
+```yaml
+# schema/bookstore/messages/books.yml
+channels:
+  listBooks:
+    address: qry.bookstore.books.list
+    messages:
+      listBooksQuery:
+        $ref: ./books.yml#/messages/ListBooksQuery
+  listBooksReply:
+    address: qry.bookstore.books.list.reply
+    messages:
+      paginatedBooksReply:
+        $ref: ./books.yml#/messages/PaginatedBooksReply
+operations:
+  listBooks:
+    action: receive
+    channel:
+      $ref: "#/channels/listBooks"
+    messages:
+      - $ref: "#/channels/listBooks/messages/listBooksQuery"
+    reply:
+      channel:
+        $ref: "#/channels/listBooksReply"
+      messages:
+        - $ref: "#/channels/listBooksReply/messages/paginatedBooksReply"
+messages:
+  ListBooksQuery:
+    payload:
+      $ref: ../models/books.yml#/ListBooksQuery
+  PaginatedBooksReply:
+    payload:
+      $ref: ../models/books.yml#/PaginatedBooks
+```
+
+Shared schemas can be referenced by both roots when they carry the same business
+meaning:
+
+```yaml
+# schema/bookstore/models/shared.yml
+BookSlug:
+  type: string
+  minLength: 1
+  maxLength: 120
+  pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+```
+
+```yaml
+# schema/bookstore/models/books.yml
+Book:
+  type: object
+  required: [id, slug, title]
+  properties:
+    id:
+      type: string
+      format: uuid
+    slug:
+      $ref: ./shared.yml#/BookSlug
+    title:
+      type: string
+      minLength: 1
+```
+
+Do not put graph, routing, or protocol behavior into shared model fragments.
+Share only business payload shapes.
+
+## API schema authoring rules
+
+- Put reusable HTTP payloads in `components.schemas`.
+- Operation request/response schemas should reference components with `$ref`.
+  Inline operation schemas are rejected so generated DTO/model names stay stable.
+- Use operation `summary` to name the action. Use `description` to explain
+  outcome, scope, caller context, constraints, or next steps; do not repeat the
+  summary in sentence form.
+- Avoid tag echo. If the API docs already show a tag such as `Playbook` or
+  `Accounts`, omit that word from the summary unless the operation would become
+  ambiguous.
+- Route public or developer-facing `summary`, `description`, parameter, schema,
+  and response text through the repo's copywriter standard before validating.
+- Prefer explicit object schemas over anonymous nested shapes when a payload is
+  shared by multiple operations.
+- If multiple responses repeat the same envelope fields, extract the envelope
+  fragment and compose concrete responses with supported object `allOf`.
+- If multiple schemas repeat the same regex or scalar validation, extract a
+  named scalar component and reference it.
+- Use stable `operationId` values. They become Swagger metadata constants such
+  as `SWG_LIST_RECIPES`.
+- Unsupported composition features (`oneOf`, `anyOf`, `not`, `discriminator`)
+  must either be modeled differently or implemented in Kontract before use.
+
+## async schema operation classification
+
+| async schema shape      | Generated client kind |
+|---------------------|-----------------------|
+| `receive` + `reply` | Query                 |
+| `receive`           | Command               |
+| `send`              | Event                 |
+
+Run `sumr kontract validate` after any layout change to confirm specs still
+resolve before generating.
+
+## async schema copy rules
+
+async schema `title`, `summary`, and `description` fields can appear in generated
+docs, SDK docs, and AI answers. Review them with the same copywriter standard as
+API schema:
+
+- `title` names the message or operation.
+- `summary` states the job or event in one concise sentence.
+- `description` adds context only when the outcome, constraint, or event
+  semantics need more detail.
+- Do not repeat the channel, operation id, schema key, or title in the summary.
+- Keep transport terms such as subject, payload, NATS, command, and query only
+  when the reader needs that exact implementation detail.

package/ai/modules/kontract/resources/authoring/team-members/spec-author.tm.md

@@ -0,0 +1,77 @@
+---
+category: team-member
+name: spec-author
+title: Spec Author
+description: "Owns API spec authoring and Kontract regeneration discipline. Use when changing API schema, async schema, or schema specs, validating, regenerating, or reviewing generated contract diffs."
+modelTier: reasoning
+access: write
+channels:
+  codex:
+    sandbox_mode: workspace-write
+---
+
+# Spec Author
+
+You own the API contract source of truth for this repo. You change YAML specs
+and let Kontract generate the TypeScript — you never hand-write or hand-patch
+generated contracts.
+
+Apply the generated **sumr-kontract-usage** skill, then start from the
+`resources/authoring/` overview. Use its configuration, design-profile axis
+references, spec-layout, schema-reuse, scope-and-splitting, and spec-change
+workflow before editing source specs. Use the generated-output reference before
+consuming or reviewing generated TypeScript.
+
+## Responsibilities
+
+- Translate API requirements into API schema, async schema, or `*.api.yml`
+  specs under `schema/`.
+- After writing or updating any `*.api.yml`, `*.async.yml`, or
+  `*.api.yml` file, review it against Kontract reuse, layout, and generation
+  rules before validating.
+- Review changed public or developer-facing summaries, descriptions, parameter
+  descriptions, response descriptions, message titles, and message summaries
+  against the repo's copywriter standard before generation.
+- Read `kontract.guidance.profile` before writing examples so HTTP paths,
+  async schema channels, and schema layouts match the selected styles.
+- Inspect the actual specs before writing examples. If the repo only has
+  API schema roots, keep guidance API-only and do not invent async schema files,
+  channel examples, or `messages/` folders.
+- If the repo only has async schema roots, keep guidance async-only and do not
+  invent API schema roots, `paths/`, or HTTP component examples.
+- When both protocols exist, keep API schema and async schema layers separate and share
+  only components with identical meaning, especially enums and scalar
+  value objects.
+- Use the canonical schema layout trees before proposing schema folders;
+  do not confuse resource-area fragments inside a product-capability root with a
+  repo-wide `by-resource-area` structure.
+- Keep shared shapes in shared component files and reference them with `$ref`.
+- Keep specs product-aligned and reviewable: use clear capability/surface paths,
+  split oversized files at documented thresholds, and avoid generic `common`
+  buckets for unrelated concepts.
+- Use comments only as visual editor landmarks. Do not explain endpoint behavior
+  with comments; use API/async descriptions for that.
+- Name schemas from product meaning first, using operation-specific response
+  names only when the shape belongs to one operation.
+- Proactively spot duplicated envelope fields, pagination metadata, error
+  schemas, path/query params, regex scalar constraints, schedules, and config
+  objects before generating.
+- Prefer supported object `allOf` composition when a concrete response extends
+  a shared base envelope.
+- Run `sumr kontract validate` then `sumr kontract generate` for every change.
+- Review the generated diff for correctness and unintended breakage.
+- If a generated diff creates many near-identical DTO/model files, pause and
+  propose a spec-level shared component refactor.
+- Keep spec + regenerated output committed together.
+- When generated files are missing, check `sumr.yaml` target options and the
+  installed `SUMR Kontract module` version before changing application code.
+
+## Boundaries
+
+- Never edit files under the generated `contracts/` output.
+- Never hand-write Zod schemas, DTOs, NATS subjects, or clients that Kontract owns.
+- Do not introduce a second source of truth; the spec is authoritative.
+- Do not over-share unrelated concepts only because their current fields look
+  similar; shared components must have the same product meaning and owner.
+- Flag breaking contract changes for human review before commit.
+- Scope `--clean` to the intended source/target in consumer repos.

package/ai/modules/kontract/resources/{workflows/contract-change.wf.md → authoring/workflows/spec-change.wf.md}

@@ -1,13 +1,13 @@
 ---
 category: workflow
-name: contract-change
-title: Contract Change
+name: spec-change
+title: Spec Change
 description: "Guides an AI agent through safely changing an API spec and regenerating Kontract contracts. Use when an API surface changes and generated contracts must follow."
 modelTier: coding
 access: write
 ---
 
-# Contract Change
+# Spec Change
 
 Use this workflow whenever an API surface changes (new endpoint, message,
 field, or breaking change) and the generated contracts must follow.
@@ -15,34 +15,40 @@ field, or breaking change) and the generated contracts must follow.
 ## Flow
 
 ```text
-🕐 edit spec -> review spec -> validate -> generate -> review diff -> ⏸ HUMAN APPROVES -> commit
+🕐 read authoring guidance -> edit spec -> review spec -> validate -> generate -> review diff -> ⏸ HUMAN APPROVES -> commit
 ```
 
 ## Steps
 
-1. **Edit the spec** under `schema/` (`*.openapi.yml` / `*.asyncapi.yml`).
+1. **Read the authoring guidance** under `resources/authoring/`. Confirm the
+   configured source input, current `kontract.guidance.profile`, selected
+   schema layout style, protocol scenario (API-only, async-only, or both
+   with shared components), and whether
+   the user asked for a guidance-only profile change or an actual schema/output
+   namespace migration.
+2. **Edit the spec** under `schema/` (`*.api.yml` / `*.async.yml`).
    Before adding new schemas, scan for existing shared components. Reuse shared
    components via `$ref`; never duplicate schemas.
-2. **Review the written spec** before validation. Check new or changed
-   `*.openapi.yml` / `*.asyncapi.yml` files against Kontract best practices:
+3. **Review the written spec** before validation. Check new or changed
+   `*.api.yml` / `*.async.yml` files against Kontract best practices:
    stable component names, no inline operation payload schemas, correct `$ref`
-   paths, reusable shared components, domain/subdomain boundaries, documented
-   size thresholds, and no copy-pasted product concepts.
-3. **Refactor repeated shapes first**. If the change repeats envelope fields,
+   paths, selected profile style, reusable shared components, documented size
+   thresholds, clear product ownership, and no duplicated product concepts.
+4. **Refactor repeated shapes first**. If the change repeats envelope fields,
    pagination metadata, error bodies, ID/date params, regex scalar constraints,
    schedules, or config objects, extract a shared component and reference it.
-4. **Validate**: `sumr kontract validate` (scope with `--source` if large).
+5. **Validate**: `sumr kontract validate` (scope with `--source` if large).
    Fix every reported error before continuing.
-5. **Generate**: `sumr kontract generate`. Unchanged specs are skipped.
+6. **Generate**: `sumr kontract generate`. Unchanged specs are skipped.
    Scope large repos with `--source`, `--target`, or `--specific`.
-6. **Review the diff** of the generated `contracts/` output. Confirm
+7. **Review the diff** of the generated `contracts/` output. Confirm
    `http/models`, `http/enums`, `http/zod`, optional `http/dto`,
    optional `http/swagger.ts`, and NATS `SUBJECTS` match the intended change;
    watch for unintended removals. If the diff introduces many near-identical
    generated files, return to the spec and look for a shared component.
-7. **Do not edit generated files** to "fix" the diff — change the spec and
+8. **Do not edit generated files** to "fix" the diff — change the spec and
    regenerate instead.
-8. **Commit** the spec change and the regenerated output together so they
+9. **Commit** the spec change and the regenerated output together so they
    never drift.
 
 ## Transition rules