feat(agents): query published work classification

[decode2]

Linked issue

Refs #1702; additive metadata-only coordination, not closure of owner decision work.

PR type

• New feature (type:feature)

Summary

• Export a complete bounded searchPublishedWork library over existing presence/discovery, with strict AND area/topic/tag/text/typed-reference/recorded-root filters.
• Add an explicit owner-bound classification-only discovery projection; default list behavior and curated prose privacy remain unchanged.
• Join task annotations only to the owner's current active catalog page, preserving unknowns, omissions and detached whole-row output.

Changes

Surface	Change
lib/orchestrator-work-search.ts	Strict pre-read validation, exact typed refs/IDs, human-text comparison, cached-root matching, bounded query/coverage
lib/orchestrator-discovery.ts	Optional work-only projection and exact recipient narrowing
tests/orchestrator-work-search.test.ts	Seven behavior tests with real publication, negative identity joins, bounds and privacy
docs/gentle-agents-activity.md, odd/tasks/work-discovery.md	Library contract, limits and evidence

Test plan

• Meaningful RED: existing discovery lacked explicit work projection; GREEN passed.
• Empty-recipient RED: requested empty selector broadened to all peers; GREEN preserves direct [] and rejects invalid query selections before reads.
• Writer eight-suite run: 46 passed, zero failures.
• Independent ten-suite fixed-candidate run: 254 passed, zero failed/skipped/cancelled; seven query tests passed, source and Git-index hashes unchanged.
• Type ratchet: 186 recorded diagnostics with no regressions, not clean compilation.
• Runtime check: all eight generated modules unchanged; whitespace passed.
• Shellcheck / skill-load testing: N/A, no scripts or skills changed.

Contributor checklist

• Approved existing issue, nonclosing reference for partial feature.
• Exactly one type:feature requested, verify readback.
• Tests, docs and conventional work-unit commit included.
• No AI attribution or Co-Authored-By trailers.

Chain context

Field	Value
Strategy	Sequential feature-parent stack
Position	3, usable basic metadata query library
Base	feat/work-task-annotations, PR #1780 (520cab8b)
Depends on	#1780 → #1779
Next	Related-source queries, then public list/SDK integration
Review budget	376 additions + deletions / 400, including tests/docs/tracker
Starts at	Classified session notes and explicit allocated-task annotations
Ends with	Working bounded index/filter library, not public-tool wiring
Rollback	Remove query module/tests and optional projection; publication/annotation remains

main
 └── #1779: classified publication
      └── #1780: actual owned task annotation
           └── 📍 this PR: bounded basic query library
                └── next: related-source queries
                     └── next: public list / SDK acceptance

The full query forecast was 430–540 lines; it was split by useful behavior, not compressed. related_to deliberately rejects until the next unit. No new tool verb, store, index artifact, owner wake, model call or Git probe. Shared declared refs do not prove dependencies or approval; classification remains descriptive.

Coverage is not exhaustive: at most 64 unique advertised peers, all activations retained for ambiguity checks, one eight-task catalog page each, 16-KiB whole JSON limit with whole-row omissions. Unknown/unclassified/historical unmatched annotations and catalog omissions/pending pages are counted. Rejected/overflow presence scans retain existing fail-closed behavior. Task roots never inherit the parent root or resolve launch paths.

Out of scope: public orchestrator_list.filter, related-source selection, new search SDK proof, helper classification capture, owner decisions, permission/ownership/exclusivity and runtime activation. Existing SDK regression passed, but it does not prove the not-yet-wired public query feature.

Native assessment: medium risk, runtime large profile, under budget, outcome unknown. Extra independent functional verification is separate evidence, not native review consumption or main merge approval.

Summary by CodeRabbit

• New Features

  • Added a bounded search for published work, with filters for areas, topics, tags, text, references, and repository roots. Results include matching reasons and report coverage or omitted entries.
  • Added an opt-in way to include published work details in orchestrator discovery results.

• Documentation

  • Documented search behavior and limitations, including that public search tools and related-work queries are not included.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 7a360714-be20-4b56-9c84-ef696b8d82ef

📥 Commits

Reviewing files that changed from the base of the PR and between 36a78bc and 3bc4561.

📒 Files selected for processing (5)

• docs/gentle-agents-activity.md
• lib/orchestrator-discovery.ts
• lib/orchestrator-work-search.ts
• odd/tasks/work-discovery.md
• tests/orchestrator-work-search.test.ts

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

---

📝 Walkthrough

Walkthrough

The change adds opt-in published-work data to orchestrator discovery and introduces a library search for classified work. The search validates filters and selection, limits peer and catalog reads, and returns detached results with match and coverage details.

Changes

Published work search

Layer / File(s)	Summary
Opt-in discovery work projection lib/orchestrator-discovery.ts, tests/orchestrator-work-search.test.ts, docs/gentle-agents-activity.md	Discovery accepts optional recipient selection and includeWork. For the matching recipient, it returns published work and its timestamp when requested; otherwise, it returns the existing state metadata.
Search index and filter matching lib/orchestrator-work-search.ts, tests/orchestrator-work-search.test.ts	The search validates supported filter fields, indexes classified root work and annotations for current catalog tasks, and applies AND-combined filters. Results identify satisfied filters or classified.
Bounded search and coverage reporting lib/orchestrator-work-search.ts, tests/orchestrator-work-search.test.ts, docs/gentle-agents-activity.md, odd/tasks/work-discovery.md	The search limits examined peers and catalog pages, reports incomplete or omitted data, and caps detached results at 16 KiB. Documentation and task records describe the available search and work that remains outside its scope.

Priority: ⬇️ Low

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant searchPublishedWork
  participant PresenceAndCatalogData
  Caller->>searchPublishedWork: Submit filter, peers, and selection
  searchPublishedWork->>searchPublishedWork: Validate filter and selection
  searchPublishedWork->>PresenceAndCatalogData: Examine bounded peer and catalog data
  PresenceAndCatalogData-->>searchPublishedWork: Return presence and catalog records
  searchPublishedWork-->>Caller: Return matches and coverage details

Loading

Merge Risk: ⚪ Minimal · up to 3bc45

This change adds an opt-in work projection and a bounded library-only search over published work. No actionable merge-blocking issue was found, and the default discovery behavior is preserved.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 3bc45

The new query exposes deliberately published metadata without granting execution authority or exporting private owner notes. Recipient and identity checks remain effective. Some inherited persistence and partial-publication guarantees remain unverified, but no introduced security vulnerability was established.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — The new query operates on caller-supplied peers within one profile and exposes published classifications, labels, task status, workspaces and recorded repository facts. Its output has no transport endpoints or execution controls. On non-Windows platforms, existing storage controls require owned private publication directories and owned regular files; this is not isolation from another process running as the same user.

Trust Boundaries and Controls

• observed — Caller-supplied peer records do not alone establish a work join. Discovery requires one activation, one matching presence header, matching activation metadata and a recent header. Discovery and catalog readers check session hash, incarnation and generation; workRecord additionally requires the published state's session ID to match the candidate. Stale, duplicate, malformed or mismatched inputs produce unknown or absent work.
• observed — The state decoder requires the exact validated envelope, schema-compatible curated fields and fixed non-authoritative markers. The cache binds reads to both manager identity and session ID, suppresses older state when the latest record is malformed or foreign, and returns clones. Publication checks identity before and after its append callback before replacing the cached value.

Resilience and Maintainability Implications

• observed — Existing publication uses atomic replacement per file, but catalog and discovery writes fail independently and are not a cross-file transaction. Cleanup is idempotent and removes only files whose identities still match the publisher's records. Search preserves non-authoritative and recorded-time semantics; it does not establish live or transactionally consistent ownership from these snapshots.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding a query for published work classification.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 3 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · 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.}