Add path-scoped Copilot instructions for context/ and routing/

[Copilot]

Summary

The two largest subsystems — context engine (11 modules) and routing engine (9 modules) — lacked agent-facing guidance scoped to their directories. Agents editing manager.py or graph.py had no subsystem-specific invariants to follow, risking broken pipeline ordering, firewall bypasses, or invalid graph states.

Changes

• .github/instructions/context.instructions.md (applyTo: src/contextweaver/context/**)

  • 8-stage pipeline in exact required order, with explicit ordering constraints (closure before scoring; firewall before scoring)
  • Firewall invariants: raw tool_result text never reaches prompt; artifact handle format; artifact_ref always populated
  • Async-first pattern and no-blocking-I/O rule
  • Dependency closure must-run-before constraint with consequence if skipped
  • manager.py flagged at ~876 lines with decomposition refs ([refactor] Decompose context/manager.py to meet ≤300-line module guideline #73, [context] Extract manager.py to stay within 300-line module limit #69); discourages new methods until decomposed
  • Defers sensitivity rules to sensitivity.instructions.md

• .github/instructions/routing.instructions.md (applyTo: src/contextweaver/routing/**)

  • All 4 ChoiceGraph._validate() invariants documented (root exists, children resolve, no cycles, all items reachable)
  • Eager cycle detection in add_edge() — must not be bypassed
  • TreeBuilder 3-strategy priority order (namespace → Jaccard clustering → alphabetical) with fallback conditions
  • Router determinism: (-score, id) sort key must not change; confidence_gap bounds
  • generate_sample_catalog seed=42 is a contract — demos and tests depend on it
  • ChoiceCard schema prohibition; sync-only routing; no cross-engine imports

Both files are ≤100 lines, documentation-only, and grounded in actual code.

Checklist

• Tests added or updated for every new/changed public function
• make ci passes locally (fmt + lint + type + test + example + demo)
• CHANGELOG.md updated under ## [Unreleased]
• Docstrings added for all new public APIs (Google-style)
• Every modified module stays ≤ 300 lines (or a decomposition issue is linked above)
• Related issue linked in the summary above
• Agent-facing docs updated if pipeline, API, or conventions changed

Notes for reviewers

Instruction files are loaded automatically by VS Code Copilot when editing files under the targeted paths — no tooling changes required. Content is derived directly from manager.py docstring, graph.py._validate(), router.py.route(), tree.py.build(), and catalog.py.generate_sample_catalog() — reviewers should cross-check those sources if any rule seems off.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[agent] Add path-scoped Copilot instructions for context/ and routing/</issue_title>
<issue_description>## Problem

The two largest subsystems — context engine (9 modules, 1113 lines) and routing engine (9 modules, 1568 lines) — lack module-specific agent guidance. Root-level files (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) provide general conventions but don't cover subsystem-specific invariants.

Agents editing context/manager.py (629 lines, the largest module) or routing/graph.py (316 lines) need scoped rules to avoid breaking critical invariants like pipeline stage ordering, firewall guarantees, or ChoiceGraph validation constraints.

Evidence:

• .github/instructions/ — directory does not exist
• src/contextweaver/context/ — 9 modules, pipeline has strict ordering (candidates → scoring → dedup → selection → firewall → prompt)
• src/contextweaver/routing/ — 9 modules, graph has validation invariants (root exists, children resolve, items reachable, no cycles)
• context/manager.py — 629 lines, violates ≤300-line guideline, decomposition tracked in [refactor] Decompose context/manager.py to meet ≤300-line module guideline #73/[context] Extract manager.py to stay within 300-line module limit #69
• AGENTS.md mentions module responsibilities but not subsystem-specific constraints

Proposal

Create 2 path-scoped Copilot instruction files that VS Code Copilot automatically loads when editing files in the corresponding directories.

.github/instructions/context.instructions.md

Apply to src/contextweaver/context/**. Should cover:

• Pipeline stage ordering (the 7 stages in order) — never reorder
• Firewall invariants: raw text NEVER reaches prompt; always goes through artifact store
• Async-first pattern: build() is async, build_sync() wraps it
• Dependency closure: resolve_dependency_closure() must run before scoring
• manager.py decomposition: reference [refactor] Decompose context/manager.py to meet ≤300-line module guideline #73/[context] Extract manager.py to stay within 300-line module limit #69, warn agents about the 629-line size
• Import rules: exceptions from contextweaver.exceptions, similarity from contextweaver._utils

.github/instructions/routing.instructions.md

Apply to src/contextweaver/routing/**. Should cover:

• ChoiceGraph validation rules: root must exist, all children must resolve, all items must be reachable, no cycles
• TreeBuilder strategies: namespace grouping → Jaccard clustering → alphabetical fallback
• Router beam-search constraints: deterministic tie-break by ID, confidence_gap threshold
• Catalog invariants: generate_sample_catalog is seeded for reproducibility
• ChoiceCard: never include full schemas (keeps prompt tokens minimal)
• All routing is synchronous (pure computation, no async)

Acceptance criteria

• .github/instructions/context.instructions.md created
• applyTo metadata targets src/contextweaver/context/**
• Covers: pipeline ordering, firewall invariants, async pattern, dependency closure, decomposition refs
• .github/instructions/routing.instructions.md created
• applyTo metadata targets src/contextweaver/routing/**
• Covers: graph validation, tree strategies, beam-search determinism, catalog seeding, card constraints
• Each file ≤100 lines, focused on invariants agents must preserve
• References specific file paths and related issues ([refactor] Decompose context/manager.py to meet ≤300-line module guideline #73, [context] Extract manager.py to stay within 300-line module limit #69, [context] Wire pluggable Summarizer/Extractor protocols into firewall #63)
• No code changes — instruction files only

File paths

• .github/instructions/context.instructions.md (create)
• .github/instructions/routing.instructions.md (create)

Dependencies

• None (independent)

Estimated effort

S (1-2 days)</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [agent] Add path-scoped Copilot instructions for context/ and routing/ #95

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

Adds path-scoped Copilot instruction files to provide subsystem-specific invariants and editing guidance for the context engine and routing engine directories.

Changes:

• Introduces .github/instructions/context.instructions.md scoped to src/contextweaver/context/** with pipeline/firewall/sensitivity guidance.
• Introduces .github/instructions/routing.instructions.md scoped to src/contextweaver/routing/** with ChoiceGraph/TreeBuilder/Router/Catalog invariants and determinism rules.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
.github/instructions/context.instructions.md	Adds context-engine pipeline ordering and firewall/sensitivity invariants for agents editing src/contextweaver/context/**.
.github/instructions/routing.instructions.md	Adds routing-engine graph validation + determinism + catalog/card constraints for agents editing src/contextweaver/routing/**.

---

You can also share your feedback on Copilot code review. Take the survey.