docs: expand dispatch-repository nested fields in frontmatter-full.md

[Copilot]

dispatch-repository in the generated reference showed only {}, hiding all required nested keys (workflow, event_type, repository/allowed_repositories, inputs, max) from users who couldn't author a valid config without reading schema source.

Changes

• pkg/parser/schemas/main_workflow_schema.json: Added x-example-key: "trigger-ci" annotation to dispatch-repository and x-example-key: "repo-name" to its inputs sub-property. Updated description to call out the snake_case naming (event_type, allowed_repositories) vs. kebab-case used by adjacent safe-output fields.

• scripts/generate-schema-docs.js: Generator now handles objects annotated with x-example-key that use additionalProperties (dynamic-key maps) — renders an expanded example entry instead of bare {}. The annotation is opt-in so complex schemas like jobs are unaffected.

• scripts/generate-schema-docs.test.js: Added 5 assertions covering the expanded output (no bare {}, correct placeholder key, required fields present).

• docs/src/content/docs/reference/frontmatter-full.md: Regenerated.

Before / After

# Before
dispatch-repository:
  {}

# After
dispatch-repository:
  # Configuration for a single repository dispatch tool
  trigger-ci:
    description: "..."        # optional
    workflow: "example-value" # required
    event_type: "example-value" # required
    repository: "example-value" # optional (or use allowed_repositories)
    allowed_repositories: []
    inputs:
      repo-name:
        type: "string"
        ...
    max: 1
    github-token: "${{ secrets.GITHUB_TOKEN }}"
    staged: true

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #44456 does not have the 'implementation' label and has only 3 new lines of code in business logic directories (threshold: 100).

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

[Copilot]

Pull request overview

Improves the generated frontmatter reference documentation by expanding the dispatch-repository example so users can see the required nested fields (instead of a bare {}), using an opt-in schema annotation and generator support for dynamic-key (additionalProperties) objects.

Changes:

• Annotated dispatch-repository (and its nested inputs) with x-example-key so the doc generator can render a representative map entry.
• Updated the schema-doc generator to expand additionalProperties objects when x-example-key is present (instead of emitting {}).
• Added test assertions for the expanded output and regenerated frontmatter-full.md.

Show a summary per file

File	Description
pkg/parser/schemas/main_workflow_schema.json	Adds x-example-key annotations and clarifies snake_case nested key naming for dispatch-repository.
scripts/generate-schema-docs.js	Expands annotated dynamic-key objects (via additionalProperties) to show a representative nested schema entry.
scripts/generate-schema-docs.test.js	Adds assertions to prevent regressions where dispatch-repository renders as {}.
docs/src/content/docs/reference/frontmatter-full.md	Regenerated reference output including expanded dispatch-repository examples.
.github/workflows/daily-elixir-credo-snippet-audit.lock.yml	Includes workflow lock changes unrelated to the docs-focused PR scope.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 4/5 changed files
• Comments generated: 3
• Review effort level: Low

[github-actions]

🧪 Test Quality Sentinel Report

✅ Test Quality Score: 92/100 — Excellent

Analyzed 1 test(s): 1 design, 0 implementation, 0 violation(s).

📊 Metrics (1 test)

Metric	Value
Analyzed	1 (Go: 0, JS: 1)
✅ Design	1 (100%)
⚠️ Implementation	0 (0%)
Edge/error coverage	1 (100%)
Duplicate clusters	0
Inflation	NO (0.39:1)
🚨 Violations	0

Test	File	Classification	Issues
Test 10: dispatch-repository nested fields	scripts/generate-schema-docs.test.js:140	✅ Design	None

Verdict

✅ Passed. 0% implementation tests (threshold: 30%).

Quality Summary:

• Strong design focus: The new test validates user-facing documentation output (dispatch-repository nested fields expansion)
• Solid coverage: 5 assertions including 1 negative test (should NOT render as bare "{}") and 4 positive assertions for required fields
• Healthy test ratio: 11 test lines vs 28 production lines (0.39:1, well below 2:1 threshold)
• No violations: Proper assertion practices, no mocking violations

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• awmgmcpg

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "awmgmcpg"

See Network Configuration for more information.

🧪 Test quality analysis by Test Quality Sentinel · 18.4 AIC · ⌖ 11.6 AIC · ⊞ 6.8K · ◷
_{Comment /review to run again}

[github-actions]

✅ Test Quality Sentinel: 92/100 Excellent. 0% implementation tests (threshold: 30%). The new test validates user-facing documentation output with proper edge-case coverage.

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs and /tdd — commenting on maintainability and test-coverage gaps. The core change (expanding dispatch-repository from {} to a fully-documented example) is correct and a clear UX win for workflow authors.

📋 Key Themes & Highlights

Issues Found

• Duplicate logic (/grill-with-docs): The x-example-key expansion block is copy-pasted verbatim into both generateVariants and generateProperty. A shared helper would eliminate the duplication and make the feature easier to extend later.
• Weak test scoping (/tdd): The new assertions for event_type: and workflow: test for string presence anywhere in the full ~6 000-line output; both tokens already appear elsewhere in the doc, so those assertions would pass even if the dispatch-repository block regressed.
• Missing nested-key test (/tdd): inputs.x-example-key: "repo-name" was added to the schema but is not covered by any of the 5 new assertions.

Positive Highlights

• ✅ x-example-key is opt-in via a schema annotation — zero impact on unrelated maps like jobs
• ✅ The before/after in the PR description makes the improvement immediately legible
• ✅ assertNotContains(output, "dispatch-repository:\n {}", ...) is a solid guard against the original regression
• ✅ The schema description update calling out snake_case vs kebab-case is a nice usability note

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 68.3 AIC · ⌖ 7.35 AIC · ⊞ 6.6K
_{Comment /matt to run again}

[github-actions]

[/grill-with-docs] The x-example-key expansion block added in generateProperty (here) is an exact copy of the block added in generateVariants (line 240). Future fixes must be applied twice.

💡 Suggested refactor: extract a shared helper

function expandExampleKey(prop, indent) {
  const indentStr = " ".repeat(indent);
  const lines = [];
  const exampleKey = prop["x-example-key"];
  const addlProp = resolvePropertyRef(prop.additionalProperties);
  if (addlProp.description) {
    lines.push(formatComment(addlProp.description, indent + 2));
  }
  lines.push(`${indentStr}  ${exampleKey}:`);
  if (addlProp.properties) {
    lines.push(generateProperties(addlProp.properties, addlProp.required || [], indent + 4));
  } else {
    lines.push(`${indentStr}    {}`);
  }
  return lines;
}

Then both sites become a one-liner: lines.push(...expandExampleKey(prop, indent)). This also makes the feature easy to unit-test in isolation.

@copilot please address this.

[github-actions]

[/tdd] assertContains(output, "event_type:", ...) passes as long as event_type: appears anywhere in the ~6 000-line output, not just inside the dispatch-repository block. The same is true for workflow: (line 147). Both fields appear in many other sections, so these assertions would pass even if the dispatch-repository expansion was broken.

💡 Tighter assertion approach

Capture only the dispatch-repository slice of the output before asserting on its content:

const dispatchBlock = output.slice(
  output.indexOf("\ndispatch-repository:"),
  output.indexOf("\ndispatch_repository:")
);
allPassed &= assertContains(dispatchBlock, "event_type:", "dispatch-repository example should include 'event_type' field");
allPassed &= assertContains(dispatchBlock, "workflow:",   "dispatch-repository example should include 'workflow' field");

Or at minimum add a separate assertNotContains that would fail if the fields vanish from context.

@copilot please address this.

[github-actions]

[/tdd] There is no test for the nested x-example-key expansion: inputs.x-example-key: "repo-name" (added in the schema). The tests confirm allowed_repositories: is present but say nothing about whether inputs actually renders the repo-name sub-example or falls back to a bare key. A silent regression here would be invisible.

💡 Suggested additional assertion

allPassed &= assertContains(
  output,
  "repo-name:",
  "dispatch-repository inputs should show annotated example key 'repo-name'"
);

Or scoped to the dispatch block:

allPassed &= assertContains(
  dispatchBlock,
  "repo-name:",
  "dispatch-repository inputs example key should be expanded"
);

@copilot please address this.

[github-actions]

Request Changes — Test suite does not protect the fix it ships

The doc expansion for dispatch-repository works correctly in the generated output. The schema annotation and generateProperty implementation are sound. However, the test suite added in this PR has three compounding flaws that leave the fix completely unprotected against regression:

Blocking issues

1. Vacuously-true negative assertion (line 141): the assertNotContains pattern has no leading indent, so it never matches the indented output. Always passes regardless of whether the fix is present.

2. Positive assertions match the deprecated alias too (lines 143–149): trigger-ci:, event_type:, workflow:, and allowed_repositories: each appear twice in the output file (once for dispatch-repository, once for the deprecated dispatch_repository alias). Tests pass even if dispatch-repository reverts to bare {}.

3. Dead code in generateVariants (lines 227–237 in the diff): no x-example-key property exists inside any oneOf/anyOf array in the schema — confirmed by scanning the full JSON. The real fix is in generateProperty; this copy is dead and a future DRY violation.

4. Missing coverage for nested x-example-key (inputs→repo-name): the nested path is exercised but never asserted.

🔎 Code quality review by PR Code Quality Reviewer · 153.6 AIC · ⌖ 5.53 AIC · ⊞ 5.4K
_{Comment /review to run again}

[github-actions]

Negative assertion is vacuously true — provides zero regression protection for the core fix.

💡 Details

The test checks for the literal string "dispatch-repository:\n {}" (no leading spaces). But dispatch-repository is indented 2 spaces inside the tools: block, so the old broken output would have been " dispatch-repository:\n {}" — which does not match the searched-for unindented string.

assertNotContains always passes here, even if this fix is reverted. Verified: 'dispatch-repository:\n {}' in ' dispatch-repository:\n {}' → False.

Fix: include the leading indent in the assertion:

assertNotContains(output, "  dispatch-repository:\n    {}", "dispatch-repository should NOT render as bare '{}'");

[github-actions]

Dead/unreachable code block — x-example-key inside generateVariants can never execute with the current schema.

💡 Details

The new block at lines 227-237 (inside generateVariants) handles variant["x-example-key"] when a variant in a oneOf/anyOf array is itself a dynamic-key object. However, dispatch-repository is a plain property, not a oneOf/anyOf variant — it's handled by generateProperty, not generateVariants.

A scan of the entire schema confirms: no property annotated with x-example-key appears inside any oneOf/anyOf array. The copy in generateProperty (lines 298-313) does the actual work; the copy here is dead code today.

Beyond the dead-code issue, the two blocks are verbatim duplicates. Any future behavioural change (e.g., rendering nested descriptions differently) must be applied in both places or they'll silently diverge. Extract into a shared helper:

function renderAdditionalPropertiesExample(exampleKey, addlProp, indentStr, indent, lines) {
  if (addlProp.description) lines.push(formatComment(addlProp.description, indent + 2));
  lines.push(`${indentStr}  ${exampleKey}:`);
  if (addlProp.properties) {
    lines.push(generateProperties(addlProp.properties, addlProp.required || [], indent + 4));
  } else {
    lines.push(`${indentStr}    {}`);
  }
}

[github-actions]

Positive assertions are too broad — they match anywhere in the file, including the deprecated dispatch_repository alias that renders identically.

💡 Details

assertContains(output, "trigger-ci:"), assertContains(output, "event_type:"), assertContains(output, "workflow:"), and assertContains(output, "allowed_repositories:") scan the entire generated file. The deprecated dispatch_repository alias is rendered with the same x-example-key expansion starting at line 8391 of the output, so all four strings appear twice in the file.

These tests would pass even if dispatch-repository itself was broken (e.g., reverted to bare {}) as long as the deprecated alias still expanded correctly.

Fix: scope assertions to the context of dispatch-repository:, not the whole file:

const drIdx = output.indexOf("  dispatch-repository:");
const drSection = output.slice(drIdx, output.indexOf("\n  dispatch_repository:", drIdx));
allPassed &= assertContains(drSection, "trigger-ci:", "...");
allPassed &= assertContains(drSection, "event_type:", "...");

[github-actions]

No coverage for the nested x-example-key path (inputs → repo-name).

💡 Details

The schema adds "x-example-key": "repo-name" to the inputs sub-property of each dispatch tool entry. This exercises a second invocation of the x-example-key handling inside generateProperty (at a deeper indent level), but Test 10 never asserts that repo-name: appears in the output.

A regression in how nested x-example-key objects are indented or rendered would go undetected.

Add one assertion:

allPassed &= assertContains(output, "repo-name:", "dispatch-repository inputs should show annotated example key 'repo-name'");

[github-actions]

Review: docs: expand dispatch-repository nested fields in frontmatter-full.md

This is a high-quality docs improvement. The dispatch-repository expansion is accurate and matches the schema; all nested fields (workflow, event_type, repository, allowed_repositories, inputs, max, github-token, staged) are correctly represented with proper comments. Key observations:

• ✅ dispatch-repository expansion: correct and complete — resolves the {} usability gap
• ✅ dispatch_repository (deprecated alias): correctly mirrored
• ✅ allowed-collaborators rename: matches source (safe_outputs_config_types.go)
• ✅ {triggering_type} removal from messages comment: aligned with JSON schema description (line 10419)
• ✅ Wildcard slash_command / command docs: clear and accurate
• ✅ New permission fields (attestations, copilot-requests, id-token, models, organization-projects, etc.): well described
• ✅ restore-memory, skills additions: consistent style
• ✅ Lock file bump (gh-aw-mcpg v0.4.0 → v0.4.1): routine container bump, skipping per lock-file conventions

One non-blocking suggestion filed inline on report-failure-as-issue.

🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · 80 AIC · ⌖ 6.32 AIC · ⊞ 4.8K

Comments that could not be inline-anchored

docs/src/content/docs/reference/frontmatter-full.md:9527

The Format 1 example value (report-failure-as-issue: true) was removed, leaving only a comment description but no concrete YAML example for users to copy.

Every other multi-format field in this file shows a concrete YAML value per format. Consider restoring it:

  # Format 1: A boolean value that may also be specified as a GitHub Actions
  # expression string that resolves to a boolean at runtime.
  report-failure-as-issue: true

Without it, users relying on Format 1 have no copy…

[github-actions]

🎉 This pull request is included in a new release.

Release: v0.82.8