[Schema Consistency] Schema Consistency Check – 2026-03-24

[github-actions[bot]]

Summary

• Inconsistencies Found: 4 (3 new + 1 persisting)
• Categories Analyzed: Schema, Parser/Compiler, Documentation, Workflows
• Strategy Used: Strategy-35 — Changeset-Driven Safe Output Type Completeness Audit
• Day of Year: 83 (83 mod 10 = 3 → proven strategy)
• New Strategy: No

Two fully-implemented safe output types are invisible to users in the primary reference documentation (safe-outputs.md), a new feature flag is completely undocumented, and a previously-reported schema description mismatch persists after conflicting changesets.

---

Critical Issues

🔴 HIGH — set-issue-type completely absent from safe-outputs.md

The set-issue-type safe output type is fully production-ready — it has schema definitions, Go compiler code, CJS runtime handlers, and is listed in the schema $comment — but it has zero presence in safe-outputs.md, the primary user-facing reference.

Evidence:

• Schema: main_workflow_schema.json:6938 — full object definition with allowed, max, target, target-repo, allowed-repos, staged fields
• Go: compiler_types.go:491, safe_outputs_config.go:290, compiler_safe_outputs_config.go:844, safe_outputs_config_generation.go:460, imports.go:339
• Schema $comment at line 4381 explicitly lists set-issue-type in the "Operations requiring safe-outputs" list
• frontmatter-full.md:4570 — auto-generated YAML reference only
• safe-outputs.md — no section, not listed in ToC, zero occurrences

Impact: Users cannot discover that they can configure the AI agent to set/clear GitHub Issue types. The feature is entirely invisible unless a user reads raw schema or auto-generated reference YAML.

Fix: Add a ### Set Issue Type (set-issue-type:) section to safe-outputs.md under the Issues & Discussions heading and include it in the ToC.

---

🔴 HIGH — mark-pull-request-as-ready-for-review completely absent from safe-outputs.md

Same situation: fully implemented, schema-defined, listed in the $comment permission list, but absent from the primary documentation.

Evidence:

• Schema: main_workflow_schema.json — full object with required-labels, required-title-prefix, target, max, target-repo, allowed-repos, staged fields
• Go: mark_pull_request_as_ready_for_review.go (dedicated file), compiler_types.go:464, compiler_safe_outputs_config.go:320, imports.go:323
• Schema $comment at line 4381 explicitly lists mark-pull-request-as-ready-for-review
• frontmatter-full.md:3166 and safe-outputs-specification.md:2731 — present
• safe-outputs.md — no section, not listed in the Pull Requests ToC, zero occurrences
• safe-outputs-pull-requests.md — also absent

Impact: Users building draft-PR workflows cannot discover that the agent can convert draft PRs to ready-for-review. The required-labels/required-title-prefix filter fields are especially invisible.

Fix: Add a ### Mark PR as Ready for Review (mark-pull-request-as-ready-for-review:) section to safe-outputs.md (Pull Requests section) and include it in the ToC.

---

Documentation Gaps

🟡 MEDIUM — features.copilot-requests flag completely undocumented

The CopilotRequestsFeatureFlag = "copilot-requests" feature flag (defined in pkg/constants/constants.go:722-725) has non-trivial effects on Copilot engine workflows, but is not documented anywhere in docs/.

Behavior when features.copilot-requests: true:

1. Skips the secret validation step for COPILOT_GITHUB_TOKEN (copilot_engine_installation.go:33-34)
2. Uses the GitHub Actions GITHUB_TOKEN as COPILOT_GITHUB_TOKEN instead of a PAT (copilot_engine_execution.go:216-219)
3. Injects copilot-requests: write permission into the workflow (tools.go:318-323)
4. Sets S2STOKENS=true environment variable (copilot_engine_execution.go:244)

Evidence that documentation was intended:

• The changeset patch-add-copilot-requests-feature.md explicitly says it "documented the features.copilot-requests feature flag"
• The frontmatter.md Features section only covers features.action-mode
• A search for copilot-requests across all of docs/ yields zero relevant hits

Impact: Users who need token-free Copilot authentication via GitHub Actions OIDC/S2STOKENS cannot find the flag. The auth guide (auth.mdx) only documents PAT-based COPILOT_GITHUB_TOKEN setup.

Fix: Add a #### Copilot Requests (features.copilot-requests) subsection to the Feature Flags section in frontmatter.md, explaining the four behavioral changes and when to use it.

---

Persisting Issues

🟡 MEDIUM (persisting since strategy-30) — status-comment schema description is stale after conflicting changesets

The schema description for on.status-comment (line 1603 in main_workflow_schema.json) says:

"Must be explicitly set to true to enable status comments - there is no automatic bundling with ai-reaction."

But compiler_safe_outputs.go:192-195 automatically sets StatusComment = true for slash_command and label_command triggers when not explicitly set, as introduced by the minor-enable-reaction-status-comment-by-default.md changeset:

"Enable reaction: eyes and status-comment: true by default when slash_command or label_command triggers are used."

The schema description was written for the earlier minor-decouple-status-comment.md changeset but was not updated when the default was re-enabled for command triggers.

Impact: The schema description misleads users into thinking status-comment is always opt-in, when it is actually opt-out for command-type triggers.

Fix: Update the schema description to: "Whether to post status comments (started/completed) on the triggering item. Defaults to true for slash_command and label_command triggers; must be explicitly set to true for all other trigger types. Set to false to disable even for command triggers. Not bundled with ai-reaction."

Also update frontmatter-full.md:820-825 comment which has the same stale text.

---

Schema Improvements Needed

Field	Location	Issue
on.status-comment	main_workflow_schema.json:1603	Description says "must be explicitly set to true" but auto-enabled for command triggers

Documentation Updates Required

Feature	Missing From	Present In
set-issue-type	safe-outputs.md (ToC + section)	frontmatter-full.md, schema $comment
mark-pull-request-as-ready-for-review	safe-outputs.md (ToC + section), safe-outputs-pull-requests.md	frontmatter-full.md, safe-outputs-specification.md
features.copilot-requests	frontmatter.md features section, all user docs	constants.go, 4+ workflow Go files

Recommendations

1. Add set-issue-type section to safe-outputs.md — Add to the "Issues & Discussions" ToC entry and create a ### Set Issue Type section documenting the allowed, max, target, target-repo, allowed-repos, and staged fields. This is a completed feature with no user-facing documentation.

2. Add mark-pull-request-as-ready-for-review section to safe-outputs.md — Add to the "Pull Requests" ToC entry and create a ### Mark PR as Ready for Review section. Document required-labels, required-title-prefix, target, max, and cross-repo fields.

3. Document features.copilot-requests in frontmatter.md — Add a subsection under Feature Flags describing the four behavioral changes this flag triggers, and cross-link with the Copilot authentication guide in auth.mdx.

4. Fix on.status-comment schema description — Update to accurately reflect auto-enablement for command triggers.

---

Strategy Performance

• Strategy Used: Changeset-Driven Safe Output Type Completeness Audit
• Method: Read recent changeset files → identify new features → cross-reference schema, Go code, and safe-outputs.md
• Findings: 3 new + 1 confirmed persisting
• Effectiveness: HIGH — changesets reliably flag recently-added features to audit
• Should Reuse: YES — high signal-to-noise for doc gaps on new features

---

Next Steps

• Add set-issue-type section to safe-outputs.md (ToC + documentation)
• Add mark-pull-request-as-ready-for-review section to safe-outputs.md and safe-outputs-pull-requests.md
• Document features.copilot-requests in the Feature Flags section of frontmatter.md
• Update on.status-comment schema description and frontmatter-full.md comment

References: §23473029442

AI generated by Schema Consistency Checker · history

• expires on Mar 25, 2026, 4:34 AM UTC

[github-actions[bot]]

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

A newer discussion is available at Discussion #22830.