[Story]: Onboarding-blueprint freshness check (AI)

[adoLime]

User Story

As an Admin/PM, I want the AI to regularly check how up-to-date each role-specific onboarding blueprint is, so that onboarding content does not silently go stale and I get concrete suggestions for what to fix.

Context & Motivation

• Type: Functional (Onboarding / AI Quality)
• Parent epic: 06 EPIC - Onboarding Journey & Digital Adoption #55 (06 EPIC – Onboarding Journey & Digital Adoption)
• Teams: team:ai (freshness agent), team:backend (scheduler + flag storage)
• Sister stories: [Story]: Missing-runbook / missing-ADR detection #115 (missing-runbook / missing-ADR detection) and the stale-threshold config in [Story]: Configurable stale-artifact threshold #116 — both should ideally share the same freshness agent / infrastructure to avoid duplicate scans.

Acceptance Criteria

• A scheduled and manually-triggered check evaluates every role blueprint against the current project artefacts in the index.
• The check uses a dedicated freshness agent (separate from the general RAG / chat agent) with its own prompt and tool access.
• Detection covers at minimum the following criteria list:
  • Broken link in a step's citation.
  • Referenced artefact deleted or renamed in the source system.
  • Referenced artefact content changed substantially since the blueprint step was created (configurable threshold, see [Story]: Configurable stale-artifact threshold #116).
  • Inconsistencies between blueprints of different roles (same component described in conflicting ways, or a step present in one role's blueprint but missing in another where it would be expected).
• Each finding carries: blueprint, step, criterion hit, severity, evidence (chunk + source).
• For every finding the agent produces a concrete remediation suggestion (e.g. "regenerate step from current artefact", "add runbook template for component X", "merge duplicate step").
• Findings + suggestions are surfaced to PM/Admin (dashboard panel + per-blueprint view).
• No silent auto-overwrite of PM manual edits — the agent flags and suggests, the PM decides.
• The agent is re-runnable on demand and produces a stable finding id so duplicates across runs are suppressed.

Sub-Tasks (by team)

• AI — implement the dedicated freshness agent: prompt, tool list, criteria list (above), grounded remediation-suggestion generator; reuse [Story]: Anti-hallucination guardrails #105 grounding rules.
• Backend — schedule + on-demand trigger; store findings (blueprint / step / criterion / evidence / suggestion); deduplicate across runs; expose findings endpoint.
• Frontend — dashboard panel for freshness flags + suggestion list; per-blueprint freshness view; filter by severity / role / component.
• PM/Admin — accept / dismiss / act-on-suggestion flow (low prio: direct "apply suggestion" action in a later iteration).

Dependencies

• [Story]: Hard-coded onboarding path per role #108 (default paths), [Story]: Onboarding path generator v0 (AI-generated from artifacts) #163 (AI generation — produces the blueprints we check), [Story]: Configurable stale-artifact threshold #116 (stale-threshold config), [Story]: Anti-hallucination guardrails #105 (grounding guardrails), [Story]: Missing-runbook / missing-ADR detection #115 (sister detection — share agent infra), [Story]: Indexing pipeline — chunk, embed & store canonical artifacts (source-agnostic) #162 (indexing pipeline — source of current artefacts).