feat(agents): publish bounded work classification

[decode2]

Linked issue

Refs #1702. This is an additive published-metadata slice, not completion of the owner-decision protocol.

PR type

• New feature (type:feature)

Summary

• Publish optional structured work (area/topic, tags, explicitly repository-scoped issue/PR/task refs) through the existing curated state entry and cache.
• Keep exact schema-1 legacy reads and use schema 2 only for validated work; retain atomic replacement/withdrawal and pre-effect rejection.
• Preserve metadata-only, historical, non-authoritative readback without a second registry, private-history inspection, or model calls.

Changes

Surface	Change
lib/orchestrator-work.ts	Pure bounded, detached work validator
lib/orchestrator-state.ts	Combined byte budget and compatible schema selection
extensions/gentle-agents.ts	Existing state parameter documents the structured shape
tests/orchestrator-work.test.ts, tests/gentle-agents.test.ts	Validator/cache/schema and production-tool publication regressions
docs/gentle-agents-activity.md	Example, limits and honest partial-feature boundaries
odd/tasks/work-discovery.md	Scope and delivery evidence

Test plan

• RED: original decodeCuratedState rejected valid work (invalid-published-state), one intended failure.
• Writer focused suite: node --experimental-strip-types --test tests/orchestrator-work.test.ts tests/gentle-agents.test.ts, 199 passed.
• Writer state/discovery/catalog/consultation/SDK regression suite, 20 passed.
• Type ratchet: 186 recorded diagnostics, no regressions (not clean compilation).
• Runtime module check: all eight modules match; no generated changes.
• Independent seven-file focused verification: 219 passed, 0 failed/skipped.
• Whitespace check passed.
• Shellcheck and skill-load testing: N/A, no shell scripts or skills changed.
• Classification-specific full SDK and human UI acceptance: not claimed; subsequent integration slice.

Contributor checklist

• Nonclosing approved issue reference selected for partial coordination work.
• Exactly one type:* label requested at creation; verify readback.
• Applicable deterministic tests and behavior docs included.
• Authorized conventional work-unit commit completed.
• No AI attribution or Co-Authored-By trailers.

Chain context

Field	Value
Strategy	Sequential stacked feature-parent PRs, individually useful
Position	1, publication foundation
Base	main at 653dad90
Depends on	None, prior coordination chain is merged
Follow-up	Explicit owned task annotation, opt-in search/related matches, actual SDK acceptance
Review budget	301 additions + deletions / 400
Starts at	Existing four-field curated publication
Ends with	Validated work available in targeted list and metadata consultation
Rollback	Remove optional work/schema-2 support and its tests/docs; legacy state remains

main
 └── 📍 this PR: classified publication
      └── next: explicit allocated-task annotation
           └── next: published-work search / related matches
                └── next: SDK acceptance

Out of scope: automatic agent routing, ODD-file indexing, task launch/inheritance, search wiring, helper work capture, owner decisions, dependency execution, exclusive writer locks and runtime activation.

Native assessment: medium risk, large runtime-recorded writer, under budget; native outcome is unknown, not an approved/consumed native review. Independent focused verification: 219 passed, zero failed or skipped; no unexpected repository mutation. No main merge or runtime reload is authorized by this PR.

Summary by CodeRabbit

• New Features
  • Added optional work classifications with an area, topic, tags, and references to issues, pull requests, or tasks. Metadata is validated, size-limited, and available when published state is read back or consulted.
  • Existing published state remains compatible when no work classification is provided.
• Documentation
  • Added guidance on classifying recorded work, including limits and how updates and withdrawals behave.
  • Clarified that classifications do not provide search, inheritance, or owner-decision coordination.

[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: 4c80fa2c-d767-4d2f-b4b3-aa49f6ace400

📥 Commits

Reviewing files that changed from the base of the PR and between bc7624a and b1779ef.

📒 Files selected for processing (2)

• extensions/gentle-agents.ts
• tests/gentle-agents.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 bounded state.work classification metadata to orchestrator state. It validates the descriptor, publishes work-bearing state as schema 2 while retaining schema 1 for text-only state, and tests publication and discovery readback.

Changes

Published Work Classification

Layer / File(s)	Summary
Work descriptor and validation lib/orchestrator-work.ts, extensions/gentle-agents.ts, docs/gentle-agents-activity.md	The work descriptor defines optional area, topic, tags, and references. Validation enforces field, text, uniqueness, and size limits. The tool schema and documentation describe these constraints and state that references are not resolved or used for routing.
Published-state schemas and cache lifecycle lib/orchestrator-state.ts, tests/orchestrator-work.test.ts	Curated state accepts validated work metadata within the shared 2048-byte limit. Publishing selects schema 2 when work is present and schema 1 otherwise. Tests cover schema validation, compatibility, and cache lifecycle behavior.
Session and discovery readback tests/gentle-agents.test.ts, odd/tasks/work-discovery.md	Tests verify rejection without session changes and discovery readback of valid and malformed peer state. The coordination document records bounded classification publication as complete and other work units as pending.

Priority: ⬇️ Low

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

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Tool as orchestrator_session_id tool
  participant Curated as decodeCuratedState
  participant Work as decodeWork
  participant State as Published state
  participant Discovery as Discovery listing and consultation
  Tool->>Curated: Submit state.work
  Curated->>Work: Validate work descriptor
  Work-->>Curated: Return decoded descriptor
  Curated->>State: Publish validated state with schema 2
  State->>Discovery: Provide published work metadata

Loading

Suggested reviewers: alan-thegentleman

Merge Risk: ⚪ Minimal · up to b1779

Text-only state remains compatible, and validated work metadata is published and read back as intended. No actionable merge-blocking issue was established; proceed with normal checks.

Architecture Summary

Architecture risk: 🔵 Low · up to b1779

The change affects 5 systems.

Changed systems: extensions, lib, tests, docs, odd

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — extensions (service) was modified; 1 changed file maps to changed impact.
• observed — lib (service) was modified; 2 changed files map to changed impact.
• observed — tests (service) was modified; 2 changed files map to changed impact.
• observed — docs (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in docs/gentle-agents-activity.md: The documentation adds the state.work classification format and its constraints: topic requires area; tags and refs are bounded; refs require an explicit public repository and canonical positive-decimal issue/PR IDs, while task IDs are non-routable historical declarations. It describes rejection of duplicates, empty work, unknown keys, unsafe strings, and over-budget combined state. Omitting work in an object replacement clears classification; state: null withdraws the record. Work uses schema 2, text-only records schema 1, and readback is detached and non-authoritative. The text also states that refs are not resolved and no launch, filtering, inheritance, Git, network, or model behavior is added. The prior “Neither issue is cl
• observed — Modified behavior in lib/orchestrator-state.ts: CuratedState adds optional work: WorkDescriptor, and PublishedState.schema expands from 1 to 1 | 2; WorkDescriptor and decodeWork are imported for the new state field.
• observed — Modified behavior in lib/orchestrator-state.ts: decodeCuratedState now permits the work key, decodes it with decodeWork, and includes its serialized size in the 2048-byte limit. Unknown keys and unsafe curated text still cause invalid-published-state.
• observed — Modified behavior in lib/orchestrator-state.ts: Published-state decoding now accepts schema 1 or 2 and rejects records unless schema 2 corresponds exactly to a decoded state with work. The returned record preserves the validated schema instead of forcing schema 1.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 5 files.	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 and concisely describes the main change: publishing bounded work classification for agents.
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.

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