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

[github-actions]

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 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.

/// 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<String>,

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.

/// 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<String>,

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.

/// 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<String, String>,

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

---

tracker-id

Where to add: FrontMatter struct, after metadata.

/// 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<String>,

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.

/// 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<String>,

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.

/// 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,

/// 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):

## 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 · ● 717.8K · ◷