feat(agents): relate declared work snapshots

[decode2]

Linked issue

Refs #1702; descriptive coordination metadata, not closure of owner decisions.

PR type

• New feature (type:feature)

Summary

• Extend the existing bounded work-query library with strict related_to stable session and optional active task selectors.
• Resolve the explicit published source inside the same 64-peer bound, without widening selected candidate/cursor scope.
• Distinguish shared declared typed refs from possible area/topic/tag overlap; unavailable sources return zero related matches, never a broad fallback index.

Changes

Surface	Change
lib/orchestrator-work-search.ts	Source validation/provenance, bounded inclusion, exact entity exclusion and relation reasons
tests/orchestrator-work-search.test.ts	Real publication fixtures, reference collisions, own children, ghosts/pages, source cap, selection and bytes
docs/gentle-agents-activity.md, odd/tasks/work-discovery.md	API, honest limits and evidence

Test plan

• RED: 7 passed / 1 intended failure; existing API rejected a valid related-source query.
• Focused GREEN: 22 passed, zero failures.
• Writer broader regression: 55 passed, zero failures/skips.
• Independent ten-suite frozen candidate: 259 passed, zero failed/skipped/cancelled/todo; all source and index hashes unchanged.
• Type ratchet: 186 recorded diagnostics, no regressions (not clean compilation).
• Runtime eight generated modules unchanged and whitespace check passed.
• Shellcheck / skill-load tests: N/A, no scripts or skills changed.

Contributor checklist

• Existing approved issue, nonclosing partial-feature reference.
• Exactly one type:feature label requested; verify readback.
• Behavior, tests and docs in one conventional work-unit commit.
• No AI attribution or Co-Authored-By trailers.

Chain context

Field	Value
Strategy	Sequential feature-parent stack
Position	4, complete library related-source behavior
Base	feat/work-search, PR #1785 (da374c32)
Depends on	#1785 → #1780 → #1779
Next	Public list-filter registration and real public SDK acceptance
Review budget	270 additions + deletions / 400, tests/docs/tracker included
Starts at	Usable bounded basic work index/filter library
Ends with	Descriptive exact-source related-work queries
Rollback	Remove related-source field/logic/tests/docs; basic work queries remain

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

A source beyond the first 64 replaces one selected peer, not a 65th read. Task sources must join their owner's current published catalog page. Unknown/stale/ambiguous/unclassified/historical/outside-page sources are unavailable, not owner refusals. Only the exact source entity is excluded; independently classified root/child nodes under the same owner may still relate. Filters apply to candidate matches, not source eligibility.

Whole JSON, including source descriptor/provenance/reasons and coverage, stays at 16 KiB with whole-row omissions. All metadata remains detached, historical and non-exhaustive. Exact shared issue/PR/task references do not prove executable dependencies, permission, approval, exclusive ownership, reachability or owner replies. Same categories/tags indicate possible overlap only. No new model, Git resolution, store, index artifact, transport or tool verb.

Out of scope: public list wiring/new search SDK proof, helper work capture, owner-only decisions and runtime activation. Existing SDK regression does not prove new filter wiring or real agent spawning. The existing owned two-Node-process presence fixture is not AgentRunner child execution. The writer initially omitted repository Gentle AI preflight while reading portable test/work-unit/doc skills; subsequent read-only compliance inspection recorded that omission, without claiming retroactive preflight.

Native assessment: medium/runtime-large/under-budget, outcome unknown. Extra functional verification is not native consumption or main merge authorization.

Summary by CodeRabbit

• New Features
  • Related-work searches can now use a specific session, and optionally a task, as their source. The source must be present in the owner’s current published catalog.
  • Results include source details when available, or explain why the source could not be found. Related results exclude the source itself and show the reasons they match.
  • Existing filters still apply, while a selected recipient remains the only recipient of matches.

[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: 8b5940fc-4800-4dae-920a-6f90735edada

📥 Commits

Reviewing files that changed from the base of the PR and between 765c1d6 and 1be62c1.

📒 Files selected for processing (4)

• docs/gentle-agents-activity.md
• 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; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

searchPublishedWork accepts a related-work selector, resolves its source from published catalog data, and reports source availability. Related results exclude the source and include literal relationship reasons. The change also updates tests and documentation. Public tool, SDK, and helper capture remain unimplemented.

Changes

Related-work query

Layer / File(s)	Summary
Selector and source result contract lib/orchestrator-work-search.ts, tests/orchestrator-work-search.test.ts	WorkFilter accepts a validated related_to selector. WorkSearchResult can include available or unavailable source status, published-work provenance, and the source node or reason. Tests cover selector validation.
Source discovery and recipient scope lib/orchestrator-work-search.ts, tests/orchestrator-work-search.test.ts	Source discovery includes the requested session within the 64-peer limit and reports unavailable sources when catalog context cannot resolve the requested work. Tests cover peer limits, recipients, cursors, and unavailable-source cases.
Relationship matching and query evidence lib/orchestrator-work-search.ts, tests/orchestrator-work-search.test.ts, docs/gentle-agents-activity.md, odd/tasks/work-discovery.md	Related matches exclude the source and require at least one literal overlap reason. Tests cover reference, area, topic, and tag overlap. Documentation and work-unit evidence record the query behavior, bounds, and verification. Public tool, SDK, and helper capture remain unimplemented.

Priority: ⬇️ Low

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

Change: Feature

Merge Risk: ⚪ Minimal · up to 1be62

The related-work query appears ready to merge after normal checks. No actionable issue is established in the reviewed change.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 1be62

The new lookup remains bounded, read-only, and explicitly non-authoritative. No introduced security issue was identified in the inspected paths, but downstream integration and deployment coverage remain limited.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected exposure is published metadata within the caller-supplied profile and peer set, with at most 64 selected unique peers. The existing storage model is a same-profile OS-user trust boundary, not tenant authorization. Source selection changes which advertised peer can be read within that bound, but the inspected path does not launch tasks, execute tools, or grant authority.

Trust Boundaries and Controls

• observed — Caller-controlled source IDs select only supplied peer identities. Discovery binds metadata to the canonical peer activation, and catalog reads validate session hash, incarnation, generation, activation, and cursor binding. Match recipient selection is a filtering control, not a confidentiality boundary for the separately requested source report.

Resilience and Maintainability Implications

• observed — The search reports non-exhaustive coverage and omitted rows rather than hiding uncertainty. It performs no publication mutation, and detached output prevents callers from modifying later query results through returned source or match objects. The inspected regression assertions cover this isolation; tests were not executed during this review.

Hardening Proposals

• proposed — When registering a public tool or SDK caller, preserve the distinction between match selection and source access: establish any required access policy over both identities before supplying peers, and continue treating relationship metadata as non-authoritative. This is a future integration safeguard, not an observed defect in this PR.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 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 summarizes the main change: adding related-work queries for declared work snapshots.
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 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 5 functions across 2 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.}