Skip to content

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

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions