[Schema Consistency] Schema Consistency Check - 2026-03-22

[github-actions[bot]]

Summary

• Inconsistencies Found: 2 new (HIGH severity)
• Categories Analyzed: Schema, Parser/Compiler, Documentation, Workflows
• Strategy Used: Strategy-33 — New Changeset Features Audit + Close-Older Hidden Behavior Documentation Check (day 81, mod 10 = 1, proven strategy)
• Run Reference: §23400482456

Two new undocumented features were discovered by auditing the patch-prevent-cross-call-closes and patch-document-current-checkout changesets. Both relate to the close-older-issues/close-older-discussions subsystem — a feature-rich area where multiple hidden mechanisms now exist that users cannot discover from any documentation.

---

Critical Issues

(None new this run. Previous critical issues from prior runs persist.)

---

New High-Priority Findings

Finding 1 — close-older-key Field Completely Undocumented

Severity: HIGH | Type: Documentation Gap

The close-older-key field is a fully implemented deduplication mechanism for create-issue and create-discussion safe outputs, but it appears in zero documentation files.

Evidence of implementation:

Layer	Location	Status
Schema	main_workflow_schema.json lines 4313, 4855 (inside create-issue.oneOf[0] and create-discussion.oneOf[0])	✅ Present
Go struct	pkg/workflow/create_issue.go: CloseOlderKey string \yaml:"close-older-key,omitempty"``	✅ Present
Go struct	pkg/workflow/create_discussion.go: CloseOlderKey string \yaml:"close-older-key,omitempty"``	✅ Present
CJS runtime	actions/setup/js/close_older_issues.cjs:81 — uses gh-aw-close-key marker for search/filtering	✅ Present
CJS runtime	actions/setup/js/close_older_discussions.cjs:103 — same marker logic	✅ Present
CJS runtime	actions/setup/js/create_discussion.cjs:309-312 — normalizes and embeds the marker	✅ Present
Docs	safe-outputs.md, frontmatter.md, frontmatter-full.md, safe-outputs-specification.md	❌ Absent

Schema description (what users are missing):

"Optional explicit deduplication key for close-older matching. When set, a <!-- gh-aw-close-key: <value> --> marker is embedded in the issue body and used as the primary key for searching and filtering older issues instead of the workflow-id markers. This gives deterministic isolation across caller workflows and is stable across workflow renames. The value is normalized to identifier style (lowercase alphanumeric, dashes, underscores)."

Impact: Users who have workflows that share a reusable workflow (via workflow_call) cannot use close-older-key to isolate close-older operations between callers because they don't know the field exists. They must rely on the automatic gh-aw-workflow-call-id filtering (Finding 2 below), which itself is undocumented.

Schema excerpt for close-older-key

"close-older-key": {
  "type": "string",
  "description": "Optional explicit deduplication key for close-older matching. When set, a `<!-- gh-aw-close-key: <value> -->` marker is embedded in the issue body and used as the primary key for searching and filtering older issues instead of the workflow-id markers. This gives deterministic isolation across caller workflows and is stable across workflow renames. The value is normalized to identifier style (lowercase alphanumeric, dashes, underscores).",
  "minLength": 1,
  "pattern": "\\S"
}

Example usage that is currently undiscoverable:

safe-outputs:
  create-issue:
    title-prefix: "[report] "
    close-older-issues: true
    close-older-key: "my-unique-report-key"   # deterministic dedup key

---

Finding 2 — gh-aw-workflow-call-id Marker and Behavioral Change Undocumented

Severity: HIGH | Type: Documentation Gap + Behavioral Change

The patch-prevent-cross-call-closes changeset introduced a new hidden marker <!-- gh-aw-workflow-call-id: ... --> that is automatically embedded in items created in a workflow_call context. The close-older logic then uses this marker for filtering. Neither the marker nor its effect on close-older behavior is documented anywhere.

Evidence of implementation:

Layer	Location	Status
Compiler	pkg/workflow/compiler_safe_outputs_job.go:435-441 — sets GH_AW_CALLER_WORKFLOW_ID env var	✅ Present
CJS footer	actions/setup/js/generate_footer.cjs:113-122 — generateWorkflowCallIdMarker()	✅ Present
CJS add_comment	actions/setup/js/add_comment.cjs:548-551 — embeds marker when env var is set	✅ Present
CJS create_discussion	actions/setup/js/create_discussion.cjs:555 — embeds marker in discussion bodies	✅ Present
CJS close_older	actions/setup/js/close_older_issues.cjs:61 — uses workflow-call-id as exactMarker when callerWorkflowId is set	✅ Present
CJS close_older	actions/setup/js/close_older_discussions.cjs:65 — same	✅ Present
Tests	actions/setup/js/close_older_discussions.test.cjs:281 — explicitly tests filtering by call-id	✅ Present
Docs	safe-outputs.md, frontmatter.md, safe-outputs-specification.md	❌ Absent

Behavioral change: When a workflow runs via workflow_call, the compiler injects GH_AW_CALLER_WORKFLOW_ID. From that point:

1. All created items (issues, discussions, comments) include a second marker: <!-- gh-aw-workflow-call-id: owner/repo/workflow-name -->
2. Close-older operations for that workflow use this marker exclusively as the exact filter — NOT the gh-aw-workflow-id marker
3. Items created before this feature was added (without the gh-aw-workflow-call-id marker) will not be closed by close-older operations in a workflow_call context

Current documentation (safe-outputs.md:160) says:

"Searches for open issues containing the same workflow-id marker in their body"

This is now incomplete for workflow_call workflows — it actually searches by workflow-call-id marker in that context.

Code excerpt showing the filtering behavior

From close_older_issues.cjs:56-65:

} else {
  // Search for open issues with the workflow-id marker in the body
  const workflowIdMarker = getWorkflowIdMarkerContent(workflowId);
  const escapedMarker = workflowIdMarker.replace(/"/g, '\\"');
  searchQuery = `repo:\$\{owner}/\$\{repo} is:issue is:open "\$\{escapedMarker}" in:body`;
  exactMarker = callerWorkflowId
    ? generateWorkflowCallIdMarker(callerWorkflowId)  // ← uses call-id when available
    : generateWorkflowIdMarker(workflowId);            // ← falls back to workflow-id
}
// Later: items must contain exactMarker — old items without call-id will be excluded
if (!item.body?.includes(exactMarker)) { return false; }

Impact:

• Users deploying a reusable workflow with close-older-issues: true will notice that existing older issues (created before this feature) are no longer closed — with no explanation in docs
• The safe-outputs.md "Searching for Workflow-Created Items" section only documents gh-aw-workflow-id but not gh-aw-workflow-call-id, so users can't construct the correct search query for items from called workflows

---

Documentation Gaps

Previously Identified Persisting Issues (Unresolved)

Finding	Severity	First Found	File(s)
proxy-args missing from stdio_mcp_tool schema (additionalProperties:false blocks valid usage)	HIGH	2026-03-19	main_workflow_schema.json $defs/stdio_mcp_tool
Wrong codemod ID sandbox-agent-false-removal in mcp_tools_management.go:171 and gh-aw-as-mcp-server.md:284 (real ID: sandbox-false-to-agent-false)	HIGH	2026-03-21	pkg/workflow/mcp_tools_management.go, docs/.../gh-aw-as-mcp-server.md
update-discussion labels is a dead feature (schema + docs promise it, runtime has zero implementation)	HIGH	2026-03-20	update_discussion.cjs, safe_outputs_validation_config.go, both safe_outputs_tools.json
status-comment schema description stale (says "must be explicitly set to true" but compiler auto-enables for slash_command/label_command)	CRITICAL	2026-03-19	main_workflow_schema.json:1568, frontmatter-full.md:706-709
action-mode compiler error message missing action value (says dev/release/script only)	HIGH	2026-03-15	pkg/workflow/compiler.go:120
set-issue-type safe output absent from safe-outputs.md	HIGH	2026-03-07	docs/reference/safe-outputs.md
allowed-extensions schema description says default is .json,.jsonl,.txt,.md,.csv but code has empty default (all files)	MEDIUM	2026-03-16	main_workflow_schema.json, pkg/workflow/constants.go:1031

---

Recommendations

1. Document close-older-key in safe-outputs.md under the "Auto-Close Older Issues" and "Discussion Creation" sections. Add a note explaining it as a deterministic deduplication alternative to the workflow-id marker — especially valuable when multiple callers share the same reusable workflow.

2. Document the gh-aw-workflow-call-id marker in safe-outputs.md under "Searching for Workflow-Created Items". Explain:

   • Items created in a workflow_call context include this second marker
   • Close-older operations in workflow_call context filter by this marker (not workflow-id)
   • Users need the gh-aw-workflow-call-id search query format to find these items
   • Existing items without this marker won't be closed by close-older in workflow_call contexts (migration note)

3. Fix the close-older-issues doc description at safe-outputs.md:160 to accurately describe the two-phase filtering: searches by workflow-id but exact-matches workflow-call-id (or close-key) depending on context.

---

Strategy Performance

• Strategy Used: Strategy-33 — New Changeset Features Audit + Close-Older Hidden Behavior Documentation Check
• Findings: 2 new HIGH issues
• Effectiveness: HIGH — changeset archaeology reliably surfaces undocumented behavioral changes
• Should Reuse: YES — the close-older subsystem has complex marker logic; further audits of hide-older-comments for call-id behavior would be worthwhile

---

References

• §23400482456

AI generated by Schema Consistency Checker · history

• expires on Mar 23, 2026, 10:02 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Schema Consistency Checker.

A newer discussion is available at Discussion #22407.