Fix Glossary Maintainer workflow: Move documentation skill to .github folder and add compiler validation (#14637)

Copilot · web-flow · commit 3cb56e4b2dc9 · 2026-02-09T03:39:11.000-08:00
diff --git a/.github/skills/documentation/SKILL.md b/.github/skills/documentation/SKILL.md
@@ -0,0 +1,241 @@
+---
+name: documentation
+description: Documentation Brief description for SEO and navigation
+---
+
+### Documentation
+
+The documentation for this project is available in the `docs/` directory. It uses GitHub-flavored markdown with Astro Starlight for rendering and follows the Diátaxis framework for systematic documentation.
+
+## Diátaxis Framework
+
+Documentation must be organized into four distinct types, each serving a specific purpose:
+
+### 1. Tutorials (Learning-Oriented)
+**Purpose**: Guide beginners through achieving a specific outcome to build confidence.
+
+- Start with what the user will build or achieve
+- Provide a clear, step-by-step path from start to finish
+- Include concrete examples and working code
+- Assume minimal prior knowledge
+- Focus on the happy path (avoid edge cases and alternatives)
+- End with a working result the user can see and use
+- Use imperative mood: "Create a file", "Run the command"
+
+**Avoid**: Explaining concepts in depth, multiple options, troubleshooting
+
+### 2. How-to Guides (Goal-Oriented)
+**Purpose**: Show how to solve a specific real-world problem or accomplish a particular task.
+
+- Title format: "How to [accomplish specific goal]"
+- Assume the user knows the basics
+- Focus on practical steps to solve one problem
+- Include necessary context but stay focused
+- Show multiple approaches only when genuinely useful
+- End when the goal is achieved
+- Use imperative mood: "Configure the setting", "Add the following"
+
+**Avoid**: Teaching fundamentals, explaining every detail, being exhaustive
+
+### 3. Reference (Information-Oriented)
+**Purpose**: Provide accurate, complete technical descriptions of the system.
+
+- Organized by structure (CLI commands, configuration options, API endpoints)
+- Comprehensive and authoritative
+- Consistent format across all entries
+- Technical accuracy is paramount
+- Include all parameters, options, and return values
+- Use descriptive mood: "The command accepts", "Returns a string"
+- Minimal narrative or explanation
+
+**Avoid**: Instructions, tutorials, opinions on usage
+
+### 4. Explanation (Understanding-Oriented)
+**Purpose**: Clarify and illuminate topics to deepen understanding.
+
+- Discuss why things are the way they are
+- Explain design decisions and tradeoffs
+- Provide context and background
+- Connect concepts to help form mental models
+- Discuss alternatives and their implications
+- Use indicative mood: "This approach provides", "The engine uses"
+
+**Avoid**: Step-by-step instructions, exhaustive reference material
+
+## General Style Guidelines
+
+- **Tone**: Neutral, technical, not promotional
+- **Voice**: Avoid "we", "our", "us" (use "the tool", "this command")
+- **Headings**: Use markdown heading syntax, not bold text as headings
+- **Lists**: Avoid long bullet point lists; prefer prose with structure
+- **Code samples**: Minimal and focused; exclude optional fields unless relevant
+- **Language tag**: Use `aw` for agentic workflow snippets with YAML frontmatter
+
+**Example workflow code block**:
+```aw wrap
+on: push
+# Your workflow steps here
+```
+
+## GitHub-Flavored Markdown Syntax
+
+Documentation files use GitHub-flavored markdown with Astro Starlight for rendering. Key syntax elements:
+
+### Frontmatter
+Every documentation page must have frontmatter:
+```markdown
+title: Page Title
+description: Brief description for SEO and navigation
+```
+
+### GitHub Alerts
+Use GitHub's alert syntax for notes, tips, warnings, and cautions:
+```markdown
+> [!NOTE]
+> Important information the reader should notice.
+
+> [!TIP]
+> Helpful advice for the reader.
+
+> [!WARNING]
+> Warning about potential issues or pitfalls.
+
+> [!CAUTION]
+> Critical warning about dangerous operations.
+
+> [!IMPORTANT]
+> Key information users need to know.
+```
+
+### Code Blocks
+- Use syntax highlighting with language tags
+- Add `title` attribute for file names: ` ```yaml title=".github/workflows/example.yml" `
+- Use `aw` language for agentic workflow files with YAML frontmatter
+- Add `wrap` for line wrapping: ` ```aw wrap `
+
+### Links
+- Internal links: Use relative paths between documentation pages
+- External links: Open in new tab automatically
+- Link text: Use descriptive text, avoid "click here"
+
+### Tabs
+Use tabs for showing alternatives (e.g., different languages, platforms):
+```markdown
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+<Tabs>
+  <TabItem label="npm">
+    ```bash
+    npm install package
+    ```
+  </TabItem>
+  <TabItem label="yarn">
+    ```bash
+    yarn add package
+    ```
+  </TabItem>
+</Tabs>
+```
+
+### Cards
+Use cards for navigation or highlighting multiple options:
+```markdown
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+<CardGrid>
+  <Card title="Getting Started" icon="rocket">
+    Quick introduction to the basics.
+  </Card>
+  <Card title="Advanced Usage" icon="setting">
+    Deep dive into advanced features.
+  </Card>
+</CardGrid>
+```
+
+**Remember**: Keep components minimal. Prefer standard markdown when possible.
+
+## Content to Avoid
+
+- "Key Features" sections
+- Marketing language or selling points
+- Excessive bullet points (prefer structured prose)
+- Overly verbose examples with all optional parameters
+- Mixing documentation types (e.g., tutorials that become reference)
+
+## Avoiding Documentation Bloat
+
+Documentation bloat reduces clarity and makes content harder to navigate. Common types of bloat include:
+
+### Types of Documentation Bloat
+
+1. **Duplicate content**: Same information repeated in different sections
+2. **Excessive bullet points**: Long lists that could be condensed into prose or tables
+3. **Redundant examples**: Multiple examples showing the same concept
+4. **Verbose descriptions**: Overly wordy explanations that could be more concise
+5. **Repetitive structure**: The same "What it does" / "Why it's valuable" pattern overused
+
+### Writing Concise Documentation
+
+When editing documentation, focus on:
+
+**Consolidate bullet points**: 
+- Convert long bullet lists into concise prose or tables
+- Remove redundant points that say the same thing differently
+
+**Eliminate duplicates**:
+- Remove repeated information
+- Consolidate similar sections
+
+**Condense verbose text**:
+- Make descriptions more direct and concise
+- Remove filler words and phrases
+- Keep technical accuracy while reducing word count
+
+**Standardize structure**:
+- Reduce repetitive "What it does" / "Why it's valuable" patterns
+- Use varied, natural language
+
+**Simplify code samples**:
+- Remove unnecessary complexity from code examples
+- Focus on demonstrating the core concept clearly
+- Eliminate boilerplate or setup code unless essential for understanding
+- Keep examples minimal yet complete
+- Use realistic but simple scenarios
+
+### Example: Before and After
+
+**Before (Bloated)**:
+```markdown
+### Tool Name
+Description of the tool.
+
+- **What it does**: This tool does X, Y, and Z
+- **Why it's valuable**: It's valuable because A, B, and C
+- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
+- **When to use**: Use it when you need X
+- **Benefits**: Gets you benefit A, benefit B, benefit C
+- **Learn more**: [Link](url)
+```
+
+**After (Concise)**:
+```markdown
+### Tool Name
+Description of the tool that does X, Y, and Z to achieve A, B, and C.
+
+Use it when you need X by following steps 1-5. [Learn more](url)
+```
+
+### Documentation Quality Guidelines
+
+1. **Preserve meaning**: Never lose important information
+2. **Be surgical**: Make precise edits, don't rewrite everything
+3. **Maintain tone**: Keep the neutral, technical tone
+4. **Test locally**: Verify links and formatting are still correct
+
+## Structure by File Type
+
+- **Getting Started**: Tutorial format
+- **How-to Guides**: Goal-oriented, one task per guide
+- **CLI Reference**: Reference format, complete command documentation
+- **Concepts**: Explanation format, building understanding
+- **API Reference**: Reference format, complete API documentation
diff --git a/.github/workflows/glossary-maintainer.lock.yml b/.github/workflows/glossary-maintainer.lock.yml
diff --git a/.github/workflows/glossary-maintainer.md b/.github/workflows/glossary-maintainer.md
@@ -24,7 +24,7 @@ network:
 
 imports:
   - shared/mood.md
-  - ../../skills/documentation/SKILL.md
+  - ../skills/documentation/SKILL.md
   - ../agents/technical-doc-writer.agent.md
 
 safe-outputs:
diff --git a/.github/workflows/technical-doc-writer.lock.yml b/.github/workflows/technical-doc-writer.lock.yml
diff --git a/.github/workflows/technical-doc-writer.md b/.github/workflows/technical-doc-writer.md
@@ -25,7 +25,7 @@ network:
 
 imports:
   - shared/mood.md
-  - ../../skills/documentation/SKILL.md
+  - ../skills/documentation/SKILL.md
   - ../agents/technical-doc-writer.agent.md
 
 safe-outputs:
diff --git a/pkg/parser/remote_fetch.go b/pkg/parser/remote_fetch.go
@@ -117,6 +117,31 @@ func ResolveIncludePath(filePath, baseDir string, cache *ImportCache) (string, e
 	remoteLog.Printf("Using local file resolution for: %s", filePath)
 	// Regular path, resolve relative to base directory
 	fullPath := filepath.Join(baseDir, filePath)
+	
+	// Security check: ensure the resolved path is within the .github folder
+	// baseDir should be .github or a subdirectory within it
+	githubFolder := baseDir
+	// Find the .github folder by traversing up from baseDir
+	for !strings.HasSuffix(githubFolder, ".github") && githubFolder != "." && githubFolder != "/" {
+		githubFolder = filepath.Dir(githubFolder)
+		if githubFolder == "." || githubFolder == "/" {
+			// If we can't find .github folder, use baseDir
+			githubFolder = baseDir
+			break
+		}
+	}
+	
+	// Normalize paths for comparison
+	normalizedGithubFolder := filepath.Clean(githubFolder)
+	normalizedFullPath := filepath.Clean(fullPath)
+	
+	// Check if fullPath is within githubFolder
+	relativePath, err := filepath.Rel(normalizedGithubFolder, normalizedFullPath)
+	if err != nil || relativePath == ".." || strings.HasPrefix(relativePath, ".."+string(filepath.Separator)) || filepath.IsAbs(relativePath) {
+		remoteLog.Printf("Security: Path escapes .github folder: %s (resolves to: %s)", filePath, relativePath)
+		return "", fmt.Errorf("Security: Path %s must be within .github folder (resolves to: %s)", filePath, relativePath)
+	}
+	
 	if _, err := os.Stat(fullPath); os.IsNotExist(err) {
 		remoteLog.Printf("Local file not found: %s", fullPath)
 		// Return a simple error that will be wrapped with source location by the caller
diff --git a/pkg/workflow/expression_validation.go b/pkg/workflow/expression_validation.go
@@ -412,6 +412,16 @@ func validateRuntimeImportFiles(markdownContent string, workspaceDir string) err
 		githubFolder := filepath.Join(workspaceDir, ".github")
 		absolutePath := filepath.Join(githubFolder, normalizedPath)
 
+		// Security check: ensure the resolved path is within the .github folder
+		// Use filepath.Rel to check if the path escapes the .github folder
+		normalizedGithubFolder := filepath.Clean(githubFolder)
+		normalizedAbsolutePath := filepath.Clean(absolutePath)
+		relativePath, err := filepath.Rel(normalizedGithubFolder, normalizedAbsolutePath)
+		if err != nil || relativePath == ".." || strings.HasPrefix(relativePath, ".."+string(filepath.Separator)) || filepath.IsAbs(relativePath) {
+			validationErrors = append(validationErrors, fmt.Sprintf("%s: Security: Path must be within .github folder (resolves to: %s)", filePath, relativePath))
+			continue
+		}
+
 		// Check if file exists
 		if _, err := os.Stat(absolutePath); os.IsNotExist(err) {
 			// Skip validation for optional imports ({{#runtime-import? ...}})
