Skip to content

feat(resolver): sealed property to prevent content override by higher layers #206

@mrwogu

Description

@mrwogu

Context

In a multi-layer registry architecture, Layer 2 (product) may define critical skill instructions that should not be overridden by Layer 3 (BU) or Layer 4 (project). Currently, any higher layer can freely replace the content property via @extend, which creates a governance gap — there is no way for a skill author to protect their instructions.

Parent issue: #199 (Phase 2)
Spec: docs/superpowers/specs/2026-03-30-skill-overlay-extends-design.md §13
Review: docs/superpowers/specs/2026-03-30-skill-overlay-extends-review.md §3.2

Proposal

Add an optional sealed property to skill definitions that prevents specified properties from being overridden by @extend in higher layers.

Syntax

@skills {
  clm512-expert: {
    description: "CLM 5.12+ development expert"
    content: """
      Critical workflow instructions that must not be changed.
    """
    sealed: [content, description]
  }
}

Semantics

  • sealed takes an array of property names that cannot be replaced by @extend
  • When a higher layer attempts to override a sealed property, it is a validation error (not silently ignored)
  • sealed only affects replace-strategy properties — append-strategy properties (references, requires) can still be extended
  • sealed itself cannot be unsealed by higher layers (it is implicitly sealed)
  • sealed: true (boolean shorthand) seals all replace-strategy properties

Error message

PS027: Cannot override sealed property 'content' on skill 'clm512-expert'
  (sealed by @clm5core/skills/clm512-expert)

Implementation approach

  1. AST: Add optional sealed?: string[] | boolean to skill property handling
  2. extensions.ts: Check sealed before applying replace-strategy overrides in mergeSkillValue()
  3. Validator: New rule PS027: sealed-property-override — error when @extend targets a sealed property
  4. Provenance: Sealed status and origin should be tracked for error messages

Design considerations

  • sealed protects properties from @extend but does NOT prevent skill composition (@use phases) — those create new content, not override existing
  • Should sealed also protect against @inherit? Probably yes, for consistency
  • The sealed property must be preserved through the resolution pipeline (add to SKILL_PRESERVE_PROPERTIES in extensions.ts)

Acceptance criteria

  • sealed: [prop1, prop2] prevents those properties from being replaced via @extend
  • sealed: true seals all replace-strategy properties
  • Attempting to override a sealed property produces a clear validation error
  • Error message includes the origin of the sealed declaration
  • sealed itself is implicitly sealed (cannot be removed by higher layers)
  • Append-strategy properties (references, requires) remain extendable even when sealed
  • Works correctly in multi-layer (3+) extension chains
  • Unit tests for all sealed scenarios
  • Documentation with enterprise use case examples

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions