microsoft / microsoft/hve-core

Reconcile skill SECURITY.md repo-root links with the cross-artifact portability rule

Open
#2,646 0 comments 1 reaction 1 assignee Claimed by @WilliamBerryiii View on GitHub
compliance security tech-debt
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

Discovered while remediating review findings on #2599.

## Problem

Two repository rules now contradict each other.

`hve-builder.instructions.md` (added in #2599) states that a cross-artifact reference must name its target rather than hard-code a path into another package, so references survive extension and plugin packaging.

`skill-security-model.instructions.md` mandates that every skill `SECURITY.md` carry a "See also: repo-wide STRIDE model" callout linking `docs/security/security-model.md`. In practice that is implemented as `../../../../docs/security/security-model.md`, which escapes the skill root and only resolves inside this repository at a known nesting depth.

A skill installed through a plugin or extension package gets a callout pointing at nothing, and the failure is silent.

## Scope

68 skill-root-escaping link instances exist across 15 files under `.github/skills/**`:

| Target | Instances |
|--------------------|-----------|
| `docs/security` | 34 |
| `docs/docusaurus` | 19 |
| `evals/` | 9 |
| `CODE_OF_CONDUCT.md` | 5 |
| `docs/agents` | 1 |

The 34 `docs/security` instances span 11 skill `SECURITY.md` files and exist to satisfy the mandated callout.

## Consequence visible today

PR #2599 converted references in `vex/SECURITY.md` and `customer-card-render/SECURITY.md` but could not remove their mandated callout links, so both files now carry both conventions. In `customer-card-render/SECURITY.md` the converted and unconverted forms sit on adjacent lines of the same References list.

## Options

1. Change `skill-security-model.instructions.md` to require naming the repo-wide model rather than linking it, then convert all 34 instances.
2. Carve out an explicit exception in the portability rule for repository-governance documents that are not part of any package.
3. Publish the security model at a stable URL and reference that instead of a relative path.

Option 2 is the smallest change but weakens the portability rule. Option 1 is the most consistent and the largest diff.

## Acceptance

- The two instructions no longer contradict each other.
- No skill `SECURITY.md` contains both reference conventions.
- The chosen approach is recorded so future SECURITY.md authors are unambiguous.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.