PLAN.md

IntelligenceX Chat/Tools Decoupling Plan

Objective

Build a contract-first architecture where:

• Chat is generic orchestration only.
• Tools/packs self-describe routing, handoff, setup, and recovery behavior.
• Adding a new pack/tool does not require Chat hardcoded logic edits.
• Legacy fallback heuristics in Chat are removed.

Checkpoint Updates (2026-03-01)

• PR #974 merged: replace reflection/object retry-policy test hooks with typed test contract (RetryProfileSnapshot).
• PR #975 merged: centralize pack-id normalization in ToolSelectionMetadata.NormalizePackId(...) and delegate Chat bootstrap normalization to Tools.
• PR #976 merged: make planner candidate selection core static with explicit ToolOrchestrationCatalog input (keep compatibility wrapper for existing test reflection contract).
• Architecture guardrails active in Chat to prevent reintroduction of legacy pack-capability fallback source files/symbols.

Checkpoint Updates (2026-03-02)

• PR #985 merged: generic runtime pack toggles are fully list-driven (EnabledPackIds/DisabledPackIds) across app/client/host/profile paths.
• Startup bootstrap visibility landed end-to-end (structured telemetry + status parsing + UI surfacing for runtime/tool-pack loading progress).
• Startup bootstrap telemetry now includes ordered phase timings + slowest-phase summary so UI can explain where startup time is spent.
• ToolRegistry now hard-fails registration when Routing.PackId or Routing.Role is missing (strict-mode toggle still controls explicit-vs-inferred source).
• Startup diagnostics now include per-pack registration progress (pack_register_progress) + slow-registration summaries, and Chat app status parsing surfaces registration activity during runtime warmup.
• Turn watchdog now surfaces phase-aware in-flight wait hints before first token (awaiting ack/model/tool output) and mirrors that in header status for long-running turns.
• Service now emits early request/model-phase progress markers before thread binding, weighted tool-subset model calls, and model resolution so users see immediate in-flight status instead of silent 30s+ gaps.
• Turn metrics now include phase timings for ensure_thread, weighted subset-selection, and model-resolution, and app debug summary surfaces those phase costs directly.
• Chat app debug summary now highlights the slowest per-turn startup stage (ensure_thread, weighted_subset, resolve_model) to explain first-token latency at a glance.
• Chat app profile persona normalization no longer hardcodes AD-specific role hints (for example active directory/ad engineer), keeping persona shaping generic.
• Startup telemetry split now exposes pack_register and registry_finalize phase timings (plus total registry time) so post-load delays are attributable without guesswork.
• Chat app sidecar copy targets now filter missing artifacts before copy, preventing transient .psd1 MSB3030 failures during app test/build runs.
• Tool health diagnostics now resolve pack ids from explicit routing contracts only (legacy metadata/suffix fallback removed).
• Tool health pack-info discovery now uses routing role contracts only (legacy name-suffix _pack_info fallback removed from probe selection/smoke planning).
• Chat service bootstrap no longer depends on _toolPackIdsByToolName runtime mapping; orchestration catalog is built directly from registered tool contracts.
• ToolOrchestrationCatalog no longer accepts registered pack-id fallback maps; pack identity comes from routing contracts only.
• Chat list_tools category shaping now uses declared tool category metadata only (generic normalization); no pack-id fallback/category alias maps remain in Chat service.
• Regression coverage now proves Chat does not auto-switch packs after a failed tool call, even when tools from other packs are available.
• SQLite profile migration now preserves legacy enable_*_pack intent by translating into pack-id lists before deprecated columns are dropped.
• Regression coverage added for legacy pack-toggle migration and unknown-required-column insert backfill behavior.
• PR #986 merged: planner prompt no longer emits inferred pack/pack_aliases; Chat planner context stays generic (category/family/tags) while routing search tokens remain metadata-backed.

Audit Corrections (2026-03-03)

• Decoupling cleanup: AD domain guardrail hint text is now capability-based (no hardcoded tool ids in user-facing guidance).
• Stabilization hotfix: finalize-time host structured next-action replay now blocks stale host-target replays when user/assistant host hints conflict.
• Stabilization hotfix: finalize-time single-host scope-shift guard now evaluates raw user intent (not routed rewrite payload), reducing stale AD0-style replay loops on contextual follow-ups.
• Closed: Chat bootstrap now discovers built-in packs generically from tool assemblies/descriptors in ToolPackBootstrap (no hardcoded per-pack bootstrap chain).
• Closed: host-hint helpers were re-scoped into ChatServiceSession.HostHints.cs (fallback-era file naming removed).
• Hotfix landed: stale structured-next-action carryover replay now suppresses self-loop replays (same tool + equivalent args) and rejects host-hint-conflicting carryover execution.
• Hotfix landed: deferred startup metadata flow no longer skips metadata sync purely because authentication is initially unknown (skip now applies only when interactive login is already in progress).
• Hotfix landed: startup bootstrap status publishing now stays visible while connected startup metadata sync is in progress.
• Closed (mitigated): server-scoped tooling bootstrap cache now reuses prior bootstrap snapshots across reconnect/session churn, avoiding repeated full pack bootstrap on warm path.
• Hotfix landed: carryover structured-next-action replay now accepts compact non-question follow-ups even when continuation expansion is unavailable, while still rejecting contextual-anchor and question turns.
• Hotfix landed: carryover structured-next-action replay now treats compact contextual scope-shift follow-ups (for example "other DCs") as fresh planning turns, preventing stale single-host auto-replay loops.
• Hotfix landed: Chat service now suppresses duplicate final ChatResultMessage publishes for the same request/thread/text to prevent repeated assistant finals.
• Hotfix landed: session header status now keeps startup-pending messaging while metadata/tool-pack readiness is still unresolved (no premature "Ready" flip).
• Regression coverage added: two-turn carryover scenario now proves go ahead follow-up replays queued structured next-action tool calls (host carryover call-id path).
• Hotfix landed: compact follow-up question turns no longer force execution-blocker/cached-evidence rewrite at finalize (tool-capability questions keep direct conversational handling).
• Hotfix landed: cached evidence fallback now requires explicit tool-name match when the user references a specific tool id, preventing unrelated stale evidence reuse.
• Hotfix landed: deferred startup metadata sync now waits for authenticated runtime state and is re-queued after successful login completion, avoiding premature metadata churn during sign-in.
• Hotfix landed: host structured next-action replay now skips same-tool/same-arguments loops (next_action_self_loop) to avoid repeated AD0-style replay churn.
• Hotfix landed: carryover structured-next-action auto-replay now blocks repeated identical tool+argument replays until fresh context is provided (for example explicit host pin), reducing AD0-style replay churn across turns.
• Hotfix landed: carryover structured-next-action auto-replay now also blocks same-tool single-host replay loops when argument payload drifts but host scope remains unchanged, unless fresh host context is provided.
• Hotfix landed: carryover replay host-hint gating now incorporates assistant draft host targets (not just user text), preventing stale single-host (AD0) replay after multi-host follow-up plans.
• Hotfix landed: carryover host-hint gating now treats multi-host follow-up hints as incompatible with single-host auto-replay, preventing mixed-hint (AD0 + AD1/AD2) stale carryover execution loops.
• Hotfix landed: carryover replay freshness/scope guards now evaluate raw user request text even when assistant draft host hints are appended for mismatch detection, preventing AD0-only replay loops from assistant-draft host echo.
• Hardening landed: carryover replay now passes raw replay-intent text and assistant host-hint context as separate inputs (no in-band marker protocol), reducing marker-collision risk while preserving multi-host mismatch blocking.
• Startup stabilization: transient runtime reconnects now preserve interactive auth state when prior state is authenticated or login is in-flight (unless explicit unauthenticated probe exists), reducing sign-in/connect-disconnect churn.
• Startup visibility: connect flow now surfaces per-attempt pipe connect/retry timeout and retry-delay progress in status text (instead of generic "starting runtime" only).
• Validation checkpoint: dotnet run --project IntelligenceX.Cli/IntelligenceX.Cli.csproj --framework net8.0 -- analyze validate-catalog --workspace . passes with 0 error(s), 0 warning(s) on this branch.
• Hotfix landed: contextual follow-up detection now evaluates the Follow-up: tail from legacy continuation expansion when deciding carryover replay eligibility.
• Closed: standalone lowercase ad alias auto-routing was removed from domain-intent signal resolution to keep Chat lexical routing generic.
• Hotfix landed: continuation subset reuse now exits when follow-up text explicitly names a tool outside the remembered subset (for example eventlog_live_query), forcing fresh candidate routing.
• Startup visibility hotfix: header status now keeps a bounded runtime lifecycle timeline (status tooltip + debug panel) so long connect/auth/bootstrap phases are traceable instead of collapsing into a single generic chip.
• Startup/turn diagnostics hotfix: routing-meta activity timeline labels now include selected strategy and tool counts (strategy, selected/total) instead of a generic route strategy marker.
• Stabilization hotfix: finalize-time execution blocker now skips cached-evidence substitution for explicit tool-capability questions (for example eventlog_evtx_query?), preserving direct conversational/tool-availability answers.
• Startup perf hotfix: plugin duplicate detection now has a loaded-assembly fast-path (skip before dependency preload/reflection), reducing first-session tool bootstrap stalls and preventing avoidable reconnect churn during deferred metadata sync.
• Stabilization hotfix: explicit tool-id follow-ups now suppress pending-action/carryover auto-replay rewrites, and escaped Markdown tool ids (for example eventlog\_evtx\_query) are recognized by cached-evidence gating.
• Startup resilience hotfix: deferred startup metadata phases (hello, list_tools, auth_refresh) now retry once on transient disconnect errors to reduce "connected but packs/catalog missing" startup failures.
• Startup/turn UX hotfix: assistant final-message replacement now reuses the most-recent assistant bubble when only System/Tools rows followed (no intervening user), preventing duplicate assistant finals during retry/reconnect churn.
• Stabilization hotfix: carryover structured-next-action replay eligibility now evaluates compact follow-up intent from raw user text (not routed payload rewrite text), restoring go ahead follow-up auto-execution after pending-action routing hints.
• Stabilization hotfix: domain-intent payload parsing now handles invalid UTF-16 input safely (catches ArgumentException in addition to JsonException) to keep compact follow-up expansion Unicode-safe.
• Contract-alignment cleanup: routing/output lifecycle tests now reflect strict routing-contract enforcement and single-meaningful-final result policy for the same request/thread pair.
• Startup stability hotfix: deferred startup metadata sync now supports rerun requests when login succeeds during an in-flight sync, preventing dropped post-login hello/list_tools/auth_refresh refreshes and stale tool-catalog visibility.
• Stabilization hotfix: continuation subset reuse now recognizes escaped Markdown tool ids (for example eventlog\_live\_query) as explicit tool references, forcing fresh routing when follow-ups switch tools across packs.
• Regression coverage expanded: deferred startup metadata rerun path now has explicit dispatch-safety tests (rerun requested + connected + not shutting down) alongside busy-sync rerun-request checks.
• Stabilization hotfix: explicit quoted tool-descriptor follow-ups (including multiline/backticked catalog snippets and invisible format chars inside tool ids) now bypass finalize-time cached-evidence fallback rewrites and stay on direct tool-capability answer paths.
• Startup/dispatch stabilization hotfix: SendPromptAsync now claims startup/send lifecycle state atomically behind the active-turn lock, preventing manual-send vs auto-dispatch races that produced duplicate assistant replies.
• Carryover stabilization hotfix: contextual compact follow-up questions now block stale single-host structured replay when thread evidence is multi-host, while short acknowledgement questions remain replay-eligible.
• Startup UX hotfix: login-completed status updates now queue deferred startup metadata sync before publishing connected status, avoiding transient "ready" flips while tool-pack startup is still pending.
• Startup UX hotfix: startup pending/status overlay now includes browser sign-in-in-progress states, and startup-time reconnect churn surfaces explicit reconnect-sync status (instead of generic disconnected text).
• Startup UX hotfix: connected-phase bootstrap progress now preserves Runtime connected... wording (with cause metadata_sync) instead of reverting to Starting runtime..., reducing status-chip connect/disconnect confusion while metadata sync is active.
• Startup/send hotfix: queued-after-login prompt deduplication now treats one-sided empty conversation ids as equivalent for normalized prompt text, preventing duplicate dispatch after startup/sign-in transitions.
• Contract guardrail expanded: bootstrap metadata tests now assert all canonical built-in tools register with explicit routing source + pack id + role under strict registration (not only _pack_info tools).
• Stabilization regression coverage: finalize host scope-shift guard now has explicit precedence tests proving raw user intent is used ahead of routed rewrite text when deciding stale single-host replay blocking.
• Catalog contract projection now includes setup requirements/hints, normalized handoff edges, and recovery-policy details (retryable_error_codes, alternate engines) in ToolOrchestrationCatalog.
• Contract-first domain intent alignment: runtime /act resolution now requires catalog-mapped action ids (no undeclared default-action fallback when custom routing action ids are registered), and domain host guardrail candidate detection no longer infers AD scope from tool-name patterns.
• Stabilization hotfix: ResolveDomainIntentActionCatalog now keeps all declared action ids per family as valid /act aliases (order-independent), while canonical clarification action ids are selected deterministically and ambiguous cross-family ids no longer rely on first-wins map order.
• Regression coverage now asserts cross-pack isolation in orchestration catalog: no ADPlayground -> DomainDetective handoff is inferred without explicit ToolHandoffContract edges.
• Live strict scenario validation: ad-ad0-then-all-dcs-followthrough-10-turn passes end-to-end in host runtime with cross-DC fanout (machine_name>=2) and no duplicate tool-call/output ids.
• Live strict scenario validation: ad-eventlog-tool-capability-followthrough-10-turn now guards explicit eventlog_evtx_query capability follow-ups against cached-evidence fallback regressions and passes end-to-end (10/10 turns) in host runtime.
• Live strict scenario validation: transcript-derived ad-other-dcs-go-ahead-followthrough-10-turn now passes end-to-end (10/10 turns), guarding continuation-style go ahead follow-through with cross-DC tool execution (machine_name>=2) and direct eventlog_evtx_query capability responses.
• Scenario-contract hardening: host runtime now supports explicit forbidden tool-input values (forbid_tool_input_values / forbidden_tool_inputs) and applies them in retry eligibility, assertion checks, and distinct-host fallback repair paths.
• Transcript guardrail hardening: ad-other-dcs-go-ahead-followthrough-10-turn continuation turns now explicitly forbid machine_name=AD0, and strict catalog tests lock this requirement.
• Added transcript-derived strict scenario seed ad-domainwide-reboot-followthrough-10-turn to guard AD0-baseline -> domain-wide non-AD0 continuation flow, explicit eventlog_evtx_query capability follow-up behavior, and DNS cross-pack routing in one 10-turn sequence.
• Forbidden host-input hardening: scenario contract enforcement now treats short-host and FQDN equivalents consistently (for example AD0 == AD0.ad.evotec.xyz) in retry gating, fallback target selection, and assertion checks.
• Live host validation rerun: ad-domainwide-reboot-followthrough-10-turn passes end-to-end (10/10 turns) with non-AD0 continuation turns staying off AD0/FQDN equivalents during distinct-host repair.
• Startup/send race hardening: manual resend now suppresses an equivalent prompt when the same queued-after-login turn is already in-flight, preventing duplicate assistant replies after usage-limit switch-account recovery.
• Transcript wording coverage refresh: strict cross-DC continuation scenarios now include explicit "those are correct DCs, go ahead" phrasing to lock replay suppression and non-AD0 fanout behavior.
• Stabilization hotfix: domain host-scope guardrail now blocks stale single-host AD-scope replay for compact scope-shift follow-ups when thread evidence is already multi-host, unless the user explicitly pins a single host.
• Stabilization regression coverage: domain host-scope guardrail now has explicit compact scope-shift replay tests (block stale single-host replay, allow explicit host pin, allow short acknowledgement questions).
• Live strict validation rerun: transcript-derived ad-other-dcs-go-ahead-followthrough-10-turn, ad-domainwide-reboot-followthrough-10-turn, and ad-ad0-then-all-dcs-followthrough-10-turn all pass end-to-end (10/10) after host-scope replay hardening.
• Stabilization hotfix: AD monitoring ADWS probe port normalization now treats non-positive port overrides as default 9389 (instead of clamping to 1), preventing false ADWS-down endpoint probes (net.tcp://<dc>:1/...).
• Transcript-derived strict scenario seed added: ad-ldap-go-ahead-followthrough-8-turn to lock "scope confirmed -> go ahead executes LDAP diagnostics" continuation behavior and explicit tool-capability follow-through.
• Live strict validation: ad-ldap-go-ahead-followthrough-8-turn passes end-to-end (8/8) after ADWS port normalization hardening.
• Startup/send dedupe hardening: queued-after-login duplicate suppression now also handles startup/login windows where both prompts have missing conversation ids but equivalent normalized text, reducing duplicate assistant greetings after switch-account recovery.
• Regression coverage expanded: queue dedupe tests now explicitly lock both-missing-conversation-id startup fallback behavior for manual resend suppression during in-flight queued-after-login dispatch.
• Catalog contract validation checkpoint: analyze validate-catalog --workspace . passes with 0 error(s), 0 warning(s) after startup/login and ADWS hardening batches.
• Stabilization hotfix: weighted/planner routing subsets now preserve explicitly requested tool ids (including escaped markdown forms such as eventlog\_evtx\_query), preventing false "tool not active" follow-up responses when the tool is registered.
• Regression coverage expanded: routing tests now assert explicit escaped tool-id inclusion in weighted subset selection and limit-bound planner backfill (EnsureMinimumToolSelection) replacement behavior.
• Live strict validation rerun: ad-eventlog-tool-capability-followthrough-10-turn passes end-to-end (10/10) with explicit eventlog_evtx_query capability turns executing EventLog tools in-session.
• Scenario-contract clarity hardening: forbidden tool-input directives now render as key not-in [v1|v2] in execution contracts/retry prompts (while parser stays backward-compatible with legacy key!=v1|v2), reducing model misreads that inverted non-AD0 constraints.
• Transcript-derived strict replay guardrail added: ad-other-dcs-transcript-replay-guardrail-10-turn now passes end-to-end (10/10) and locks "other DCs" follow-through with cross-DC execution, explicit non-AD0 follow-up turns, and direct eventlog_evtx_query capability handling.
• Transcript-derived strict fanout guardrail added: ad-c400-transcript-cross-dc-fanout-10-turn now passes end-to-end (10/10) and locks explicit 4-host non-AD0 fanout (AD1/AD2/DC1/ADRODC) after continuation phrasing that previously replayed AD0-only calls.
• Startup visibility hardening: startup/connect/reconnect status text now emits structured context tokens (phase startup_*, cause ...), and connected bootstrap status rewrites legacy cause-only suffixes to phase+cause so runtime-ready ambiguity is diagnosable from the header chip alone.
• Stabilization hotfix: no-text tool-output synthesis retry now runs only when review-loop mode is enabled, redaction is off, and at least one tool output succeeded; deterministic fallback is used first for redaction/tool-failure paths to avoid extra model rounds.
• Follow-through quality hardening: no-text synthesis prompts now include compact tool-argument context from executed calls (for example host/log/window selectors), reducing false "missing target context" narratives on sparse summaries.
• Startup UX hardening: shell header status chip now derives compact labels from structured startup phase/cause markers (startup_connect, startup_auth_wait, startup_metadata_sync) before generic fallback labels, improving visibility during connect/auth/bootstrap wait phases.
• Live strict rerun checkpoint after no-text/startup UX hardening: ad-c400-transcript-cross-dc-fanout-10-turn (10/10), ad-eventlog-tool-capability-followthrough-10-turn (10/10), and ad-ldap-go-ahead-followthrough-8-turn (8/8) all pass on this branch.
• Host decoupling cleanup: removed host-side tool-name-specific retry rewrite path (AD discovery, AD replication probe, DomainDetective summary) so runtime no longer mutates calls via hardcoded tool IDs; added architecture guardrail test to prevent reintroduction.
• Typed-surface guardrail hardening: added pack-wide source guardrail asserting typed-pipeline tools (RunPipelineAsync + ToolRequestBindingResult) do not regress to ad-hoc arguments?.Get.../arguments.Get... parsing across AD/DomainDetective/DnsClientX/System/EventLog/TestimoX/FileSystem/Email/PowerShell/OfficeIMO.
• Typed-envelope migration increment: ad_scope_discovery now emits ToolResultV2 envelopes (Error + OkFlatWithRenderValue) and is covered by typed-wrapper guardrail assertions.
• Typed-envelope standardization increment: AD shared base helpers now use ToolResultV2 (instead of direct ToolResponse) for required-argument errors, convention-mapped collection failures, and common AD success/error wrapper helpers; guardrail asserts ActiveDirectoryToolBase* files stay ToolResponse-free.
• Startup visibility increment: service now emits runtime-provider connect progress telemetry ([startup] provider_connect_progress ... with phase/status/elapsed), and app startup status parsing consumes it with send-safe publish override so first-turn provider connect latency is visible instead of silent.
• Decoupling guardrail increment: Chat architecture tests now fail if IntelligenceX.Chat.App or IntelligenceX.Chat.Service source reintroduces hardcoded tool-pack ids (testimox, active_directory, adplayground, domaindetective, dnsclientx, reviewer_setup).
• Contract-first routing increment: Chat routing scoring pack-hint resolution now uses explicit routing contract pack ids only (no ToolSelectionMetadata.TryResolvePackId(...) fallback), and architecture guardrail coverage locks this.
• Scenario-contract reliability increment: transcript strict scenario ad-eventlog-tool-capability-followthrough-10-turn now uses semantic contains-any assertion for eventlog tool availability (eventlog or event log) to avoid wording-only false failures.
• Live strict validation rerun: ad-eventlog-tool-capability-followthrough-10-turn passes end-to-end (10/10) after contract-only routing-hint cleanup and scenario assertion hardening.
• Contract-first routing decoupling increment: Chat tokenization no longer uses hardcoded compound-pack compact heuristics (ToolSelectionMetadata.IsKnownCompoundPackRoutingCompact); routing relies on natural-language tokens + explicit pack metadata aliases only.
• Live strict validation rerun: transcript-derived cross-pack/follow-up guardrail scenarios remain green after compound-token heuristic removal (ad-eventlog-tool-capability-followthrough-10-turn 10/10, ad-other-dcs-transcript-replay-guardrail-10-turn 10/10).
• Follow-up recovery hardening: compact continuation turns now trigger execution replan when the assistant emits structured linked "deferred execution" drafts with zero in-turn tool activity, preventing go ahead turns from settling on evidence-only summaries.
• Live strict validation rerun: ad-ldap-go-ahead-followthrough-8-turn passes end-to-end (8/8) after compact follow-up structured-draft recovery hardening.
• Regression fix (2026-03-04): finalize no-text recovery no longer issues an extra synthesis model round for redacted/tool-failure turns (RunChatOnCurrentThreadAsync_DoesNotAutoSwitchPacksAfterToolFailure and RunChatOnCurrentThreadAsync_RedactsToolOutputRecoveryFallbackWhenRedactionEnabled restored).
• Live strict rerun validation (2026-03-04): ad-c400-transcript-cross-dc-fanout-10-turn (10/10), ad-eventlog-tool-capability-followthrough-10-turn (10/10), and ad-ldap-go-ahead-followthrough-8-turn (8/8) pass after the no-text recovery gating fix.
• Startup UX wording hardening (2026-03-04): header status chip now upgrades generic connected unauthenticated Sign in to continue text to Sign in to continue loading tool packs while startup tools-loading is pending, improving startup cause clarity during auth wait.
• Language-neutral strict scenario increment (2026-03-04): added transcript-derived Polish scenario ad-pl-eventlog-capability-followthrough-10-turn to lock AD->EventLog capability follow-through without cached-evidence/no-tool fallback phrasing regressions.
• Live strict validation (2026-03-04): ad-pl-eventlog-capability-followthrough-10-turn passes end-to-end (10/10) with paired EventLog tool execution and no duplicate call/output ids.
• Startup visibility hardening (2026-03-04): send-safe bootstrap phases now publish even during startup turn/send waits (pack_register/load, plugin_load, scan/finalize), and connected sessions can still surface send-safe startup statuses when metadata-sync flags lag briefly.
• Contract-first domain-intent hardening (2026-03-04): Chat tool-routing no longer infers domain family from raw tool-name fallback in ResolveDomainIntentFamily(string toolName); family resolution now stays registry/catalog contract-based, with architecture guardrail coverage locking this.
• Transcript-snippet guardrail hardening (2026-03-04): Polish strict scenario ad-pl-eventlog-capability-followthrough-10-turn now uses the original multiline catalog-descriptor phrasing (eventlog_evtx_query · Event Log (EventViewerX) ...) that previously triggered cached-evidence fallback loops.
• Live strict validation rerun (2026-03-04): ad-pl-eventlog-capability-followthrough-10-turn remains green (10/10) with direct capability handling for the multiline descriptor follow-up and no cached-evidence fallback response.
• Documentation increment (2026-03-04): published contract-first onboarding guide for adding tool packs without Chat edits, including plugin contract schema examples (InternalDocs/agent-playbooks/chat-pack-contract-first-onboarding.md).
• Language-neutral routing validation checkpoint (2026-03-04): ChatServiceRoutingTrimTests suite passes (709/709), including Unicode ordinal parsing and compact follow-up routing safeguards.
• Routing-heuristic cleanup checkpoint (2026-03-04): Chat service no longer uses raw tool-name TryResolveDomainIntentFamily(toolName, ...) paths for domain-family routing decisions; remaining resolution is contract-first with definition metadata fallback only.
• Decision checkpoint (2026-03-04): strict pack-boundary isolation (DomainDetective vs ADPlayground) is now enforced by contract/cross-pack isolation tests; no implicit handoff is inferred without explicit ToolHandoffContract.
• Typed adapter increment (2026-03-04): added reusable ToolRequestAdapter<TRequest> abstraction in IntelligenceX.Tools.Common plus ToolBase.RunPipelineAsync(..., adapter) overload, and migrated dnsclientx_pack_info + domaindetective_pack_info to this adapter path.
• Typed adapter migration increment (2026-03-04): migrated domaindetective_checks_catalog, reviewer_setup_pack_info, and reviewer_setup_contract_verify to typed binder/adapter pipelines and standardized their envelopes on ToolResultV2; added guardrail coverage to keep these wrappers off raw arguments?.Get* parsing.
• Typed binder backfill increment (2026-03-04): migrated system_bitlocker_status, system_installed_applications, system_network_adapters, system_patch_compliance, eventlog_channels_list, and eventlog_providers_list to typed pipeline binders; added folder-wide source guardrail requiring typed binder usage across migrated non-AD packs.
• Documentation cleanup increment (2026-03-04): refreshed ADR wording in InternalDocs/architecture/adr-0001-chat-tools-contract-boundary.md so cross-pack fallback references are historical/current-state accurate (no stale present-tense behavior claims).
• Fallback-marker cleanup checkpoint (2026-03-04): verified runtime Chat service no longer contains legacy cross-pack fallback telemetry/constants/symbols; only active projection-fallback metadata markers remain (projection_fallback_*) for view-argument recovery diagnostics.

Planning Extension (2026-03-25)

• Startup preview truthfulness hardening (2026-03-29): persisted descriptor-preview startup now emits explicit descriptor preview bootstrap telemetry/cache-mode/status detail instead of replaying stale full-bootstrap timings from a prior live activation.
• Startup phase telemetry rename (2026-03-29): live bootstrap now emits explicit descriptor_discovery, pack_activation, and registry_activation_finalize phases, and app summaries/status text now reflects the descriptor-first lifecycle instead of legacy pack load / pack register wording.
• Startup disabled-pack activation trim (2026-03-29): descriptor-only disabled known built-ins no longer consume raw pack_load_progress activation steps on the default bootstrap path; availability still publishes, but disabled toggles now avoid both constructor work and fake activation-progress churn.
• Versioned descriptor snapshot contract (2026-03-29): persisted tooling bootstrap cache now writes and prefers an explicit versioned descriptor/capability snapshot payload for preview-safe metadata (hello/list_tools/first-paint), with legacy top-level fallback and fail-open diagnostics when the nested descriptor snapshot schema is stale.
• Workspace output probing hardening (2026-03-29): built-in pack assembly resolution now honors EnableWorkspaceBuiltInToolOutputProbing on the live load path too, so repo-local bin scanning stays opt-in for dev/bootstrap recovery instead of leaking into default startup.
• Built-in discovery metadata-first refactor (2026-03-29): default built-in assembly allowlist now starts from KnownBuiltInPackBootstrapMetadata assembly identities, with dependency-graph and embedded manifest reads left as compatibility fallbacks instead of primary discovery sources.
• Descriptor-first first-paint startup (2026-03-29): app startup/connection flows now treat persisted-preview hello policy snapshots as sufficient metadata for first paint, seed plugins from hello, skip inline list_tools when descriptor metadata is already present, and queue the final metadata refresh in the background instead of blocking startup on full activation semantics.
• Activation-on-demand status truthfulness (2026-03-29): deferred chat pack activation now emits explicit in-progress routing status before descriptor-matched or handoff-target pack activation work starts, then follows with the existing activated/ready notices once live tool schemas are actually available.
• Phase-based bootstrap reporting compatibility (2026-03-29): shared/app/UI startup summaries and signal thresholds now resolve canonical descriptor_discovery, pack_activation, and registry_activation_finalize durations from phase telemetry first, using legacy aggregate fields only as backward-compatible fallback.
• Startup release-gate coverage expansion (2026-03-29): app/runtime tests now explicitly lock zero-pack startup sparsity, plugin-only persisted-preview metadata/snapshot projection, and descriptor-first shell bootstrap summary labels so these startup modes stay protected without depending on the externally blocked shared Chat test project.
• Known built-in pre-activation filtering (2026-03-29): default startup now trims disabled known built-in assemblies out of live discovery before assembly/type reflection work, while still publishing descriptor-only disabled availability and preserving truthful on-demand disabled-pack activation results.
• Workspace probing opt-in hardening (2026-03-29): workspace/project-output assembly fallback now stays isolated behind explicit opt-in/test-only workspace-root helpers, and known built-ins selected without a resolvable trusted path now report truthful unavailable availability instead of silently disappearing from on-demand activation results.
• Structured-only runtime self-report classification checkpoint (2026-03-29): app/shared runtime-introspection classifiers no longer promote raw cue-word asks like model / tools into runtime self-report mode; trusted ix:runtime-self-report:v1 directives now carry runtime mode explicitly, while legacy lexical-fallback prompt branches stay covered only through explicit precomputed-analysis tests.
• Multilingual prompt-mode release-gate checkpoint (2026-03-29): app prompt/gating tests now explicitly lock non-English broad capability asks (Co mozesz zrobic dla mnie?) into conversational capability mode, and also lock plain cue-word runtime asks out of implicit runtime self-report mode unless trusted ix:runtime-self-report:v1 metadata is present.
• Literal-confirmation routing-prelude checkpoint (2026-03-29): shared Chat routing tests now explicitly prove bare confirmations like go ahead / go ahead? stay fresh turns with no structured continuation context, compact follow-up flag, or continuation expansion unless real pending-action/continuation state already exists.
• Shape-based capability boundary checkpoint (2026-03-29): app capability-question classification no longer depends on exact English internal-noun blockers like model / tool / plugin; it now uses broader open-ended question shape so broad capability asks still enter conversational capability mode while short runtime/inventory asks remain out through dedicated classifier and prompt regressions.
• Obsolete runtime cue-catalog removal checkpoint (2026-03-30): the old English internal-noun blocker catalog (RuntimeSelfReportCueCatalog) is now deleted entirely after the app/runtime capability boundary moved to shape- and directive-based handling, and shared host tests no longer freeze that unused English-only list in place.
• Contract-backed host-target hint checkpoint (2026-03-30): host retry/scenario prompts no longer tell the model to infer or default remote host targets from prose; they now instruct it to use declared host-target arguments only when concrete thread inputs already exist, otherwise ask for the minimal missing target input instead of guessing defaults.
• Known-host hint consolidation checkpoint (2026-03-30): duplicate “remaining discovered DCs/hosts” prose policy was removed from host retry/scenario prompts; distinct-target coverage guidance now lives only in the structured known-host hint that appears when concrete prior host/DC inputs actually exist.
• Ordered known-host summary checkpoint (2026-03-30): the structured known-host hint now reports ordered distinct host/DC candidates from prior tool inputs instead of carrying a second prose rule about distinct-target coverage; prompt tests now lock duplicate filtering and the removal of the old narrative instruction.
• No-text warning known-host checkpoint (2026-03-30): host no-text fallback warnings now surface the same structured known-host/DC summary when concrete prior targets exist, so recovery warnings keep contract/locality context and thread-known target context together.
• Canonical startup phase-duration contract checkpoint (2026-03-31): startup bootstrap telemetry now ships pre-resolved canonical descriptor/activation/finalize durations from C#, and the shell consumes those canonical fields instead of duplicating legacy phase-id fallback mapping in JavaScript.
• Persisted preview fingerprint alignment checkpoint (2026-03-31): tooling bootstrap cache now persists the actual deferred descriptor-preview fingerprint computed from bootstrap options, avoiding false persisted-preview fast-path misses caused by rehashing the fuller live snapshot shape.
• Split tooling bootstrap into two explicit phases: descriptor_discovery and pack_activation, with startup/status telemetry for both phases.
• Ensure disabled packs are filtered before constructor/reflection-heavy activation work so pack toggles reduce startup cost, not only runtime exposure.
• Keep workspace/project-output assembly probing available only for explicit dev/bootstrap repair modes, not on the default warm path.
• Make built-in pack discovery descriptor/manifest-first so the embedded built-in assembly manifest remains transitional metadata instead of a hard architectural dependency.
• Add activation-on-demand for packs/tools selected after descriptor-only startup, with truthful status emission while activation is in progress.
• Remove remaining English-triggered control flow for runtime/capability classification; English descriptions/examples remain allowed, but user-intent routing must stay structure-first or contract-backed.
• Add release gates for zero-pack startup, plugin-only startup, persisted descriptor-preview startup, and multilingual runtime-introspection/capability asks that do not rely on borrowed English cue words.

Hard Decisions (Locked)

• D1 Remove Chat-owned cross-pack fallback execution logic (no legacy compatibility layer).
• D2 Keep resilience only inside tools/engines (for example CIM -> WMI), not in Chat routing.
• D3 Make routing metadata explicit and contract-validated for every tool.
• D4 Prefer typed request/response models in tools; keep JSON/text as transport envelope only.
• D5 Treat pack boundaries as strict: DomainDetective != ADPlayground unless contracts declare handoff.

Current Gaps To Eliminate

• G1 Chat has hardcoded cross-pack fallback builders in IntelligenceX.Chat/IntelligenceX.Chat.Service/ChatServiceSession.PackCapabilityFallback.cs.
• G2 Chat triggers fallback replay in IntelligenceX.Chat/IntelligenceX.Chat.Service/ChatServiceSession.ChatRouting.NoExtractedFinalize.cs.
• G3 Chat pack preflight no longer depends on _pack_info/_environment_discover suffix selection.
• G4 Chat deterministic routing now relies on contract metadata rather than suffix/prefix family-key inference paths.
• G5 Tools metadata enrichment hardcoded pack/category inference maps removed from IntelligenceX/Tools/ToolSelectionMetadata.cs in favor of contract/tag metadata.
• G6 Fallback behavior is partly metadata-driven, partly hardcoded; split must become tool-contract only.
• G7 Warm-path tooling bootstrap still computes an expensive discovery fingerprint before persisted preview reuse, so startup can pay plugin scan/probe costs even when cache data is valid.
• G8 Disabled packs are still discovered/instantiated before runtime enablement is applied, so EnabledPackIds/DisabledPackIds are not yet strong startup-cost controls.
• G9 Built-in pack onboarding still depends on Chat-owned assembly discovery metadata instead of pack-owned descriptor exports.
• G10 App/runtime introspection classification still uses English runtime cue words in control flow, which conflicts with language-neutral routing goals.
• G11 Host prompt hints still carry some runtime fallback guidance (for example remote-host inference) that should move into explicit tool/setup contracts.

Phase 0 - Baseline And Guardrails

1. Create ADR in InternalDocs/architecture/ defining the no-legacy contract-first target.
2. Add temporary architecture test that fails if new TryBuildCross*Fallback* methods appear in Chat.
3. Add temporary architecture test that fails if Chat introduces new pack-name switch chains for fallback/routing.
4. Add migration tracker section in TODO.md linking this PLAN.md.
5. Freeze net-new fallback logic in Chat (explicit policy: no new fallback PRs accepted).

Phase 1 - Expand Tool Contracts (Tools Layer)

1. Add a dedicated ToolRecoveryContract in IntelligenceX/Tools (transient retry policy, not cross-pack routing).
2. Add a dedicated ToolRoleContract or equivalent role fields in ToolRoutingContract (pack_info, environment_discover, operational, resolver, diagnostic).
3. Add explicit ToolHandoffContract types in IntelligenceX/Tools for source entity -> target argument mappings.
4. Add explicit ToolSetupContract types for prerequisites and user-facing setup hints.
5. Add RoutingSource (explicit|inferred) and strict-mode gate ToolRegistry.RequireExplicitRoutingMetadata to enforce explicit routing metadata during migration.
6. Extend ToolDefinition validation in IntelligenceX/Tools/ToolRegistry.cs to require explicit pack/routing role metadata.
7. Remove implicit pack/category/domain-family inference pathways from IntelligenceX/Tools/ToolSelectionMetadata.cs (or gate them behind hard-fail mode that is always enabled).
8. Enforce one canonical source for domain intent family/action mapping from routing contracts.
9. Ensure all _pack_info tools define explicit routing contracts (not inference).
10. Keep ToolPackGuidance as rich documentation contract, but make routing-critical fields available without calling tools.

Phase 2 - Build Runtime Orchestration Catalog (Chat Reads Contracts, Not Names)

1. Introduce ToolOrchestrationCatalog in Chat bootstrapping built from ToolRegistry.GetDefinitions().
2. Include in catalog: pack id, role, scope/operation/entity/risk, domain family/action, setup requirements, handoff edges, recovery policy.
3. Replace direct _toolPackIdsByToolName and suffix inference consumers with catalog queries.
4. Keep Chat startup diagnostics but add new contract health metrics (missing role, missing handoff schema, invalid setup contracts).
5. Surface catalog health in existing routing policy UI payloads.
6. Add runtime policy toggle RequireExplicitRoutingMetadata (CLI/profile/session policy) to support strict contract-only registration rollout.

Phase 3 - Remove Chat Fallback Engine

1. Delete cross-pack fallback builders from ChatServiceSession.PackCapabilityFallback.cs.
2. Delete fallback host-hint helpers tied to that flow from ChatServiceSession.HostHints.cs.
3. Remove _packCapabilityFallbackContractsByPackId state from ChatServiceSession.cs.
4. Remove RebuildPackCapabilityFallbackContracts(...) call in ChatServiceSession.ProfilesAndModels.cs.
5. Remove fallback replay branch in ChatServiceSession.ChatRouting.NoExtractedFinalize.cs.
6. Keep normal model-driven retries/review loops; do not auto-run substitute tools in Chat.
7. For resilience use-case support, route it into tool internals (engine/tool package), not Chat orchestration.

Phase 4 - Replace Heuristics With Contracts

1. Replace pack preflight suffix detection in ChatServiceSession.PackPreflight.cs with role-based contract selection.
2. Replace deterministic family key heuristics in ChatServiceSession.ChatRouting.RoutingScoring.cs with contract pack/role fields.
3. Ensure domain-intent signals in ChatServiceSession.ToolRouting.DomainIntentSignals.cs come from registered contract signals only.
4. Keep Unicode-safe ordinal parsing in ChatServiceSession.PendingActions.IntentParsing.cs (this is generic and should remain).
5. Remove remaining routing paths that depend on tool name prefix assumptions when contract fields exist.

Phase 5 - Tool Pack Migration (Domain Separation + Easy Additions)

1. Migrate ADPlayground pack tools to explicit role/handoff/setup/recovery contracts.
2. Migrate DomainDetective pack tools with explicit domain/public handoff contracts.
3. Migrate DnsClientX pack tools with explicit resolver-vs-posture role split.
4. Migrate System/EventLog/TestimoX/FileSystem/Email/PowerShell/OfficeIMO packs the same way.
5. Add contract tests per pack proving no Chat changes are needed to register and route new tools.
6. Add one synthetic sample pack in tests to prove plug-in registration works without Chat edits.

Phase 5A - Descriptor-First Startup And Lazy Activation

1. Add a lightweight persisted PackDescriptorSnapshot / capability snapshot contract that includes pack ids, tool ids, roles, execution scope, setup/auth/mutability metadata, handoff edges, and version/fingerprint data without requiring full tool activation.
2. Refactor startup so persisted descriptor snapshots can satisfy hello, list_tools, and app first-paint before full pack activation completes.
3. Split runtime bootstrap telemetry into explicit descriptor_discovery, descriptor_cache_hit, pack_activation, and registry_activation_finalize phases.
4. Make pack enablement filtering happen before constructor/reflection-heavy activation work for built-in and plugin packs.
5. Make workspace bin probing and other repair-oriented discovery fallbacks opt-in for dev/bootstrap recovery only, not part of the default warm path.
6. Add activation-on-demand for descriptor-known tools/packs so the runtime can activate only the selected capability area when a turn first needs it.
7. Add zero-pack, plugin-only, descriptor-preview, and lazy-activation regression suites with latency budget assertions.

Phase 5B - Language-Neutral Turn Classification And Prompting

1. Remove English cue-word gating from app/runtime capability and runtime-introspection classifiers while keeping question-shape, punctuation, and structured-context signals.
2. Ensure user-intent routing, safety gating, and execution decisions never depend on literal English phrases when equivalent structured contract/state is available.
3. Keep English descriptions, examples, and prompt text allowed as explanatory metadata, but prevent those strings from becoming routing/safety control flow.
4. Move remote-target/default-host inference hints out of host prompt text and into explicit tool/setup/execution contracts where they can be tested and surfaced consistently.
5. Add multilingual tests covering runtime introspection and capability questions that do not rely on borrowed English nouns like model, tool, or plugin.

Phase 6 - Typed Tool Surface (Less Stringly, More Models)

1. Add optional typed tool interface/adapter pattern in IntelligenceX.Tools.Common (request/response model typed; envelope serialization centralized).
2. Keep ITool compatibility adapter for transport, but mark direct raw argument parsing patterns as deprecated.
3. Enforce typed binders (ToolRequestBinder) for all new tools; backfill existing tools incrementally.
4. Standardize success/error envelope shaping through ToolResultV2 only.
5. Add analyzer rule in IntelligenceX.Tools.Tests or shared analyzer package to flag ad-hoc arguments?.Get... in refactored packs.

Phase 7 - Test Migration And Coverage

1. Replace reflection-heavy fallback tests in IntelligenceX.Chat/IntelligenceX.Chat.Tests/ChatServiceRoutingTrimTests.*PackFallback*.cs with internal helper exposure tests or remove if behavior deleted.
2. Add contract-driven routing tests in Chat that use synthetic tools with explicit contracts.
3. Add regression tests verifying Chat does not auto-switch packs after tool failure.
4. Add tests ensuring preflight uses role contracts, not suffixes.
5. Add tests ensuring DomainDetective and ADPlayground remain isolated unless handoff contract explicitly connects them.
6. Keep existing language-neutral routing/ordinal tests green.

Phase 8 - Cutover And Cleanup

1. Remove dead constants/helpers tied to old fallback reason telemetry markers.
2. Remove stale docs referencing Chat cross-pack fallback behavior.
3. Publish new "How to add a tool/pack without touching Chat" guide in InternalDocs/agent-playbooks/.
4. Publish contract schema examples for plugin authors.
5. Run full solution build/test gates and close migration tracker items.

Parallel Workstreams

1. Track A (Contracts) Tools contract types + validation + pack migration templates.
2. Track B (Chat Core) Orchestration catalog + heuristic removal + fallback deletion.
3. Track C (Tests/Quality) Architecture tests + regression suite updates + docs.
4. Track D (Startup/Activation) Descriptor snapshot, preview startup, lazy activation, and warm-path perf hardening.
5. Track E (Language Neutrality) Turn classification cleanup, multilingual regressions, and prompt/control-flow separation.
6. Merge order: Track A foundational contracts first, Track B next, Tracks C/D/E continuously once contract boundaries stay stable.

Immediate Next Steps (Post-Audit)

1. Add continuation-subset escape for tool-capability question turns that do not reference explicit tool ids, so follow-up capability questions do not get trapped in stale subset visibility.
2. Add startup churn diagnostics classification in app status/debug (for example auth_wait, pipe_retry, metadata_retry, runtime_disconnect) so connect/disconnect loops are attributable without log digging.
3. Add end-to-end regression covering contextual follow-up scope-shift + host structured next-action finalize path using routed rewrite text to prevent stale single-host replay regressions.
4. Run full release preflight (dotnet build, dotnet test, harness net8/net10) before PR merge.
5. Add descriptor-snapshot contract and persisted preview payload versioning for startup-safe capability self-knowledge.
6. Refactor tooling bootstrap cache-key validation so persisted preview reuse does not require full discovery fingerprint recomputation on the warm path.
7. Filter disabled packs before activation work and add a regression proving startup cost decreases when packs are disabled.
8. Remove English runtime cue-word routing in app/shared classifiers and replace it with structure-first classification plus multilingual tests.
9. Replace host-side remote target/default host prompt hints with contract-backed execution/setup metadata.

Definition Of Done

• DoD1 No Chat file contains cross-pack fallback execution methods.
• DoD2 Chat does not decide substitute tools based on hardcoded pack names.
• DoD3 Pack preflight/routing relies on contracts, not suffix/prefix naming.
• DoD4 Every registered tool has explicit routing role + pack metadata.
• DoD5 New synthetic pack/tool can be added in tests without Chat code changes.
• DoD6 DomainDetective vs ADPlayground separation enforced by contracts/tests.
• DoD7 Full build/test suite passes after legacy fallback removal.
• DoD8 hello, list_tools, and first-paint startup can complete from persisted descriptor/capability snapshots before full pack activation finishes.
• DoD9 Disabling packs measurably reduces startup activation cost instead of only hiding tools from runtime exposure.
• DoD10 Built-in pack onboarding does not require Chat runtime code edits to learn the pack's contract surface.
• DoD11 Runtime/capability classification and routing no longer depend on hardcoded English cue words or literal confirmation phrases.
• DoD12 Zero-pack, plugin-only, lazy-activation, and multilingual capability/runtime-introspection suites pass under release gates.

Suggested Session Plan

1. Session 1: Phase 0 + Phase 1 scaffolding (contracts + validation).
2. Session 2: Phase 2 catalog + Phase 4 preflight/routing heuristic replacement.
3. Session 3: Phase 3 fallback deletion + failing tests triage.
4. Session 4: Phase 5 pack migrations (ADPlayground/DomainDetective/DnsClientX first).
5. Session 5: Phase 6 typed-surface migration start + analyzer guardrails.
6. Session 6: Phase 7/8 cleanup, docs, and final quality gate.
7. Session 7: Phase 5A descriptor snapshot + preview-startup contract and warm-path cache validation.
8. Session 8: Phase 5A lazy activation + disabled-pack preactivation filtering + startup perf budgets.
9. Session 9: Phase 5B language-neutral classifier cleanup + multilingual runtime/capability tests.