[FEATURE] override a consumed primitive's frontmatter (e.g. agent name/description) from apm.yml

[DevSecNinja]

Is your feature request related to a problem? Please describe.
When consuming individual primitives from another repo (e.g. github/awesome-copilot
agents) via dependencies.apm, the content is materialized verbatim and the
apm.lock.yaml integrity check (correctly) forbids editing it. But upstream display
names are often inconsistent or carry vendor taglines — e.g.
Prompt Builder - Brought to you by microsoft/edge-ai, or terse slugs like
sast-sca-security-analyzer. I would like to normalize these artifacts
without forking or vendoring each file — which loses apm update and the
supply-chain gate.

Describe the solution you'd like
Allow per-dependency frontmatter overrides in apm.yml, applied at deploy time and
recorded in apm.lock.yaml so they are reproducible and visible in diffs:

dependencies:
  apm:
    - repo: github/awesome-copilot
      path: agents/sast-sca-security-analyzer.agent.md
      ref: <sha>
      overrides:
        name: "SAST/SCA Security Analyzer"
        # description: "Reviews dependencies and code for SAST/SCA findings."

[github-actions]

Triage decision

needs-design

Proposed labels

theme/governance
area/package-authoring
area/lockfile
type/feature
status/needs-design

Milestone

null

Suggested next action

Draft a design brief specifying the integrity model for frontmatter overrides: choose between (A) in-memory overlay, (B) excluded-frontmatter checksum, or (C) transformed SHA recorded alongside the source SHA in apm.lock.yaml, and enumerate which frontmatter keys are in scope.

Suggested issue comment

Thank you for the well-framed feature request. You have put your finger on a real tension: the supply-chain gate correctly forbids editing locked files, but upstream display metadata is often inconsistent or vendor-tagged. Forking to rename loses `apm update` and integrity tracking -- so the override mechanism you propose is the right design direction.

The feature is accepted in principle. What needs to be designed before code lands is the integrity model. The deployed file after override will not match the locked SHA (because its frontmatter has changed), which means one of three things must be true:

- **Option A (in-memory overlay)**: Overrides are applied by the consuming tool at runtime, never touching the deployed file. APM materializes the raw file; a companion metadata layer carries the display name. This keeps the integrity check clean but requires consumer tools to support the overlay format.
- **Option B (excluded-frontmatter checksum)**: APM applies overrides to the deployed file but locks a content checksum that excludes frontmatter. `apm lock verify` passes if the body (post-frontmatter) matches the locked SHA. This is simpler but weakens the provenance guarantee.
- **Option C (transformed SHA)**: APM records both the source SHA (pre-override) and the transformed SHA (post-override) in `apm.lock.yaml`. `apm lock verify` checks the transformed SHA against the deployed file and the source SHA against the upstream commit. This is the most auditable but adds lockfile schema complexity.

Also worth specifying upfront: which frontmatter keys are allowed to be overridden? If only `name` and `description` are in scope, Options A or C are preferable. If the override scope could grow to include `tools:` or `model:`, Option B becomes risky.

If you want to drive this design, a comment proposing one of the three options with rationale would be the concrete next step.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The request maps to a real pain: upstream package display names carry vendor taglines or terse slugs that don't fit the consuming team's tooling vocabulary. The proposed syntax (an overrides: key inside the dependency block in apm.yml) is ergonomically clean and follows the package-manager mental model -- analogous to npm package aliases or cargo patch tables. The scope as proposed is narrow (only name and description), which is good for a first implementation. The key UX concern is discoverability: users must know the override is in effect when they run apm install or apm view -- the output should surface applied overrides clearly.

Supply Chain Security Expert -- Risk-Surface Reviewer

This feature touches the lockfile contract (apm.lock.yaml) and the file integrity model, both of which are core to APM's supply-chain security guarantee. The risk surface is real: if name overrides are applied to deployed files, the deployed artifact no longer matches the locked SHA, which means apm lock verify would either fail or must be redesigned. The critical question is whether name is used by any agent host to route or invoke the primitive -- if so, renaming is a functional change, not just a display change, and warrants theme/security alongside theme/governance. Treating it as theme/governance (lockfile contract) is correct until the invocation surface is confirmed.

OSS Growth Hacker -- Contributor-Tone Reviewer

DevSecNinja has author_association: NONE and filed a concise but well-thought feature request that explicitly acknowledges the supply-chain tension. The reply should validate that understanding and give them a concrete design question to answer, not a blocker. Story angle: "normalized display names for consumed primitives" is an enterprise feature -- naming governance, vendor-tag cleanup for regulated environments. First-time contributor tone: warm, technically direct, make the next step actionable.

Python Architect -- Architecture Reviewer

The schema impact spans three components: apm.yml (new overrides: key per dependency), apm.lock.yaml (must record overrides alongside the source SHA), and the materialization step in install/compile (must apply overrides to deployed files or via in-memory overlay). The integrity check in src/apm_cli/deps/lockfile.py will require redesign under Options B and C. Option A (in-memory overlay) is architecturally cleanest but requires consumer tool support. The design choice also determines whether area/lockfile stays a primary or secondary area -- if the lockfile schema changes (Options B or C), it is a primary concern. status/needs-design is correct; feasibility is medium (schema changes have migration cost).

Doc Writer -- Documentation Reviewer

An implementing PR will need: documentation of the overrides: key in the apm.yml reference, documentation of how overrides are recorded in apm.lock.yaml, and a guide section on the use case (normalizing upstream display names). area/docs-site should ride as a secondary label when the feature ships. For the design phase, no doc work is implied. The proposed comment correctly frames the three integrity-model options without inventing features.

APM CEO -- Triage Arbiter

Feature direction is correct -- upstream display-name inconsistency is a real friction point for enterprise consumers who aggregate primitives from multiple repos. The Supply Chain Security expert's invocation-surface question (does name affect routing?) is the load-bearing uncertainty before the design can close. theme/governance is the right primary theme (lockfile contract and integrity model). The Python Architect's three-option framing gives the community a concrete design surface to react to. status/needs-design with null milestone is correct. The existing human-applied type/feature is correct; the panel agrees and does not need to re-add it. theme/governance + area/package-authoring + area/lockfile is the correct minimal label set.

{
  "decision": "needs-design",
  "decision_detail": "Specify the integrity model for frontmatter overrides: choose between Option A (in-memory overlay), Option B (excluded-frontmatter checksum), or Option C (transformed SHA in lockfile), and enumerate which frontmatter keys are in scope.",
  "theme": "theme/governance",
  "areas": ["area/package-authoring", "area/lockfile"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design brief choosing between the three integrity-model options (in-memory overlay, excluded-frontmatter checksum, or transformed SHA) and specifying which frontmatter keys are in scope for overrides.",
  "comment_markdown": "Thank you for the well-framed request. The feature is accepted in principle. Before code lands, the integrity model must be chosen: Option A (in-memory overlay), Option B (excluded-frontmatter checksum), or Option C (transformed SHA in lockfile). Also specify which frontmatter keys are in scope."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · sonnet46 3.3M · ◷