[FEATURE] `apm validate` / test harness for user packages (hooks, instructions, skills)

[saaga112]

Is your feature request related to a problem?

As a user authoring APM packages (.apm/ with hooks, instructions, skills, agents), there is no first-class way to verify that my package actually works before installing/compiling it into a runtime:

• Hook scripts may have syntax errors, wrong permissions, or never fire for the intended lifecycle event.
• Instruction files may have malformed frontmatter or applyTo globs that silently match nothing.
• Skills may never be routed to because their description/intent metadata doesn't match how users phrase requests.

Today the feedback loop is "compile, run a real agent session, notice the behavior is wrong" — slow and hard to debug. The APM repo itself has a strong internal test suite (unit / integration / acceptance / mutation), including hook execution tests, but none of this is exposed to package authors as a validation tool.

Describe the solution you'd like

A user-facing validation/test command, e.g. apm validate (or apm test), that runs against a local package and reports:

1. Contract checks (static)

   • Frontmatter schema validation for *.instructions.md, SKILL.md, *.agent.md, *.prompt.md (required fields, valid YAML).
   • applyTo glob sanity: warn when a pattern matches zero files in the target workspace.
   • Hook manifest checks: referenced scripts exist, are executable, declare a known lifecycle event.

2. Hook dry-run (dynamic, opt-in)

   • Execute hooks in a sandbox with mock event payloads; assert exit code 0 and bounded runtime.

3. Routing/golden tests (optional fixtures)

   • Author-provided fixtures: prompt -> expected skill/instruction pairs.
   • Harness evaluates routing metadata deterministically (no LLM call needed for the static-matching portion) and reports which skill/instruction would be selected.

Output: human-readable summary + non-zero exit code on failure, so it's CI-friendly (authors can gate their package repos on apm validate).

Describe alternatives you've considered

• Ad-hoc pytest suites in each package repo — works, but every author reinvents frontmatter parsing and hook mocking; no shared contract with APM's compiler.
• Relying on compile-time errors — catches syntax issues but not "hook never fires" or "skill never routes".

Additional context

• Happy to contribute this incrementally: start with static contract checks (smallest slice), then hook dry-run, then routing fixtures — each as a separate single-concern PR with tests, per the contribution guide.
• Reuses existing internals where possible (package model parsing, hook execution code already covered by tests/integration/test_integrators_hooks_execution.py).

[github-actions]

Triage Panel Verdict

Issue: [FEATURE] apm validate / test harness for user packages (hooks, instructions, skills)

---

Panel Summary

DevX UX Expert: This is an important ecosystem feature. The current feedback loop -- compile, install, run a real agent session, discover something is broken -- is slow and opaque. Package authors have no first-class tool to verify their work. Static contract checks (frontmatter validation, glob sanity, hook manifest checks) are a high-value, achievable first slice. The proposed apm validate command fits naturally into the CLI surface alongside apm install / apm compile.

OSS Growth Hacker: Package validation lowers the barrier to ecosystem contribution significantly. If external authors can gate their own package repos on apm validate, it creates a standard quality signal and accelerates the community contribution flywheel. This is a strategic investment in the APM ecosystem.

Python Architect: Architecture is sound. The three-phase incremental plan (static checks -> hook dry-run -> routing fixtures) produces independently mergeable PRs with clear scope. Reusing existing internal infrastructure (package model parsing, tests/integration/test_integrators_hooks_execution.py for hook execution) is the correct approach -- avoids duplicating contract knowledge. Author has correctly identified that the static-checks slice is the right starting point. New apm validate command belongs in src/apm_cli/commands/ following existing command patterns.

APM CEO (arbiter): Accept. Well-scoped feature with an incremental contribution plan and a committed author. Static-checks slice (Phase 1) is the right entry point -- bounded scope, high value, no LLM dependency, CI-friendly exit codes. Phases 2 and 3 (hook dry-run, routing fixtures) are deferred to subsequent milestones as the author proposed. This feature directly enables the external package author persona which is central to APM's growth strategy.

---

Decision

Dimension	Value
Type	Feature
Area	CLI, Testing
Theme	Portability
Priority	High
Milestone	0.9 (Phase 1: static checks)
Suggested next action	Start with Phase 1 (static contract checks): new apm validate command, frontmatter schema validation, applyTo glob sanity check, hook manifest checks. Open a single focused PR with unit tests. Phases 2-3 can follow in separate PRs.

Labels to apply: type/feature, area/cli, area/testing, theme/portability, priority/high, status/triaged

---

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 · 53.3 AIC · ⌖ 5.6 AIC · ⊞ 9.2K · ◷