docs(spec): add consumer context guidance to purpose, surface descriptions, and output contracts

[hadleychristoffels]

Summary

Three targeted additions to docs/COVENANT.md that make consumer context a first-class concern in covenant authoring: purpose declarations should name who outputs serve, surface operation descriptions should identify the consumer when outputs are consumer-specific, and output contract descriptions should name what a value means to the consumer rather than just its structural type.

Linked issue

N/A

Spec impact

• docs/COVENANT.md changed
• spec/schema.json changed
• Conformance fixtures added or modified
• Validator or test-runner behaviour changed
• CLI or MCP surface changed
• None of the above

Changes

domain.purpose - adds one sentence: "Name the consumer or domain context, not just the operation." Updates the closing declaration from "this scope and nothing outside it" to "this scope, this consumer, and nothing outside it."

interface.surface[n].description - extends the existing bullet to: "what the operation does in one to two sentences; name who the outputs serve when they are consumer-specific." Preserves the length constraint; appends the consumer guidance conditionally.

contracts.outputs - adds two sentences: "Output description fields should name what the value means to the consumer, not just its structural type. Two outputs with the same type signature may serve entirely different professional or domain contexts; that distinction belongs in the description."

None of the additions alter a capitalised MUST or SHOULD. All three changes use lowercase prose guidance only.

Checklist

• npm test passes
• npm run test:fixtures passes
• npm run lint passes
• Conformance fixtures pass (when present)
• Breaking changes to covenant_version semantics are called out above
• Docs updated if behaviour changed
• No em-dashes, British English (project convention)

Note on lint: npm run lint reports 39 errors and 34 warnings on the unmodified branch tip (pre-existing). No new issues introduced by this change.

---

Summary by cubic

Adds consumer-context guidance to docs/COVENANT.md so contracts state who outputs are for, not just what they do or their type. Updates domain.purpose, interface.surface[n].description, and contracts.outputs descriptions to include consumer context; no schema or normative changes.

^{Written for commit 19fdbf6. Summary will update on new commits.}

Summary by CodeRabbit

• Documentation
  • Updated specification guidance with clearer wording for authors regarding domain context, operation descriptions, and output documentation requirements.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request updates the COVENANT specification document to clarify guidance for three key fields: domain.purpose now requires authors to name consumer or domain context; operation description guidance now emphasizes indicating who outputs serve when consumer-specific; and contracts.outputs guidance expands to require consumer meaning in descriptions and domain-context differentiation for structurally identical outputs.

Changes

Output and Domain Context Specification Guidance

Layer / File(s)	Summary
Specification wording clarifications docs/COVENANT.md	Three specification text updates clarify required author guidance: domain.purpose now instructs naming consumer/domain context; operation description now includes who outputs serve when consumer-specific; contracts.outputs description now requires consumer meaning statements and domain-context differentiation for structurally similar outputs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

📜 A clarity quest through the COVENANT tome,
Where domain and consumer find textual home,
Three sentences strengthened with purpose so clear,
Output descriptions now speak what we hear. 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main changes: adding consumer context guidance to three specific sections of the COVENANT.md specification.
Description check	✅ Passed	The description follows the template structure with Summary, Linked issue, and Spec impact sections completed. All required information is provided, including detailed explanations of changes and checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/consumer-context-guidance

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/COVENANT.md (1)

243-246: ⚡ Quick win

Consider aligning examples with the new consumer-context guidance.

The three guidance additions at lines 264, 324, and 472 emphasize naming consumer or domain context. The examples currently focus on operations and structural descriptions rather than demonstrating this guidance:

• domain.purpose example (lines 243-246) describes operations but doesn't name the consumer
• interface.surface descriptions (lines 285-305) don't indicate who outputs serve
• contracts.outputs descriptions (lines 436-447) focus on structural type rather than consumer meaning

Updating one or more examples to demonstrate the guidance would help authors understand what "naming the consumer context" looks like in practice.

Also applies to: 285-305, 436-447

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/COVENANT.md` around lines 243 - 246, The examples in COVENANT.md do not
demonstrate the new consumer-context guidance; update the example content for
domain.purpose, interface.surface, and contracts.outputs to explicitly name the
consumer or domain context they serve (e.g., "for content editors", "for
automated publishing pipeline", "for integration with CRM X") so readers see
practical usage; locate and edit the example blocks referenced by the symbols
domain.purpose, interface.surface, and contracts.outputs and replace or augment
their descriptive sentences with a short example that ties the output/intent to
a specific consumer persona or system.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@docs/COVENANT.md`:
- Around line 243-246: The examples in COVENANT.md do not demonstrate the new
consumer-context guidance; update the example content for domain.purpose,
interface.surface, and contracts.outputs to explicitly name the consumer or
domain context they serve (e.g., "for content editors", "for automated
publishing pipeline", "for integration with CRM X") so readers see practical
usage; locate and edit the example blocks referenced by the symbols
domain.purpose, interface.surface, and contracts.outputs and replace or augment
their descriptive sentences with a short example that ties the output/intent to
a specific consumer persona or system.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 62261057-806e-4359-b2c8-8fb03e0d268d

📥 Commits

Reviewing files that changed from the base of the PR and between b84ed8d and 19fdbf6.

📒 Files selected for processing (1)

• docs/COVENANT.md

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}