51fc34f585
Align session skill filtering with Skills-view path identities. - Match session inclusions, exclusions, and diagnostics by skills-relative body path. - Ignore stale flat toggle keys for categorized skills and cover the display/session invariant. - Document the behavior and add a patch changeset. Files changed: .../fn-8465-legacy-skill-toggle-path-match.md | 7 ++ docs/dashboard-guide.md | 2 +- .../legacy-flat-skill-toggle-session-divergence.md | 41 ++++++++ .../engine/src/__tests__/skill-resolver.test.ts | 73 ++++++++++++++ packages/engine/src/skill-resolver.ts | 105 ++++++++++++++------- 5 files changed, 191 insertions(+), 37 deletions(-) Fusion-Task-Id: FN-8465 Fusion-Task-Lineage: 042fc7f4-08a3-42f4-9a6f-52f066d585e8 Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>
42 lines
2.1 KiB
Markdown
42 lines
2.1 KiB
Markdown
---
|
|
title: "Legacy flat skill-toggle keys silently suppressed categorized session skills"
|
|
date: 2026-07-21
|
|
category: docs/solutions/logic-errors
|
|
module: engine (session skill resolver)
|
|
problem_type: logic_error
|
|
component: path_identity
|
|
symptoms:
|
|
- "The Skills view showed a categorized plugin skill enabled while agent sessions omitted it."
|
|
- "Deleting a stale flat `-name/SKILL.md` settings entry restored the skill to the session manifest."
|
|
root_cause: logic_error
|
|
resolution_type: code_fix
|
|
severity: medium
|
|
related_components:
|
|
- skill-resolver
|
|
- skill-settings
|
|
- skills-adapter
|
|
tags:
|
|
- skills
|
|
- settings
|
|
- plugin-skills
|
|
- path-identity
|
|
- session-manifest
|
|
- legacy-settings
|
|
---
|
|
|
|
# Legacy flat skill-toggle keys silently suppressed categorized session skills
|
|
|
|
## Problem
|
|
|
|
Project skill toggles are persisted as signed paths such as `-api/api-versioning/SKILL.md`. The Skills view resolves those paths relative to a skill body beneath `skills/`, but the session override resolver also accepted a bare skill-name match. After a plugin moved a body from `skills/api-versioning/SKILL.md` to `skills/api/api-versioning/SKILL.md`, an old `-api-versioning/SKILL.md` entry no longer matched the view yet still excluded the session skill because pi exposed `skill.name === "api-versioning"`.
|
|
|
|
## Solution
|
|
|
|
Session allow, exclusion, and disabled-diagnostic matching now use the same canonical identity as the Skills view: the complete body-relative path beneath the final `skills/` segment. Absolute patterns continue to match exact file paths. A flat `name/SKILL.md` pattern remains compatible only when the discovered body path is itself flat; it cannot match a categorized `category/name/SKILL.md` body merely by sharing the final directory name.
|
|
|
|
## Prevention
|
|
|
|
- Treat stored setting keys as identities, not labels: compare the complete normalized path at every reader.
|
|
- When a layout changes, test every reader of the persisted key, including session assembly and diagnostics, not only the UI display.
|
|
- Preserve legacy compatibility only where the legacy key still identifies the current on-disk path; otherwise ignore it consistently rather than allowing one reader to honor it.
|