feat(coordination): implied Related-Section detection via title-keyword match

[thewrz]

Why

#256 A4: a spec body can imply a Related Section it doesn't list — e.g. a conduit spec describing firestopping should reference 07 84 00 Firestopping. This is fuzzy concept→section inference.

What

Adds an advisory implied_related_section coordination finding: when a spec body mentions a distinctive keyword from an in-scope section title but does not already list that section under Related Sections, it's suggested (with the matched keyword, source paragraph, and a confidence score). Surfaced via REST + MCP; demo renders it behind API_FEATURES.impliedRelated. Adds ADR-035.

Design decisions

• Title keywords derived from in-scope sections (present + required + source-library), normalized with a stop-word list + light suffix stemmer; keywords appearing in >2 titles are suppressed (precision bias).
• Confidence is advisory and fixed (0.72 base, +0.08/extra keyword, cap 0.92).
• Review fix: sections already explicitly cited in the body are suppressed (they're covered by related_cited_not_listed) — prevents double-findings on the same section.

Testing

• Unit + integration 14/14 (run on an isolated DB during review)
• pnpm build, pnpm lint, redocly lint openapi.yaml
• Conduit→firestopping implied; already-listed → none; generic word → none; explicitly-cited → no duplicate finding
• CI green

🤖 Implemented by Codex (GPT-5.5 xhigh), reviewed + adversarially re-reviewed by Claude Opus 4.8 (one P2 precision fix applied). Closes #261.

Summary by CodeRabbit

• New Features

  • Added implied related-section suggestions in coordination reports to highlight likely missing section references.
  • Expanded the demo UI and report summaries to show the new suggestion type and its confidence details.

• Bug Fixes

  • Improved matching rules to reduce false positives from generic wording and avoid duplicates when sections are already listed or cited.

• Documentation

  • Added an ADR describing the new suggestion behavior and its review-time guidance.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 78cc13dd-8a3a-420c-9edf-3e986d9f30d7

📥 Commits

Reviewing files that changed from the base of the PR and between a1d1c63 and 08ea023.

📒 Files selected for processing (11)

• docs/adr/035-implied-related-section.md
• examples/web_ui_demo/js/coordination.js
• examples/web_ui_demo/js/features.js
• openapi.yaml
• src/coordination/implied-related.test.ts
• src/coordination/implied-related.ts
• src/coordination/index.ts
• src/db/queries/coordination-implied.ts
• src/db/queries/coordination.integration.test.ts
• src/db/queries/coordination.ts
• src/mcp/tools.ts

---

📝 Walkthrough

Walkthrough

Adds an advisory implied_related_section finding, its title-keyword detection, report aggregation, schema updates, and demo UI rendering.

Changes

Implied related-section detection

Layer / File(s)	Summary
Keyword detector and ADR docs/adr/035-implied-related-section.md, src/coordination/implied-related.ts, src/coordination/index.ts, src/coordination/implied-related.test.ts	ADR-035 defines the implied-related finding, the detector normalizes section titles and paragraph text, exports the matcher APIs, and unit tests cover match and suppression cases.
Report assembly and query src/db/queries/coordination-implied.ts, src/db/queries/coordination.ts, src/db/queries/coordination.integration.test.ts	The coordination report query reads catalog titles and paragraphs for implied matching, merges implied_related_section findings into the report, counts them in the summary, and integration tests cover the new flow.
Schema and demo UI openapi.yaml, examples/web_ui_demo/js/features.js, examples/web_ui_demo/js/coordination.js, src/mcp/tools.ts	The OpenAPI schema adds the new finding variant and summary counter, the demo UI gates and renders the finding with a feature flag, and the MCP tool description text is rewrapped.

Sequence Diagram(s)

sequenceDiagram
  participant getCoordinationReport
  participant readImpliedRelatedFindings
  participant buildTitleKeywordIndex
  participant findImpliedRelatedSections
  participant buildFindings
  participant summarize
  getCoordinationReport->>readImpliedRelatedFindings: load catalog, paragraphs, and classified refs
  readImpliedRelatedFindings->>buildTitleKeywordIndex: build title keyword index
  readImpliedRelatedFindings->>findImpliedRelatedSections: scan spec bodies for implied matches
  getCoordinationReport->>buildFindings: merge implied findings into report findings
  getCoordinationReport->>summarize: count implied_related_section findings

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• wrzonance/SpecR#241: Similar coordination-report schema and aggregation changes that added another finding variant to the same report model.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-261

---

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