Repository navigation
Document company_onboarding brief purpose in Context reference - #365
sidneyswift wants to merge 2 commits into
Conversation
The company_onboarding purpose shipped through database#96, api#992 and app#2178 but the public OpenAPI reference still listed only creative_direction and playlist_pitch, so public docs no longer matched shipped HTTP/MCP behavior. Add the enum value on the brief and save_brief branches, describe assessment_scope and per-request next_steps, state the coverage-not-proof and no-rights caveats, and name the required company-assessment migration. Additive edits only. Refs recoupable/app#2134 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configuration
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
1 issue found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/context.json">
<violation number="1" location="api-reference/openapi/context.json:301">
P3: The 200 response description names the `next_steps` entry fields as "requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics", but the operation description names the third field `topics`. A consumer reading only the response section cannot tell the field is called `topics`. Name it explicitly, e.g. "requestId, action, and topics (that request's missing topics)", so both sections agree on the field name.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
| }, | ||
| "200": { | ||
| "description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record." | ||
| "description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record. For purpose company_onboarding, brief and save_brief responses (and read_brief snapshots of them) additionally include assessment_scope (always selected_saved_context_requests) and next_steps: one entry per request with requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics." |
There was a problem hiding this comment.
P3: The 200 response description names the next_steps entry fields as "requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics", but the operation description names the third field topics. A consumer reading only the response section cannot tell the field is called topics. Name it explicitly, e.g. "requestId, action, and topics (that request's missing topics)", so both sections agree on the field name.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At api-reference/openapi/context.json, line 301:
<comment>The 200 response description names the `next_steps` entry fields as "requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics", but the operation description names the third field `topics`. A consumer reading only the response section cannot tell the field is called `topics`. Name it explicitly, e.g. "requestId, action, and topics (that request's missing topics)", so both sections agree on the field name.</comment>
<file context>
@@ -294,7 +298,7 @@
},
"200": {
- "description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record."
+ "description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record. For purpose company_onboarding, brief and save_brief responses (and read_brief snapshots of them) additionally include assessment_scope (always selected_saved_context_requests) and next_steps: one entry per request with requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics."
},
"400": {
</file context>
The read-only brief action compiles company_onboarding in api code and never calls save_context_brief, so only save_brief (and snapshots read back with read_brief) depends on 20261010010000_context_company_assessment. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Summary
Brings the public Context reference in line with shipped behavior for the
company_onboardingbrief purpose, which merged and went live via database#96 → api#992 → app#2178 but is still missing fromapi-reference/openapi/context.jsonon docsmain. Addscompany_onboardingto thepurposeenum of thebriefandsave_briefrequest branches, documents what that purpose adds to the response (assessment_scope: "selected_saved_context_requests"and per-requestnext_stepswithreview_assessment_coverage/review_available_evidence), states that missing topics are coverage prompts rather than proof evidence does not exist and that submitted names/metadata do not establish rights or ownership, and notes that only saving (save_brief) needs migration20261010010000_context_company_assessment.sql; the read-onlybriefaction compiles the purpose in api code. This advances #2134's Done-when item "Public docs and MCP match shipped behavior". The MCP input schema is shared with the API Zod schema, but the human-readable MCP tool descriptions (context,compile_music_context_brief,save_music_context_brief) also still name only creative direction and playlist pitch, so the docs are not the only surface that lags (documented in the api runbook, recoupable/api#1012, section 2.2). Additive, anchored JSON edits only: no path, example or existing enum value removed; no new MDX page; nodocs.jsonchange.Refs recoupable/app#2134 (child of epic recoupable/app#2116).
Merge sequencing
docs → database → api → app. Superseded by recoupable/docs#360 (see the note above). No code dependency: the behavior described is already merged and released (database#96, api#992, app#2178). Sibling PR for this ticket: recoupable/api#1012 (release runbook + guard test), which does not depend on this PR and references docs#360 as the preferred docs change. No database or app PR for this ticket.
Verification
python3 -c "import json;json.load(open('api-reference/openapi/context.json'))"— parses.briefandsave_briefpurpose enums both containcompany_onboarding; thebriefpurpose description no longer claims the migration is required; thesave_briefpurpose description does; the 200 response description containsassessment_scope— ok.origin/main— all previouspathsand every previous enum value retained (10 insertions, 6 deletions; the deletions are the replaced description strings and the two enum closers, each replaced by a superset).git merge-treeagainst the docs#358 and docs#360 branches — both conflict with this PR (same hunks).Out of scope / known gaps
plan,read_execution, release-case and release-track actions, name/brief/text intake) are still documented only inapi/lib/context/README.mdand the MCP tool schema.🤖 Generated with Claude Code