[unbraind]

Universal context controls previously refused every pm-brief reader. This change opts all nine commands into the SDK 2026.10.13 read_output contract and returns structured results when canonical controls are requested. Ordinary documents and file-summary JSON/TOON keep their existing output; file writes refuse read controls before writing.

Design and before/after

• Declare actual, non-overlapping row collections; align the development SDK, peer floor, manifest floor and version contract.
• Use a scoped output service for ordinary rendered documents and file summaries, declining structured results so the host owns projection, omission receipts, budgets and continuation.
• Before: pm brief next --output-budget refused usage. After: the installed host applies the requested budget and exposes advancing per-path cursors when rows are compacted.

Validation

• env HOME=$(mktemp -d) GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 npm run release:check: 390 passed, 0 failed/skipped.
• env HOME=$(mktemp -d) GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 bun run release:check: 390 passed, 0 failed/skipped.
• Coverage at unchanged thresholds: 100% lines, 98.27% branches, 100% functions across the configured source. All three packed-consumer scenarios (npm-current, bun-current, npm-minimum) pass under both gates.
• Linked node --test test/read-output-host.test.ts: 13 passed, 0 failed/skipped. The packaged-host suite also passes on Node 22.23.1; archive discovery tolerates npm 10 lifecycle stdout. Strict tracker health with required merge drivers passes.
• Declaration-only revert: rebuild an isolated snapshot after removing only all nine declarations; all nine reader regressions fail on the host refusal (zero passes or skips).
• Real temporary trackers and the npm-packed extension verify all readers, projection, infeasible budgets, exact projected row-identity recovery, SDK transports, ordinary documents, all supported document file variants and writer refusal.

Adoption recipe

1. Pin the development SDK to 2026.10.13 and synchronize the peer/manifest floors and package-specific constants.
2. Add read_output: { row_keys: [...] } only to readers. Paths must name real, non-overlapping arrays/object maps; use [] for a singleton or nullable result shape.
3. Return structured payloads for canonical controls. Route ordinary raw documents through a scoped output_format service that declines structured results. Guard hybrid file-writing flags before side effects.
4. Test every reader through the packed extension and installed host over real trackers: projection, explicit omission, budget-fitting pages, cursor progress and exactly-once row recovery. Later pages may need a larger budget; retry the same cursor without changing semantic inputs.
5. Remove only declarations in an isolated snapshot, rebuild and require the reader tests to fail; run unchanged npm/Bun release gates.

Tracker: pm-brief-ccwo.

SDK observation: generic budget-string compaction can shorten compound identifiers longer than 240 characters. Tests use ordinary stable IDs and allow disclosed detail compaction; SDK changes and upstream issue filing are outside this task.

Summary by Sourcery

Adopt the SDK 2026.10.13 read-output contract across pm-brief readers while preserving existing document rendering and safely rejecting incompatible file writes.

New Features:

• Enable all nine pm-brief reader commands to support the SDK universal read-output controls with structured projections, budgets, and cursor-based continuation.

Bug Fixes:

• Prevent read-output controls from being applied to file-writing commands before any file or tracker mutation occurs.
• Preserve existing ordinary document, JSON, and TOON output behavior when canonical controls are not requested.

Enhancements:

• Replace command-specific renderer ownership with a scoped output-format service that leaves structured results to the host.
• Declare accurate row contracts for each reader and align the SDK, peer dependency, manifest, and version requirements with the read-output contract.

Documentation:

• Document universal read-output controls, writer restrictions, cursor recovery, row contracts, and the adoption requirements.

Tests:

• Add packaged-host coverage for projection, omissions, budget handling, cursor recovery, SDK transports, document output, and writer refusal.
• Update output ownership tests to validate the scoped output service and structured-result fallback behavior.

Chores:

• Add tracker fixtures and history for the read-output adoption work.

---

Summary by cubic

Adopts the SDK 2026.10.13 read_output contract on all nine brief read commands, so the host can now apply universal projection, amount, token-budget, and cursor-continuation controls. Previously the host refused these controls; now commands return structured results when canonical controls are requested, while ordinary documents and file summaries keep existing output and file writes refuse read controls before writing.

• Declares read_output with real, non‑overlapping row paths on all nine readers.
• Routes ordinary rendered documents through a scoped output service that declines structured results, leaving projection and continuation to the host.
• Bumps the dev SDK pin, peer dependency floor, and manifest pm_min_version to 2026.10.13.
• Adds host‑contract tests covering the full read path and verifies that removing the declarations makes the contract fail as expected.

^{Written for commit 46478e7. Summary will update on new commits.}

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[sourcery-ai]

Sorry @unbraind, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 16 hours and 40 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 00caa98c-5419-4a16-bc18-f9695e1bb917

📥 Commits

Reviewing files that changed from the base of the PR and between 3b6fc94 and 46478e7.

⛔ Files ignored due to path filters: 1

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing: 9

• .agents/pm/features/pm-brief-ccwo.toon
• .agents/pm/history/pm-brief-ccwo.jsonl
• README.md
• index.ts
• manifest.json
• package.json
• test/read-output-host.test.ts
• test/renderer-ownership.test.ts
• test/version-contract.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Summary by CodeRabbit

• New Features
  • Read commands now support host-managed output controls for projecting results, omitting content, applying output budgets, and continuing through results.
  • Existing document and diagram output remains available when host controls aren’t requested.
• Bug Fixes
  • Requests that combine --output with host-managed output controls now return a usage error before writing a file.
  • Infeasible output budgets report an error and exit with status 2.
• Documentation
  • Added guidance on using output controls and recovering budget-compacted results.

Walkthrough

pm-brief adopts pm CLI read-output controls for nine read commands. The commands provide structured results for host processing and retain ordinary rendering. The extension updates its service registration and minimum supported CLI version, and adds packaged-host tests and documentation.

Changes

Read-output controls

Layer / File(s)	Summary
Host output contract and service index.ts, manifest.json, package.json, test/renderer-ownership.test.ts	The extension uses the output_format service in place of renderer registration. It routes structured results for host handling, formats file-summary results, updates the CLI version requirements, and tests service behavior.
Read-command row declarations and routing index.ts	The nine read commands declare structured row keys and route results through the output-aware helper. They reject incompatible output controls before processing.
Packaged-host coverage and adoption records test/read-output-host.test.ts, README.md, .agents/pm/features/*, .agents/pm/history/*	Packaged-host tests cover projection, omission, budget failures, cursor-based recovery, file output, and ordinary rendering. The README describes the controls and adoption contract. Agent records document the implementation and report checks.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant BriefCommand
  participant PmCliHost
  participant OutputFormatService
  BriefCommand->>PmCliHost: Return declared structured rows
  PmCliHost->>PmCliHost: Apply requested output controls
  PmCliHost->>OutputFormatService: Request formatting for file-summary output
  OutputFormatService-->>PmCliHost: Return JSON or text output

Loading

Possibly related PRs

• unbraind/pm-brief#76: PR #76 introduced complete-corpus reads for brief readers. This PR adds host output declarations and routing to those reader paths.

Merge Risk: ⚪ Minimal · up to 46478

No actionable merge-blocking issue was identified; the change is ready for normal merge checks.

Pre-merge checks: 5

Passed checks: 5 passed

Check name	Status	Explanation
Title check		The title clearly and concisely identifies the main change: enabling read_output controls for brief reader commands.
Description check		The description directly explains the read_output adoption, preserved output behavior, writer restrictions, dependency updates, and validation results.
Docstring Coverage		Docstring coverage is 80.43% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 46 functions across 4 files. (5 skipped: 5 …
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.}

[sourcery-ai]

Reviewer's Guide

This PR upgrades all nine pm-brief readers to the pm CLI/SDK 2026.10.13 read_output contract by declaring real row paths, returning structured data for host-controlled requests, and routing ordinary documents through a scoped output service; it also raises compatibility floors, guards file writes, adds packed-host continuation and projection coverage, and documents the adoption model.

Sequence diagram for host-controlled brief output

sequenceDiagram
    actor User
    participant CLI as pm_CLI_host
    participant Brief as pm_brief_reader
    participant Service as output_format_service

    User->>CLI: Invoke brief command with output controls
    CLI->>Brief: run(ctx)
    Brief->>Brief: validateReadOnlyOutput(ctx)
    Brief-->>CLI: Structured result with declared rows
    CLI->>CLI: Apply projection, budget, omission, cursor
    CLI-->>User: Projected page and optional continuation cursor

    User->>CLI: Invoke brief command without controls
    CLI->>Brief: run(ctx)
    Brief-->>Service: Rendered document result
    Service-->>CLI: Raw document output
    CLI-->>User: Existing document rendering

Loading

Flow diagram for brief file-write control validation

flowchart TD
    A[Brief reader invoked] --> B{--output and read controls supplied?}
    B -- Yes --> C[validateReadOnlyOutput]
    C --> D[Reject with usage error]
    B -- No --> E{File output requested?}
    E -- Yes --> F[writeFileSync]
    E -- No --> G[Return structured or rendered result]

Loading

File-Level Changes

Change	Details	Files
Opt all nine brief readers into the SDK read_output contract while preserving existing document and summary rendering paths.	Declare concrete, non-overlapping row collections for each reader. Return structured payloads when canonical host controls are present. Retain ordinary rendered documents and file-summary behavior through a scoped output_format service. Reject read controls with --output before any file-write side effect.	index.ts
Align package compatibility and extension capabilities with the read_output and service APIs.	Pin development and peer SDK requirements to 2026.10.13. Raise the manifest minimum version and replace renderer capability with services. Update lockfile and version-contract expectations.	package.json package-lock.json manifest.json test/version-contract.ts
Add comprehensive packed-consumer and service-level validation for host projection, budgeting, continuation, and rendering ownership.	Exercise all nine readers through the installed host over real trackers. Verify projection, omissions, infeasible budgets, cursor advancement, exact row recovery, SDK transports, and writer refusal. Replace renderer-registration tests with output-service ownership tests.	test/read-output-host.test.ts test/renderer-ownership.test.ts
Document the universal read output controls and adoption requirements for users and maintainers.	Describe supported controls, row discovery, projection, budgets, cursors, and file-write restrictions. Record the SDK pinning, declaration, implementation, and validation recipe.	README.md
Record the feature tracker and implementation history.	Add the tracker definition and history entries for the adoption work.	.agents/pm/features/pm-brief-ccwo.toon .agents/pm/history/pm-brief-ccwo.jsonl

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[unbraind]

@coderabbitai full review

Please review head 46478e7, including outside-diff findings.

[coderabbitai]

✅ Action performed

Full review finished.