mosaicstack/stack
1
0
Fork 0
Code Issues 42 Pull Requests Actions Packages Projects Releases 15 Wiki Activity

docs(#744): complete Tess documentation gate #746

Merged
jason.woltje merged 4 commits from feat/tess-docs into main 2026-07-13 17:44:18 +00:00
Conversation 4 Commits 4 Files Changed 7 +416
jason.woltje commented 2026-07-13 16:01:30 +00:00
Owner
Copy Link

Refs #744

Task: TESS-M5-003

Adds API contract, user/admin/developer/plugin/operations guides, and completion checklist.

Refs #744 Task: TESS-M5-003 Adds API contract, user/admin/developer/plugin/operations guides, and completion checklist.
jason.woltje added 1 commit 2026-07-13 16:01:31 +00:00
docs(#744): add Tess API and operations guides
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
470eb911c0
jason.woltje commented 2026-07-13 16:16:24 +00:00
Author
Owner
Copy Link

REQUEST CHANGES reviewer-of-record [W-jarvis:reviewer] head 470eb911c0

Reviewed exact live head 470eb911c0220982ca5eac9002aa81f3efa2db7b; Woodpecker pipeline 1782 is SUCCESS for that commit. apps/gateway/src/commands/command-authorization.service.ts is byte-identical to main (hash a9f829e7ecec721c6c585fe0da56fb5d6a6441e9). Scope is docs-only.

Blockers for the documentation hard gate:

  1. docs/openapi-tess.yaml does not cover the real memory API. The real MemoryController exposes:

    • GET /api/memory/preferences
    • GET /api/memory/preferences/:key
    • POST /api/memory/preferences
    • DELETE /api/memory/preferences/:key
    • GET /api/memory/insights
    • GET /api/memory/insights/:id
    • POST /api/memory/insights
    • DELETE /api/memory/insights/:id
    • POST /api/memory/search

    The spec documents only POST /api/memory/search, so preferences and insights are missing despite being explicitly in scope.

  2. The OpenAPI request/response schemas are not traceable to the actual DTOs/controllers. The spec mostly uses descriptions and { type: object }, but the landed DTOs include concrete shapes such as CreateMosHandoffDto, UpsertPreferenceDto, CreateInsightDto, and SearchMemoryDto. The interaction enroll/attach/send/stop/recover bodies are also collapsed into one generic object instead of documenting their distinct controller body contracts.

  3. The interaction operation path is malformed/too generic for a hard-gate contract. The real controller defines separate routes (/enroll, /attach, /send, /stop, /recover, plus SSE /stream), while the spec collapses them into /sessions/{sessionId}/{operation}. Parsed YAML also turns the multiline summary into stray operation keys (attach, send, stop, or recover a durable session) rather than a single summary, which is not a valid/usable OpenAPI operation object.

  4. The guide files are present, but they are one-paragraph placeholders. For a documentation hard gate, they do not yet substantively ground the real endpoint/body contracts, memory preference/insight behavior, or operational procedures beyond high-level statements.

Positive checks: docs are present, no code/product files changed, no live credentials found, and the Mos coordination route names (handoff, observe, result) align with MosCoordinationController.

No merge performed by reviewer.

Marker: ROR-746-REQUEST-CHANGES-470eb911

REQUEST CHANGES reviewer-of-record [W-jarvis:reviewer] head 470eb911c0220982ca5eac9002aa81f3efa2db7b Reviewed exact live head `470eb911c0220982ca5eac9002aa81f3efa2db7b`; Woodpecker pipeline `1782` is SUCCESS for that commit. `apps/gateway/src/commands/command-authorization.service.ts` is byte-identical to main (hash `a9f829e7ecec721c6c585fe0da56fb5d6a6441e9`). Scope is docs-only. Blockers for the documentation hard gate: 1. `docs/openapi-tess.yaml` does not cover the real memory API. The real `MemoryController` exposes: - `GET /api/memory/preferences` - `GET /api/memory/preferences/:key` - `POST /api/memory/preferences` - `DELETE /api/memory/preferences/:key` - `GET /api/memory/insights` - `GET /api/memory/insights/:id` - `POST /api/memory/insights` - `DELETE /api/memory/insights/:id` - `POST /api/memory/search` The spec documents only `POST /api/memory/search`, so preferences and insights are missing despite being explicitly in scope. 2. The OpenAPI request/response schemas are not traceable to the actual DTOs/controllers. The spec mostly uses descriptions and `{ type: object }`, but the landed DTOs include concrete shapes such as `CreateMosHandoffDto`, `UpsertPreferenceDto`, `CreateInsightDto`, and `SearchMemoryDto`. The interaction enroll/attach/send/stop/recover bodies are also collapsed into one generic object instead of documenting their distinct controller body contracts. 3. The interaction operation path is malformed/too generic for a hard-gate contract. The real controller defines separate routes (`/enroll`, `/attach`, `/send`, `/stop`, `/recover`, plus SSE `/stream`), while the spec collapses them into `/sessions/{sessionId}/{operation}`. Parsed YAML also turns the multiline summary into stray operation keys (`attach`, `send`, `stop`, `or recover a durable session`) rather than a single summary, which is not a valid/usable OpenAPI operation object. 4. The guide files are present, but they are one-paragraph placeholders. For a documentation hard gate, they do not yet substantively ground the real endpoint/body contracts, memory preference/insight behavior, or operational procedures beyond high-level statements. Positive checks: docs are present, no code/product files changed, no live credentials found, and the Mos coordination route names (`handoff`, `observe`, `result`) align with `MosCoordinationController`. No merge performed by reviewer. Marker: ROR-746-REQUEST-CHANGES-470eb911
jason.woltje added 1 commit 2026-07-13 16:30:52 +00:00
docs(#744): complete Tess API contracts
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
c9f69300a3
jason.woltje commented 2026-07-13 16:45:39 +00:00
Author
Owner
Copy Link

REQUEST CHANGES reviewer-of-record [W-jarvis:reviewer] head c9f69300a3

Reviewed exact live head c9f69300a367c62dba544e5d4be409b53f2dbcab; Woodpecker pipeline 1784 is SUCCESS for that commit. apps/gateway/src/commands/command-authorization.service.ts remains byte-identical to main (hash a9f829e7ecec721c6c585fe0da56fb5d6a6441e9). Scope is docs-only.

Progress:

  • Memory API coverage is now mostly present in docs/openapi-tess.yaml: preferences list/get/upsert/delete, insights list/get/create/delete, and search are documented.
  • The generic /sessions/{sessionId}/{operation} path was split into distinct /enroll, /attach, /send, /stop, and /recover routes.
  • YAML parses cleanly; the prior stray summary keys are gone.

Remaining blockers:

  1. OpenAPI dropped the Mos coordination endpoints entirely. The real MosCoordinationController exposes:

    • POST /api/coord/mos/handoff
    • GET /api/coord/mos/{handoffId}/observe
    • GET /api/coord/mos/{handoffId}/result

    These were required in the documentation hard gate and are referenced by the guides/checklist, but no /api/coord/mos/... paths exist in the current OpenAPI file.

  2. OpenAPI still does not document the real interaction stream route. The real InteractionController exposes @Sse('sessions/:sessionId/stream'); the requested remediation explicitly included /stream, but docs/openapi-tess.yaml has no stream path.

  3. The checklist is now inaccurate: it claims openapi-tess.yaml covers Mos handoff/observe/result, but the OpenAPI file does not. It also only names “memory search” even though the remediated scope requires memory preferences + insights + search.

  4. Some request body schemas are closer but still not fully aligned with controller contracts: Send and Stop omit required fields for content/idempotencyKey and approvalRef; Insight marks source and category required even CreateInsightDto makes them optional. These should be corrected so the contract is traceable to the actual DTOs/controllers.

No merge performed by reviewer.

Marker: ROR-746-REQUEST-CHANGES-c9f69300

REQUEST CHANGES reviewer-of-record [W-jarvis:reviewer] head c9f69300a367c62dba544e5d4be409b53f2dbcab Reviewed exact live head `c9f69300a367c62dba544e5d4be409b53f2dbcab`; Woodpecker pipeline `1784` is SUCCESS for that commit. `apps/gateway/src/commands/command-authorization.service.ts` remains byte-identical to main (hash `a9f829e7ecec721c6c585fe0da56fb5d6a6441e9`). Scope is docs-only. Progress: - Memory API coverage is now mostly present in `docs/openapi-tess.yaml`: preferences list/get/upsert/delete, insights list/get/create/delete, and search are documented. - The generic `/sessions/{sessionId}/{operation}` path was split into distinct `/enroll`, `/attach`, `/send`, `/stop`, and `/recover` routes. - YAML parses cleanly; the prior stray summary keys are gone. Remaining blockers: 1. OpenAPI dropped the Mos coordination endpoints entirely. The real `MosCoordinationController` exposes: - `POST /api/coord/mos/handoff` - `GET /api/coord/mos/{handoffId}/observe` - `GET /api/coord/mos/{handoffId}/result` These were required in the documentation hard gate and are referenced by the guides/checklist, but no `/api/coord/mos/...` paths exist in the current OpenAPI file. 2. OpenAPI still does not document the real interaction stream route. The real `InteractionController` exposes `@Sse('sessions/:sessionId/stream')`; the requested remediation explicitly included `/stream`, but `docs/openapi-tess.yaml` has no stream path. 3. The checklist is now inaccurate: it claims `openapi-tess.yaml` covers Mos handoff/observe/result, but the OpenAPI file does not. It also only names “memory search” even though the remediated scope requires memory preferences + insights + search. 4. Some request body schemas are closer but still not fully aligned with controller contracts: `Send` and `Stop` omit `required` fields for `content`/`idempotencyKey` and `approvalRef`; `Insight` marks `source` and `category` required even `CreateInsightDto` makes them optional. These should be corrected so the contract is traceable to the actual DTOs/controllers. No merge performed by reviewer. Marker: ROR-746-REQUEST-CHANGES-c9f69300
jason.woltje added 1 commit 2026-07-13 17:00:52 +00:00
docs(#744): complete Tess API coverage
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
7aea94e274
jason.woltje commented 2026-07-13 17:09:18 +00:00
Author
Owner
Copy Link

REQUEST CHANGES reviewer-of-record [W-jarvis:reviewer] head 7aea94e274

Reviewed exact live head 7aea94e27498033a8f69a1f17c9dfe2fe83da9fc; Woodpecker pipeline 1785 is SUCCESS for that commit. apps/gateway/src/commands/command-authorization.service.ts remains byte-identical to main (hash a9f829e7ecec721c6c585fe0da56fb5d6a6441e9). Scope is docs-only.

Progress since comment 17157:

  • OpenAPI now includes the Mos coordination routes: /api/coord/mos/handoff, /api/coord/mos/{handoffId}/observe, and /api/coord/mos/{handoffId}/result.
  • OpenAPI now includes interaction SSE /api/interaction/{agentName}/sessions/{sessionId}/stream.
  • Memory preferences/insights/search paths are present.
  • YAML parses cleanly and no stray summary keys were found.

Remaining blocker:

  • Request-body schemas are still not aligned to the real controller/DTO contracts:
    • Send has no schema-level required: [content, idempotencyKey], but InteractionController.send() rejects when either is missing/blank.
    • Stop has no schema-level required: [approvalRef], but InteractionController.stop() rejects when it is missing/blank.
    • Insight still marks source and category as required (required: [content, source, category]), but CreateInsightDto only requires content; source, category, and metadata are optional.
    • POST /api/coord/mos/handoff still has no request body schema for CreateMosHandoffDto (idempotencyKey, summary required; context, missionId optional), so that endpoint is present but not yet DTO-traceable.

Given this is the documentation hard gate, the OpenAPI contract needs to be mechanically faithful to the actual DTO/controller contracts before approval.

No merge performed by reviewer.

Marker: ROR-746-REQUEST-CHANGES-7aea94e2

REQUEST CHANGES reviewer-of-record [W-jarvis:reviewer] head 7aea94e27498033a8f69a1f17c9dfe2fe83da9fc Reviewed exact live head `7aea94e27498033a8f69a1f17c9dfe2fe83da9fc`; Woodpecker pipeline `1785` is SUCCESS for that commit. `apps/gateway/src/commands/command-authorization.service.ts` remains byte-identical to main (hash `a9f829e7ecec721c6c585fe0da56fb5d6a6441e9`). Scope is docs-only. Progress since comment `17157`: - OpenAPI now includes the Mos coordination routes: `/api/coord/mos/handoff`, `/api/coord/mos/{handoffId}/observe`, and `/api/coord/mos/{handoffId}/result`. - OpenAPI now includes interaction SSE `/api/interaction/{agentName}/sessions/{sessionId}/stream`. - Memory preferences/insights/search paths are present. - YAML parses cleanly and no stray summary keys were found. Remaining blocker: - Request-body schemas are still not aligned to the real controller/DTO contracts: - `Send` has no schema-level `required: [content, idempotencyKey]`, but `InteractionController.send()` rejects when either is missing/blank. - `Stop` has no schema-level `required: [approvalRef]`, but `InteractionController.stop()` rejects when it is missing/blank. - `Insight` still marks `source` and `category` as required (`required: [content, source, category]`), but `CreateInsightDto` only requires `content`; `source`, `category`, and `metadata` are optional. - `POST /api/coord/mos/handoff` still has no request body schema for `CreateMosHandoffDto` (`idempotencyKey`, `summary` required; `context`, `missionId` optional), so that endpoint is present but not yet DTO-traceable. Given this is the documentation hard gate, the OpenAPI contract needs to be mechanically faithful to the actual DTO/controller contracts before approval. No merge performed by reviewer. Marker: ROR-746-REQUEST-CHANGES-7aea94e2
jason.woltje added 1 commit 2026-07-13 17:15:34 +00:00
docs(#744): align Tess request schemas
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
25b9d642b9
jason.woltje commented 2026-07-13 17:30:40 +00:00
Author
Owner
Copy Link

VERIFIED APPROVE reviewer-of-record [W-jarvis:reviewer] head 25b9d642b9

Reviewed exact live head 25b9d642b939014b3efd61826e7524cafc6ffc2e; Woodpecker pipeline 1786 is SUCCESS for that commit. apps/gateway/src/commands/command-authorization.service.ts remains byte-identical to main (hash a9f829e7ecec721c6c585fe0da56fb5d6a6441e9). Scope is docs-only.

Round-3 blocker verification:

  • Send schema now has required: [content, idempotencyKey], matching InteractionController.send().
  • Stop schema now has required: [approvalRef], matching InteractionController.stop().
  • Insight schema now has required: [content] only; source, category, and metadata remain optional, matching CreateInsightDto.
  • POST /api/coord/mos/handoff now references MosHandoff with required: [idempotencyKey, summary]; context and missionId are optional, matching CreateMosHandoffDto.

Also re-confirmed: OpenAPI parses cleanly, includes distinct interaction routes plus SSE stream, Mos handoff/observe/result, memory preferences/insights/search, and the checklist matches the documented coverage. No merge performed by reviewer.

Marker: ROR-746-VERIFIED-APPROVE-25b9d642

VERIFIED APPROVE reviewer-of-record [W-jarvis:reviewer] head 25b9d642b939014b3efd61826e7524cafc6ffc2e Reviewed exact live head `25b9d642b939014b3efd61826e7524cafc6ffc2e`; Woodpecker pipeline `1786` is SUCCESS for that commit. `apps/gateway/src/commands/command-authorization.service.ts` remains byte-identical to main (hash `a9f829e7ecec721c6c585fe0da56fb5d6a6441e9`). Scope is docs-only. Round-3 blocker verification: - `Send` schema now has `required: [content, idempotencyKey]`, matching `InteractionController.send()`. - `Stop` schema now has `required: [approvalRef]`, matching `InteractionController.stop()`. - `Insight` schema now has `required: [content]` only; `source`, `category`, and `metadata` remain optional, matching `CreateInsightDto`. - `POST /api/coord/mos/handoff` now references `MosHandoff` with `required: [idempotencyKey, summary]`; `context` and `missionId` are optional, matching `CreateMosHandoffDto`. Also re-confirmed: OpenAPI parses cleanly, includes distinct interaction routes plus SSE stream, Mos handoff/observe/result, memory preferences/insights/search, and the checklist matches the documented coverage. No merge performed by reviewer. Marker: ROR-746-VERIFIED-APPROVE-25b9d642
jason.woltje merged commit bc8016c831 into main 2026-07-13 17:44:18 +00:00
jason.woltje deleted branch feat/tess-docs 2026-07-13 17:44:19 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#746
Delete Branch "feat/tess-docs"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?