From 0abf805a26c8b8f7d4bfca14677b2d7b70e13569 Mon Sep 17 00:00:00 2001
From: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Date: Tue, 24 Feb 2026 13:13:38 +0000
Subject: [PATCH] feat(skill): add registry flattening and capability summaries

Add tools() and validate_plan() methods to SkillRegistry, enhance
SkillResolver with per-include override propagation, and enforce
non-overridable field constraints.

Core changes:
- SkillRegistry.tools(name) returns combined tuple of flattened
  ResolvedToolEntry list and SkillCapabilitySummary in a single call
- SkillRegistry.validate_plan(plan) validates skill references,
  catching missing skills, include cycles, and invalid tool refs
- SkillResolver._resolve_recursive() now applies per-include overrides
  (SkillInclude.overrides) to entries from included skills, with
  before/after key snapshots to target only newly-added entries
- _NON_OVERRIDABLE_FIELDS frozenset (name, source_skill, is_inline)
  rejects overrides on structural fields with descriptive error messages
  that include skill name and include path for traceability
- _validate_override_keys() helper ensures override safety

Testing:
- 13 Behave scenarios in features/skill_flatten.feature covering
  deterministic ordering, depth-first include resolution, inline tools,
  cycle detection with path trace, per-include overrides, non-overridable
  field rejection, capability summary aggregation, tools() method,
  validate_plan() (valid/missing/cycle), de-duplication, and shallow merge
- 11 Robot Framework integration tests in robot/skill_flatten.robot
- 4 ASV benchmark suites (FlattenSimple, FlattenDeep, FlattenWide,
  ComputeSummary) in benchmarks/skill_flatten_bench.py

Documentation:
- docs/reference/skill_registry.md updated with flattening rules,
  override merging, non-overridable fields, capability summary fields,
  validate_plan() usage, and error message reference

ISSUES CLOSED: #165
-- 
2.52.0