Skip to content

[task] Add strict-mode reference documentation in frontmatter.md #4208

@github-actions

Description

@github-actions

Objective

Add comprehensive reference documentation for the strict-mode CLI feature in the frontmatter reference guide.

Context

The schema consistency audit (Discussion #4177) found that while strict-mode is mentioned in guides/security.md, it lacks detailed documentation in the reference documentation. Users need clear guidance on what strict mode does and how to use it.

Related to #4177

Current State

  • Brief mention: docs/src/content/docs/guides/security.md:124-126
  • Missing from: docs/src/content/docs/reference/frontmatter.md
  • Missing from: docs/src/content/docs/setup/cli.md (CLI reference)

Proposed Approach

Add a dedicated section in the appropriate documentation file(s):

  1. In frontmatter.md - Add note that this is CLI-only in the "Agentic Workflow Specific Fields" section
  2. In cli.md - Document the --strict flag with full details

Suggested Content Structure

### Strict Mode (CLI-only)

Strict mode enforces enhanced security and validation rules during compilation. Enable via CLI flag:

\`\`\`bash
gh aw compile --strict
\`\`\`

**Enforcement Areas:**
- **Action Pinning**: Requires all GitHub Actions to be pinned to specific commit SHAs
- **Network Permissions**: Requires explicit network configuration (no implicit defaults)
- **Write Permissions**: Requires use of safe-outputs for GitHub API write operations
- **Bash Tool Restrictions**: Restricts wildcard usage in bash tool configurations

**Note**: Strict mode is a CLI-only feature and cannot be configured in workflow frontmatter.

Files to Modify

  • docs/src/content/docs/reference/frontmatter.md - Add CLI-only features note
  • docs/src/content/docs/setup/cli.md - Add --strict flag documentation
  • Consider adding to docs/src/content/docs/guides/security.md - Expand existing mention

Acceptance Criteria

  • Reference documentation includes strict-mode section
  • Documentation clearly states it's CLI-only
  • All four enforcement areas are documented
  • Examples show CLI usage: gh aw compile --strict
  • Cross-references to related security guide sections
  • Follows Diátaxis framework (reference style)

Related Files

Implementation references:

AI generated by Plan Command for discussion #4177

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions