feat: add safe routing context

[mohanagy]

Summary

• Collect bounded, metadata-only workspace and MCP-root routing context with deterministic profile selection.
• Carry the same sanitized collector evidence through route previews and audited proxied operations.
• Document the trusted-config and project-marker boundary, roots behavior, and evidence contract.

Validation

• npm test
• npm run typecheck
• npm run lint
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package

Relates to #20

Summary by CodeRabbit

• New Features
  • Routing now derives profile selection from bounded workspace metadata and client-provided MCP roots, using an immutable context snapshot.
  • Route preview returns the resolved route, evaluated policy, and sanitized routing evidence for audit.
  • Audit events can include routing evidence when available.
• Bug Fixes
  • Ambiguous or unknown profile hints fail closed without forwarding upstream calls.
  • Roots discovery/caching and roots-list change refresh behave safely, including fallback when roots requests fail.
• Documentation
  • Expanded routing context, safety guarantees, and audit/redaction behavior guidance.
• Tests
  • Added routing-context, policy, and integration coverage, plus a documentation contract test.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds metadata-only routing context collection from bounded workspace signals, deterministic profile-hint precedence, capability-gated MCP root handling, sanitized route-preview/audit evidence, and extensive runtime, security, routing, and documentation tests.

Changes

Routing context integration

Layer / File(s)	Summary
Context contracts and bounded collection src/routing/routing-types.ts, src/routing/context-collector.ts	Defines immutable routing snapshots and collects bounded, validated, redacted environment, marker, package, workspace, root, and Git metadata.
Profile selection and pipeline wiring src/routing/routing-engine.ts, src/mcp/server/operation-pipeline.ts, src/runtime/create-miftah-runtime.ts	Applies environment and project-marker hints before rules or fallback, matches context arrays, and passes one snapshot through each operation.
MCP roots, previews, and audit evidence src/mcp/server/miftah-server.ts, src/audit/*	Caches and refreshes client roots conditionally, uses routing context for previews, and records sanitized routing evidence in audit events.
Behavioral tests and documentation tests/*, README.md, docs/*, CHANGELOG.md, vitest.config.ts	Validates routing precedence, metadata boundaries, root lifecycle behavior, preview/audit output, destructive-call blocking, and documented guarantees.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• [Routing] Add workspace, MCP roots, project files, and Git remote context #20 — Directly covers the routing-context collector, profile precedence, MCP roots, project markers, and sanitized evidence implemented here.

Possibly related PRs

• mohanagy/miftah#53 — Extends the audit event flow in the same audit files with routingEvidence.

Poem

A rabbit hops through bounded ground,
Finds safe hints without a sound.
Roots refresh, profiles align,
Secrets stay beyond the line.
Preview trails glow clean and bright—
Audit carrots tucked just right.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 5.41% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description has Summary and Validation, but it omits the required Security impact section and exact validation results/checklist details.	Add a Security impact section and fill Validation with exact command results plus the required checklist items from the template.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: safe routing context support.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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-20-routing-context

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp/server/miftah-server.ts`:
- Around line 169-174: Cache the result produced by provideRoutingContext, keyed
to the current MCP roots/connection, so collectRoutingContext is executed only
once for each roots state. Reuse the cached RoutingContextSnapshot on subsequent
lookups, including before roots initialization where applicable, and invalidate
the cache whenever MCP roots are refreshed or the connection context changes.

In `@src/routing/context-collector.ts`:
- Line 154: Update the array sorting expression in the normalization flow to use
toSorted() instead of sort(), preserving the existing sorted return value while
satisfying the e18e/prefer-array-to-sorted lint rule.
- Around line 131-136: Move the URI-scheme and Windows-drive regex literals used
by redactProjectValue to module-level constants, then have the function reuse
those constants while preserving the existing matching behavior.

In `@src/routing/routing-engine.ts`:
- Around line 59-65: Update the markerProfiles construction to use the
non-mutating toSorted() method instead of sort(), preserving the existing
deduplication and ordering behavior while satisfying the
e18e/prefer-array-to-sorted lint rule.

In `@vitest.config.ts`:
- Around line 13-14: Replace the global fileParallelism setting in the Vitest
configuration with separate projects/workspaces: keep fixture-dependent specs in
a serialized project and leave unrelated tests on the default parallel
execution. Ensure each project’s test include patterns isolate the appropriate
files without changing their existing test behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 86515006-89af-46b4-a8a0-728f859c95fc

📥 Commits

Reviewing files that changed from the base of the PR and between 11e73d2 and 92cb07d.

📒 Files selected for processing (19)

• CHANGELOG.md
• README.md
• docs/architecture.md
• docs/config.md
• docs/security.md
• src/audit/audit-trail.ts
• src/audit/audit-types.ts
• src/mcp/server/miftah-server.ts
• src/mcp/server/operation-pipeline.ts
• src/routing/context-collector.ts
• src/routing/routing-engine.ts
• src/routing/routing-types.ts
• src/runtime/create-miftah-runtime.ts
• tests/mcp-wrapper.test.ts
• tests/operation-pipeline.test.ts
• tests/routing-context-docs-contract.test.ts
• tests/routing-context.test.ts
• tests/routing-policy.test.ts
• vitest.config.ts