[JSdotNet]

Summary

Tasks can now point at Devbook pages and chapters, the way spec-manager links backlog items to spec pages. A reference is <path> or <path>#<anchor>, for example .devbook/domain/tasks/domain.md#task.

References live in a field of their own on the task. They never appear in the entry text. Each one is resolved when it is read, so a renamed chapter still shows on the task, marked as broken.

Changes

• Domain (Tasks)
  • New TaskDevbookReference value object.
  • TaskItem.SetDevbookReferences takes the whole list, keeps its order and drops duplicates.
  • A path that starts with a devbook area (arc42, domain, tech, design or ai) is stored under .devbook/.
  • New ITaskItems.SetDevbookReferencesAsync and TaskItemDto.DevbookReferences.
• Storage and sync
  • SQLite gets a devbook_refs column, added the additive way (ADR 0006).
  • TaskPayload.DevbookReferences is the last field and defaults to empty. TaskReplicaMerge maps it both ways.
• Import (ADR 0007)
  • A plan entry's metadata line accepts devbook:<path>[#anchor], and the token may repeat. Import moves the tokens into the field.
  • A re-import replaces the list only when the entry carries at least one devbook: token, so references added by hand survive.
  • The grammar document and the Foundry plan prompt are updated.
• Resolution
  • IDevbookReferenceResolver is a port owned by Tasks.Abstractions. The module boundary rules stop a module UI from referencing Devbook.Abstractions, so the port is answered by an adapter in Infrastructure.Devbook.
  • The adapter reads the database first and falls back to the file, which is read with a containment check. Both run off the render thread, and the chapter headings come back in one batched query.
  • Each reference resolves to one of chapter, page, unknown-heading, unknown-page, outside-devbook or unverified, with its title and status.
• MCP (ADR 0012)
  • set_devbook_references replaces the whole list.
  • list_devbook_references returns each reference resolved.
  • read_item now includes devbookReferences.
• Desktop
  • The task panel gets a "Devbook" group of DevbookReferenceChips, a new library component. Each chip shows the status pill and a broken marker, and can be opened or removed. Accessible names carry the location and, for a broken reference, the problem.
  • A page and chapter picker matches on title or path and shows at most 50 options at a time.
  • Task rows with references show a 📖 count.
  • Clicking a chip opens the reference in the Devbook pane on the task's repository. Home tracks a one-shot DevbookOpenRequest, so remounting the pane does not replay an old request.
  • Reference writes are serialised, so quick picks are not lost.
• Shared components that change behaviour elsewhere
  • TagMultiSelect gains ShowSelected, MatchValue and MaxOptions.
  • Its input now binds with @bind:get/set, which fixes keystrokes dropped while typing fast.
  • Its options are single-line with an ellipsis, so long "Waiting for" titles now truncate.
  • In the task panel, Escape now closes an open picker before it closes the entry. This applies to every picker.
• Storybook: new stories for the chip, the task panel's Devbook group, and the long-list TagMultiSelect.

Testing

• The CI build (Backlog.WithoutAppHeads.slnf, Release, -warnaserror, --no-incremental) is clean, and so is the Debug Backlog.sln build with the MAUI heads.
• dotnet test across the solution: 10,848 passed, 0 failed, 1 skipped (the E2E suite, which is gated on BACKLOG_E2E). New tests cover the domain, SQLite, sync, import, resolver, MCP, bUnit UI and component behaviour.
• Browser QA used Playwright against the desktop web harness and Storybook under Aspire, with log monitoring running. There were four rounds:
  • The first three found 16 defects, all fixed: an empty picker on a new task, the picker's open state leaking into the next task, Escape closing the whole panel, duplicate accessible names, path matching, dropped keystrokes, chip pill sizing and dropdown overflow.
  • The last round passed.
  • No error logs or failed traces appeared.
• The devbook checks pass: build.mjs --check and check-metadata.mjs.

Known limits, deliberately out of scope

• Opening a chapter shows its page from the top and does not scroll to the #anchor. Every chapter link in the Devbook pane already behaves this way.
• Merge is whole-document last-writer-wins. A desktop on a version without this feature that edits a task will drop that task's references when it syncs.
• A text autosave that races a reference write can restore the old list. Every other task field has the same read-modify-write race.
• Undo/redo (Undo and redo task changes with Ctrl+Z in the Tasks pane #940) works from text snapshots. Adding or removing a reference is not an undo step. Undoing a delete recreates the task from its text, so its references, like its PR projections, are not restored. Ctrl+Z inside the picker is left to the input.

Verification

Item	Verdict
Acceptance criteria 1–5 (domain, storage and sync, resolution, MCP, import, UI)	aligned. Chapter chips open their page without scrolling to the #anchor
.devbook/domain/tasks/features.md, domain.md	code-ahead: the feature is not written down yet
.devbook/domain/devbook/domain.md#task-link, #cross-linking (draft)	conflict: the draft says the Devbook context owns the link, but here the task owns it
Design guideline for DevbookReferenceChip	code-ahead

All three non-aligned rows are left to a follow-up devbook change.

Related

No issue; this was an ad-hoc request. Refs ADR 0002, 0006, 0007 and 0012.

Follow-up: the devbook chapters (.devbook/domain/tasks/) do not describe this feature yet. The draft Task Link and Cross-Linking chapters in .devbook/domain/devbook/domain.md model a link that the Devbook context owns, which needs reconciling. Both belong in a separate devbook change.

Checklist

• Scope is focused and excludes unrelated changes
• Documentation or instruction files were updated when governance or behavior changed (import grammar, Foundry prompt; devbook capture is a follow-up)
• Running Aspire instances for this checkout were stopped before PR creation
• Follow-up work is captured when the implementation is intentionally partial
• Issues this PR closes are linked with a closing keyword, or there are none

🤖 Generated with Claude Code