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

Copy Source

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 470eb911c0

jason.woltje commented 2026-07-13 16:16:24 +00:00

Author

Owner

Copy Link

Copy Source

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 c9f69300a3

jason.woltje commented 2026-07-13 16:45:39 +00:00

Author

Owner

Copy Link

Copy Source

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 7aea94e274

jason.woltje commented 2026-07-13 17:09:18 +00:00

Author

Owner

Copy Link

Copy Source

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 25b9d642b9

jason.woltje commented 2026-07-13 17:30:40 +00:00

Author

Owner

Copy Link

Copy Source

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

jason.woltje referenced this issue from a commit 2026-07-13 17:44:20 +00:00

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

jason.woltje referenced this issue from a commit 2026-07-13 18:00:13 +00:00

docs(tess): ledger sync m4 — M5-003 done, #745/#746 merged

jason.woltje referenced this pull request 2026-07-13 18:00:41 +00:00

docs(tess): ledger sync m4 — M5-003 done, #745/#746 merged #749

jason.woltje referenced this pull request 2026-07-13 18:09:00 +00:00

docs(tess): ledger sync m4 — M5-003 done, #745/#746 merged #749

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

bug

Defect in framework tooling or delivered code

fleet-enhancement

Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#746