fix(odd): pass the user's spec by reference so handoffs stop losing requirements

[Alan-TheGentleman]

Closes #1713

Type

• Bug fix (type:bug)

Summary

• The ODD feature document becomes the specification subagents read by reference: a fixed ## Specs (verbatim user strings, errors, and examples) → ## Tasks (one line each) → ## Log (where L1 is the original request verbatim) order. A requirement change rewrites only the affected S# and reopens only its task.
• Handoffs reference that document instead of paraphrasing it, verify returns a verdict per S# and runs the spec's examples on isolated state, and user-reported failures are reproduced before being dismissed. The compact contract lives in the always-on ODD steps, because the lazy assets were never read in the failing benchmark run.
• Handoff friction no longer shrinks content: writer-surface rejections name the concrete problem and ask for the same task unchanged, generic writer continuations inherit the surfaces their launch was admitted with, and unknown task ids list recent ids.

Changes

File	Change
extensions/gentle-ai.ts	Always-on ODD steps 5–6: document order, verbatim specs, reference handoffs, per-S# verify, reproduce-first
assets/orchestrator-memory.md	Detailed Specs/Tasks/Log format and per-spec change rule
assets/orchestrator-delegation.md	Removes "translate the user's request into concise English"; requirements are never translated, condensed, or paraphrased; rejected handoffs are resent unchanged
assets/agents/gentle-ai-{worker,verify,explore}.md	Read the document until ## Log (verify reads all of it); report covered S#; verify gives a verdict per S#
lib/bounded-writer-admission.ts	Concrete rejection problems (prose, invalid path, ambiguous quotable path, empty or conflicting sections, missing heading); inheritAllowedEditSurfaces for generic writer continuations; one heading matcher
extensions/gentle-agents.ts	subagent_continue inherits surfaces; unknown task ids list recent ids, context-safe
tests/*	Contract tests for the document and handoffs, exact rejection assertions, an end-to-end writer continuation test (mutation-checked), and unknown-id hints
odd/tasks/spec-by-reference-handoffs.md	Feature document, written in the new format

Test plan

• npm run typecheck: no regressions (186 recorded diagnostics, baseline unchanged).
• npm test: all stages passed (unit tests, provider contract, runtime harness).
• Focused: writer-edit-surface-scope 15/15, bounded-writer-admission 8/8, gentle-agents 191/191, prompt-contract files 589/589.
• RED was observed before each behavior change. The continuation wiring was mutation-checked: removing it makes the end-to-end test fail with the exact rejection.
• Native review: four RDD reviews were approved and acknowledged. The last one (review-44982330792543f8) returned no findings.
• Shellcheck: not applicable (no scripts changed).

Follow-up

• Port the document format to the gentle-ai canon (internal/components/agentguidance/routing.go) and regenerate fixtures/odd-routing-canonical.md, so that other runtimes get the same contract.

Checklist

• Linked issue is approved (status:approved)
• Exactly one type:* label
• Conventional commits, no Co-Authored-By trailers
• Tests and docs alongside behavior
• Shellcheck: not applicable

Summary by CodeRabbit

• Improvements
  • Feature requirements and user corrections are carried through task handoffs without being condensed or reworded.
  • Verification now reports each requirement as met, unmet, or unverified, with supporting evidence. Reported failures must be reproduced before being dismissed.
  • Continued tasks retain their original editing boundaries when none are specified for the follow-up.
  • Editing-boundary errors now explain what needs correcting, and unknown task IDs can show recent tasks to help identify the right one.

[coderabbitai]

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

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 99e60146-f229-404d-af7f-a0cc7c60c7c7

📥 Commits

Reviewing files that changed from the base of the PR and between cf3012f and 7c89cca.

📒 Files selected for processing (14)

• assets/agents/gentle-ai-explore.md
• assets/agents/gentle-ai-verify.md
• assets/agents/gentle-ai-worker.md
• assets/orchestrator-delegation.md
• assets/orchestrator-memory.md
• extensions/gentle-agents.ts
• extensions/gentle-ai.ts
• lib/bounded-writer-admission.ts
• odd/tasks/spec-by-reference-handoffs.md
• tests/bounded-writer-admission.test.ts
• tests/gentle-agents.test.ts
• tests/odd-routing-contract.test.ts
• tests/orchestrator-budget.test.ts
• tests/writer-edit-surface-scope.test.ts

 _________________________________________________
< Because, even your code needs a second opinion. >
 -------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

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