[awf-feature-surfacing] Surface recent AWF schema features in docs: regenerate frontmatter reference + document resource-attributes, normalize-closing-k [Content truncated due to length]

[github-actions]

Summary

The daily AWF spec-compiler surfacing review found that several user-facing AWF schema capabilities merged in the last 7 days are not surfaced in the documentation. The root cause is that the auto-generated frontmatter reference is stale, plus a couple of features lack any hand-written coverage.

This is the first run of the surfacing reviewer (no prior state), so the diff window was built from the GitHub API over the last 7 days.

New schema features detected (last 7 days)

Feature (schema key)	PR	Surfacing status
observability.otlp.resource-attributes	#39636	❌ Gap — 0 doc mentions anywhere
safe-outputs.*.normalize-closing-keywords (create-issue / add-comment / create-pull-request)	#39643	⚠️ Gap — only in one experimental sample
repo-memory format-json	#39540	⚠️ Partial — only in repo-memory.md; missing from generated reference
report-failure-as-issue failure-category filtering	#39721	✅ Surfaced (safe-outputs reference)
create-discussion required-category	#39640	✅ Surfaced
array/object runner specs (runs-on-slim, safe-outputs.runs-on, detection runs-on)	#39654 / #38965	✅ Surfaced
cross-repo dispatch allowed-repos	#39080	✅ Surfaced (incl. ADR)
threat-detection max-ai-credits	#38456	✅ Surfaced (incl. ADR)

Core finding: generated frontmatter reference is stale

docs/src/content/docs/reference/frontmatter-full.md is auto-generated from the JSON Schema (make generate-schema-docs → node scripts/generate-schema-docs.js), but it is out of sync with the current schema. It documents every observability.otlp key except the newly added resource-attributes, and is also missing normalize-closing-keywords and format-json.

Evidence

• Schema path confirmed present: properties/observability/properties/otlp/properties/resource-attributes in pkg/parser/schemas/main_workflow_schema.json.
• Generated doc last regenerated at commit 69e4c042 (Support array/object runner specs for runs-on-slim and safe-outputs runner fields #39654, 2026-06-16); the generator header states: "This documentation is automatically generated from the JSON Schema."
• Present/missing check against frontmatter-full.md:
  • MISSING: resource-attributes, normalize-closing-keywords, format-json
  • PRESENT: required-category, runs-on-slim, allowed-repos, max-ai-credits
• Compiler implementation of resource-attributes: pkg/workflow/observability_otlp.go, pkg/workflow/compiler_orchestrator_workflow.go, pkg/workflow/frontmatter_types.go.

Follow-up tasks

1. Regenerate the schema-derived frontmatter reference — Priority: HIGH

Run make generate-schema-docs and commit the refreshed docs/src/content/docs/reference/frontmatter-full.md. This mechanically picks up resource-attributes, normalize-closing-keywords, and format-json. Consider a CI check that fails when the generated doc drifts from the schema, to prevent recurrence.

2. Document observability.otlp.resource-attributes in hand-written docs — Priority: HIGH

Feature (#39636): additional OTEL_RESOURCE_ATTRIBUTES entries appended to the standard gh-aw/GitHub resource attributes; values may be static strings or GitHub Actions expressions; must not use secrets.* / vars.* (exported to external tracing backends, not treated as secret). Add coverage to the observability section of .github/aw/syntax-agentic.md (already documents OTLP) and the relevant hand-written observability/audit reference, including the no-secrets safety note.

3. Document normalize-closing-keywords in canonical safe-outputs docs — Priority: MEDIUM

Feature (#39643): when true, strips backticks from recognized issue-closing keywords (e.g. `Closes #1` → Closes #1) in body fields. Applies to create-issue, add-comment, and create-pull-request. Currently only referenced in docs/.../experimental/safe-outputs-samples.md. Add it to the canonical safe-outputs reference and the agent-facing .github/aw/safe-outputs-content.md.

4. Verify format-json survives regeneration — Priority: LOW

repo-memory format-json (#39540) is documented in repo-memory.md but absent from the generated reference; confirm task 1 restores it.

Notes

• Cosmetic/refactor commits in-window were excluded (e.g. legacy model_multipliers.json removal Remove legacy model_multipliers.json artifacts and file-based multiplier merge path #38642, "effective tokens"→"AI Credits" rename Replace "effective tokens" with "AI Credits" in user-facing text #38481).
• No duplicate open issues found for these feature IDs.
• Tracked feature IDs persisted to repo-memory (awf-feature-surfacing/progress.json).

Generated by 🧭 Daily AWF Spec Compiler Surfacing Review · ◷

• expires on Jun 24, 2026, 2:53 PM UTC-08:00

[github-actions]

This issue is being closed as outdated. A newer issue has been created: #40397

View newer issue

---

This action was performed automatically by the Daily AWF Spec Compiler Surfacing Review workflow.