Epic: PGS roadmap-management system (taxonomy + discussion #116 + apm-triage-panel skill)

[danielmeppiel]

What

Establish a durable, public roadmap-management system for microsoft/apm organized around the three promises in the README: Portable by manifest, Secure by default, Governed by policy (PGS). Replace ad-hoc single-word labels with a five-axis taxonomy, refactor Discussion #116 to render priorities along that spine, and ship a reusable apm-triage-panel skill so every new issue is triaged the same way -- by maintainers or by an agent.

This epic captures the work as a single What / Why / How story, links the PRs and discussion changes, and serves as the entry point for anyone -- maintainer, contributor, or interested observer -- who wants to understand how the APM roadmap is now produced and maintained.

Why

The repository was growing past the point where ad-hoc labels (security, policy, marketplace, cli, ...) and a free-form roadmap discussion could keep up:

• For maintainers: triage decisions were inconsistent issue-to-issue; milestone discipline was loose; priorities were hard to compose with filters.
• For contributors: there was no obvious "what should I pick up next?" filter scoped to a theme.
• For observers: the roadmap discussion grouped items by execution unit, not by user-facing promise -- which meant the link between "what APM commits to do" (README) and "what APM is actually building" (issues + PRs) was implicit.
• For us long-term: as the project crosses 250 stars and external contributors arrive, the cost of an inconsistent system compounds. We needed a system that scales without humans always being in the loop.

The fix is to align the issue/PR taxonomy with the README spine, and to encode the triage discipline as an apm-skill that any maintainer or workflow can re-run.

How

1. Three mega-themes, five-axis taxonomy

Issues and PRs are now classified along five orthogonal axes:

Axis	Values	Purpose
theme/*	portability, security, governance	Which README promise this serves
area/*	multi-target, marketplace, package-authoring, distribution, mcp-config, content-security, lockfile, mcp-trust, audit-policy, enterprise, cli, ci-cd, testing, docs-site	Which surface inside APM
type/*	bug, feature, docs, refactor, architecture, automation, release, performance	Kind of change
status/*	needs-triage, accepted, needs-design, blocked, in-flight	Where it sits in the lifecycle
priority/*	priority/high, priority/low (preserved)	Maintainer urgency signal

Multi-theme labels are allowed; the primary theme drives the milestone (tiebreak: Portability < Security < Governance). Multi-area labels are encouraged for cross-cutting work.

Sixteen single-word legacy labels (security, policy, marketplace, cli, bug, enhancement, documentation, ...) are kept as deprecated redirects so existing issue links survive; their descriptions read Deprecated: use <new>. They will be removed in milestone 0.10.0.

2. Discussion #116 refactored as the public roadmap

The roadmap discussion body now organizes every linked item into Now / Next / Later tiers under each of the three mega-themes, with five composable filter URLs ("contributor on-ramp by theme", "high-priority security work", "where policy is happening", ...). No roadmap content was dropped; every original #NNN link survives.

A "How to navigate" section explains the five-axis labels to readers in two paragraphs. A "Latest cohort" table shows the most recently triaged issues so observers can sanity-check the system in action.

3. apm-triage-panel skill (PR #915)

A new skill encodes the triage discipline so it is repeatable by both humans and agents.

• Always-on lenses: DevX UX Expert, Supply Chain Security Expert, APM CEO (arbiter)
• Conditional lenses: OSS Growth Hacker (first-time contributors), Python Architect (architecture / breaking-change / new schema), Doc Writer (docs / user-facing features that need new doc pages) <- the Architect and Doc Writer lenses are added in a follow-up commit on the same PR after panel feedback
• Output contract: ONE comment per issue, structured JSON tail, mechanically applied label set + milestone + decision (accept | needs-design | decline-with-reason | duplicate-of | defer-later | auto-handle)
• Decision rubric is explicit, so triage outcomes are auditable

The skill mirrors the proven apm-review-panel orchestration model (single agent loop, persona-pass procedure, completeness gate, no sub-agent dispatch). Source lives at .apm/skills/apm-triage-panel/; the regenerated mirror at .github/skills/apm-triage-panel/ is committed alongside.

4. Live cohort: 10 issues triaged with the new skill

The latest 10 open issues at the time of publishing were triaged using the panel:

#	Decision	Theme	Milestone
#913	accept	portability	0.9.3
#903	auto-handle (closed)	n/a	none
#898	accept	security	0.9.3
#894	accept (needs reproducer)	portability	none
#891	needs-design	portability	none
#888	accept (defer-later)	portability	none
#886	accept	infra	0.9.3
#879	needs-design	portability	none
#877	auto-handle (closed)	n/a	none
#876	accept (defer-later)	portability	none

Two automated app/github-actions reports (#903, #877) were closed under the auto-handle rubric; the rest were labelled, milestoned (where applicable), and given a contextual triage comment.

Before / after for triagers

Before: read issue, search prior conversations for prior similar decisions, hand-pick 1-2 single-word labels, sometimes set a milestone, post a free-form comment if any.

After: open the issue, run the apm-triage-panel skill (or follow its rubric manually), apply the structured label set, set the milestone per the rule table, post the templated comment. Output is consistent across triagers and across time.

Before / after for the public roadmap

Before: Discussion #116 grouped items by execution unit (multi-target / supply chain / marketplace / enterprise). Reader had to know APM's internal structure to find anything.

After: Discussion #116 groups items by promise to the user (portable / secure / governed) at three time horizons (now / next / later). Reader maps directly from "what APM says it does" to "what APM is building".

Before / after for maintainers managing the roadmap

Before: roadmap drift happened silently; the discussion needed manual sync sessions.

After: any maintainer can run the apm-triage-panel skill on a new issue and the result feeds the roadmap automatically (label set + milestone). The "Latest cohort" table in Discussion #116 is the public ledger of triage activity. Future automation can run the skill on every newly opened issue inside gh-aw.

Scope -- in / out

In scope (this epic):

• Five-axis label taxonomy created on microsoft/apm (30 new + 16 deprecated)
• Discussion Roadmap — Now / Next / Later #116 body rewritten and announced
• apm-triage-panel skill authored and published
• 10-issue live triage cohort
• Architecture-Reviewer and Doc-Writer conditional lenses added to the skill (follow-up commit on PR feat(skills): add apm-triage-panel for issue triage #915)

Out of scope (future, captured for the record):

• GitHub Project board materializing the views (the label taxonomy is the substrate; the board is a future polish)
• gh-aw workflow that runs apm-triage-panel automatically on every new issue
• Migration of the remaining ~200 historical open issues to the new taxonomy (planned to happen organically as issues are touched)
• Removal of the 16 deprecated legacy labels (scheduled for milestone 0.10.0)
• A apm-roadmap-publish workflow that auto-syncs the discussion body from the live label state

PRs and links

• PR #915 -- feat(skills): add apm-triage-panel for issue triage (skill source + mirror + CHANGELOG + follow-up persona refinement)
• Discussion #116 -- public roadmap, body rewritten + announcement comment
• Sibling PR #897 -- visual-communicator agent (shipped earlier in this thread of work, used for Epic Epic: Close the producer-produced drift-detection gap (per-asset lockfile + skill-as-package + apm audit --drift) #898)
• Sibling Epic #898 -- producer-produced drift detection (the first issue triaged under this new system)

Acceptance criteria

• 30 new labels live on microsoft/apm
• 16 legacy labels deprecated (description updated, kept for history)
• Discussion Roadmap — Now / Next / Later #116 body rewritten around PGS spine; all original links preserved
• Announcement comment posted on Discussion Roadmap — Now / Next / Later #116
• apm-triage-panel skill source + mirror committed on PR feat(skills): add apm-triage-panel for issue triage #915
• CHANGELOG entry under [Unreleased] references the skill PR
• 10 latest open issues triaged with the new skill
• Architecture-Reviewer + Doc-Writer conditional lenses added (follow-up commit on PR feat(skills): add apm-triage-panel for issue triage #915)
• PR feat(skills): add apm-triage-panel for issue triage #915 merged
• Triage cohort table in Discussion Roadmap — Now / Next / Later #116 refreshed at next maintainer pass

Notes for the OSS community

If something in this system feels off -- a label is missing, a theme assignment looks wrong, the rubric does not fit your issue -- comment on Discussion #116 or open an issue with status/needs-triage. The system is meant to be evolved, not enforced.