feat: align FrontMatter fields with gh-aw schema — run-name, labels, metadata, tracker-id, source, strict

## Front Matter Alignment Proposal: ado-aw ↔ gh-aw

This issue was filed automatically by the `frontmatter-aligner` workflow after detecting schema drift between the [gh-aw syntax reference](https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/syntax.md) and the `FrontMatter` struct in `src/compile/types.rs`.

### Alignment Summary

The following fields exist in gh-aw but are absent from ado-aw. Fields that are GitHub Actions–only (e.g. `github-token`, `runs-on`, `environment`, `secrets`, `jobs`, `on.forks`), require major architectural work (`imports`, `import-schema`, `experiments`), or have ADO-specific equivalents already present (e.g. `permissions`, `timeout-minutes`, `env`, `steps`, `post-steps`, `runtimes`, `mcp-servers`) were excluded.

| Field | gh-aw | ado-aw (current) | Notes |
|-------|-------|------------------|-------|
| `run-name` | ✅ | ❌ | Customize the pipeline run name displayed in the ADO UI |
| `labels` | ✅ | ❌ | Top-level categorization array; lets tooling filter/search agent files |
| `metadata` | ✅ | ❌ | Arbitrary key-value pairs; useful for governance, team ownership, and priority tagging |
| `tracker-id` | ✅ | ❌ | Identifier inserted into all safe-output assets (work items, comments, PRs, wiki pages); enables later search/retrieval |
| `source` | ✅ | ❌ | Origin tracking (`owner/repo/path@ref`) for shared/imported agent files |
| `strict` | ✅ | ❌ | Enables enhanced compile-time validation (errors instead of warnings); defaults to `true` to match gh-aw |

---

### Proposed Changes to `src/compile/types.rs`

All additions go inside `pub struct FrontMatter { ... }` after the `parameters` field, and a single helper function is added before `impl FrontMatter`.

#### `run-name`

**Where to add**: `FrontMatter` struct, after `parameters` field.

```rust
/// Custom pipeline run name surfaced in the Azure DevOps UI.
/// When set, overrides the default auto-generated run name.
/// Aligned with gh-aw's `run-name` frontmatter field.
#[serde(default, rename = "run-name")]
pub run_name: Option,
```

**Does it need compiler wiring?** Yes — the generated pipeline YAML should set the ADO `name:` property at the top level (ADO run name) when this field is present.

---

#### `labels`

**Where to add**: `FrontMatter` struct, after `run_name`.

```rust
/// Labels for categorizing and organizing this agent workflow.
/// Metadata only — does not affect pipeline execution.
/// Aligned with gh-aw's top-level `labels` frontmatter field.
#[serde(default)]
pub labels: Vec,
```

**Does it need compiler wiring?** No — parsing and storing is sufficient for now. Future tooling (list/search commands) can consume this.

---

#### `metadata`

**Where to add**: `FrontMatter` struct, after `labels`.

```rust
/// Arbitrary key-value metadata pairs.
/// Key names limited to 64 characters; values limited to 1024 characters.
/// Aligned with gh-aw's `metadata` frontmatter field.
#[serde(default)]
pub metadata: HashMap,
```

**Does it need compiler wiring?** No — parsing and storing is sufficient for now.

---

#### `tracker-id`

**Where to add**: `FrontMatter` struct, after `metadata`.

```rust
/// Optional identifier inserted into the body/description of all safe-output
/// assets created by this workflow (work items, comments, PRs, wiki pages).
/// Must be ≥ 8 characters and contain only alphanumeric characters, hyphens,
/// and underscores. Enables searching for assets linked to this workflow.
/// Aligned with gh-aw's `tracker-id` frontmatter field.
#[serde(default, rename = "tracker-id")]
pub tracker_id: Option,
```

**Does it need compiler wiring?** Yes — the value should be validated at compile time (regex `^[a-zA-Z0-9_-]{8,}$`) and passed to the Stage 3 executor (e.g., via an env var or safe-output config) so safe-output tools can append it to created assets.

---

#### `source`

**Where to add**: `FrontMatter` struct, after `tracker_id`.

```rust
/// Workflow origin tracking in the format `owner/repo/path@ref`.
/// Records where this agent file was originally sourced from.
/// Aligned with gh-aw's `source` frontmatter field.
#[serde(default)]
pub source: Option,
```

**Does it need compiler wiring?** No — metadata only for now.

---

#### `strict`

**Where to add**: `FrontMatter` struct, after `source`. Also add a module-level helper function before `impl FrontMatter`.

```rust
/// Enable strict compile-time validation (boolean, default: `true`).
/// When `false`, certain compile-time errors are downgraded to warnings.
/// Must be `true` in production workflows.
/// Aligned with gh-aw's `strict` frontmatter field.
#[serde(default = "crate::compile::types::default_true")]
pub strict: bool,
```

```rust
/// Returns `true`, used as the serde default for boolean fields that default to true.
pub fn default_true() -> bool {
true
}
```

**Does it need compiler wiring?** Yes — the compiler should check this flag and gate any "strict-mode" validation errors (e.g., future validation rules that are warnings in lenient mode and errors in strict mode).

---

### Proposed Changes to `docs/front-matter.md`

Add the following entries to the front matter reference (e.g., in a new "Workflow Metadata" section after the "Build and Test" section, or inline with the existing YAML example block):

````markdown
## Workflow Metadata

These optional fields carry metadata about the agent workflow and do not directly affect pipeline execution unless noted.

### `run-name`

```yaml
run-name: "Fix issue #$\{\{ parameters.issue_number }}"
```

Custom pipeline run name displayed in the Azure DevOps UI. When omitted, ADO generates a default run name. Equivalent to gh-aw's `run-name` field.

---

### `labels`

```yaml
labels: [automation, security, daily]
```

Array of strings for categorizing and organizing agent files. Labels are metadata only and do not affect pipeline execution. Useful for filtering agent files with tooling. Equivalent to gh-aw's `labels` field.

---

### `metadata`

```yaml
metadata:
team: platform
priority: high
```

Custom key-value pairs. Key names limited to 64 characters; values limited to 1024 characters. Useful for governance, team ownership, and priority tagging. Equivalent to gh-aw's `metadata` field.

---

### `tracker-id`

```yaml
tracker-id: "team-alpha-bot"
```

Optional identifier inserted into the body/description of all safe-output assets created by this workflow (work items, comments, pull requests, wiki pages). Must be at least 8 characters and contain only alphanumeric characters, hyphens (`-`), and underscores (`_`). Enables later search and retrieval of all assets linked to this workflow. Equivalent to gh-aw's `tracker-id` field.

---

### `source`

```yaml
source: "myorg/shared-agents/triage-bot.md@main"
```

Workflow origin tracking in `owner/repo/path@ref` format. Records where this agent file was originally sourced from (e.g., when copying a shared workflow template). Metadata only. Equivalent to gh-aw's `source` field.

---

### `strict`

```yaml
strict: true # default
```

Enables enhanced compile-time validation. Defaults to `true`. When set to `false`, certain compile-time errors are downgraded to warnings (useful during development or migration). Should remain `true` in production workflows. Equivalent to gh-aw's `strict` field.
````

---

### Validation

`cargo check` passed with all proposed changes applied (only expected "never read" dead-code warnings on the new parsing-only fields).

---

*Filed automatically by the frontmatter-aligner workflow.*

> Generated by [Front Matter Aligner: ado-aw ↔ gh-aw](https://github.com/githubnext/ado-aw/actions/runs/25531295914/agentic_workflow) · ● 717.8K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fado-aw+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fado-aw%2Ffrontmatter-aligner%22&type=issues)