Document strict mode enforcement areas and CLI flag in schema

[Copilot]

Task: Document strict mode feature comprehensively in JSON schema

Based on the issue #4193 and @pelikhan's comment, the task is to improve the documentation of the strict field in the JSON schema to make it more comprehensive.

Completed

• Understand the current state of strict mode implementation and documentation
• Review the strict mode enforcement areas in the codebase
• Review the CLI flag implementation (gh aw compile --strict)
• Update the strict field description in pkg/parser/schemas/main_workflow_schema.json to include:
  • All enforcement areas (write permissions, network config, action pinning, deprecated fields, MCP network)
  • Reference to CLI flag: gh aw compile --strict
  • Note that CLI flag takes precedence over frontmatter
  • Documentation links for more details
• Update CLI help text for --strict flag to be more comprehensive
• Add test to verify schema documentation completeness
• Run tests to ensure no regressions
• Verify the schema still validates correctly
• Fix formatting issues (gofmt)
• All linting checks pass

Changes Made

pkg/parser/schemas/main_workflow_schema.json:

• Updated strict field description from brief summary to comprehensive documentation
• Added all 5 enforcement areas: write permissions, network config, action pinning, MCP network, deprecated fields
• Added CLI flag reference and precedence rule
• Added documentation link

cmd/gh-aw/main.go:

• Updated CLI help text for --strict flag from brief to comprehensive
• Now mentions: action pinning, network config, safe-outputs, write permissions, deprecated fields

pkg/parser/schema_strict_documentation_test.go:

• Added test to verify schema documentation contains all required elements
• Validates presence of enforcement areas, CLI flag reference, and documentation link
• Ensures schema field type is correctly set to boolean
• Fixed formatting with gofmt

Verification

• ✅ Schema JSON validates correctly
• ✅ All unit tests pass (make test-unit)
• ✅ New test passes and validates documentation completeness
• ✅ Binary builds successfully (make build)
• ✅ Test workflows compile correctly with strict mode
• ✅ CLI flag enforcement works as expected
• ✅ Schema validation catches invalid values
• ✅ All linting checks pass (make lint)
• ✅ Code formatting passes (make fmt-check)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Document CLI-only strict-mode feature in JSON schema</issue_title>
<issue_description>## Objective
Add schema documentation for the strict-mode CLI-only feature to improve developer understanding and IDE tooling support.

Context

The schema consistency audit (Discussion #4177) identified that strict-mode is extensively implemented in the compiler but has no representation in main_workflow_schema.json. This creates a gap where users and IDE tooling have no schema-level indication that strict mode exists as a CLI feature.

Related to #4177

Current State

• Implementation: Extensive (15+ test files, compiler.go:111, strict_mode.go, etc.)
• Documentation: Mentioned in guides/security.md but NOT in reference/frontmatter.md
• Schema: No entry in main_workflow_schema.json
• Usage: CLI-only via gh aw compile --strict flag

Proposed Approach

Add a $comment field or dedicated section in the schema to document CLI-only features:

{
  "$comment": "CLI-ONLY: strict-mode is set via gh-aw CLI flag --strict, not in frontmatter",
  "strict-mode": {
    "type": "null",
    "description": "This field is not configurable in frontmatter. Strict mode is enabled via CLI flag: gh aw compile --strict. Enforces action pinning, network configuration, and safe-outputs usage."
  }
}

Files to Modify

• pkg/parser/schemas/main_workflow_schema.json - Add CLI-only features section or $comment
• Consider adding to schema definitions or a dedicated x-cli-features section

Acceptance Criteria

• Schema includes documentation for strict-mode as CLI-only feature
• Documentation clearly states it cannot be set in frontmatter
• Documentation references the CLI flag: gh aw compile --strict
• Documentation lists enforcement areas (action pinning, network config, safe-outputs)
• Schema validation still passes (strict-mode should not accept frontmatter values)
• Run make test to ensure no regressions

Additional Context

Enforcement areas documented in implementation:

• Action pinning (requires SHA pins)
• Network permissions (requires explicit configuration)
• Write permissions (requires safe-outputs)
• Bash tool restrictions
  Related to [Schema Consistency] 🔍 Schema Consistency Check - 2025-11-17: 83% Consistency Rate (CLI-Only Feature Gap) #4177

AI generated by Plan Command for discussion #4177</issue_description>

Comments on the Issue (you are @copilot in this section)

@pelikhan @copilot the equivalent in the schema is "strict". make sure it is documented.

• Fixes [task] Document CLI-only strict-mode feature in JSON schema #4207

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@copilot lint

[Copilot]

Pull Request Overview

This PR expands the documentation for the strict field in the main workflow schema to provide comprehensive information about strict mode enforcement areas and CLI usage. The changes aim to improve IDE tooling support and developer understanding by documenting what strict mode actually validates.

Key changes:

• Expanded the strict field description from 127 characters to 704 characters with detailed enforcement areas
• Added CLI flag reference and precedence behavior documentation
• Created a test to validate the presence of required documentation elements
• Updated CLI help text to match the enhanced schema documentation

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
pkg/parser/schemas/main_workflow_schema.json	Expanded strict field description with 5 enforcement areas, CLI usage, and documentation link
pkg/parser/schema_strict_documentation_test.go	Added validation test to ensure schema documentation completeness
cmd/gh-aw/main.go	Enhanced CLI help text for --strict flag to match schema comprehensiveness

Critical Issue: The documentation claims that strict mode enforces "Action Pinning" (actions pinned to commit SHAs), but this is not directly implemented in the strict mode validation code. Action pinning validation only occurs when the optional --zizmor flag is used alongside --strict. This creates a discrepancy between the documented and actual behavior.

---

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

[Copilot]

@copilot lint

Linting complete. Fixed formatting issue in schema_strict_documentation_test.go (commit 6dfdb00). All checks pass:

• ✅ make lint - passed
• ✅ make fmt-check - passed
• ✅ make test-unit - passed
• ✅ make golint - passed