diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md new file mode 100644 index 0000000..429b949 --- /dev/null +++ b/.github/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog — .github Directory + +All notable changes to workflows, automation, and .github folder structure. + +## [2025-01-27] Gitea Actions Workflows Setup + +### Added +- **`.github/README.md`** - .github directory overview +- **`.github/CHANGELOG.md`** - Workflow change tracking (this file) +- **`.github/decisions.md`** - Automation decisions +- **`.github/LLM-Usage-Guide--tendril.md`** - LLM instructions for workflows +- **`.github/workflows/kb-lint.yml`** - KB file validation workflow +- **`.github/workflows/kb-index-update.yml`** - KB index auto-update workflow + +### Notes +- Phase 3 Gitea Actions Workflows Setup completed +- All workflows use Gitea Actions (compatible with GitHub Actions format) +- Workflows configured for Tendril repository structure +- KB lint workflow validates all KB file naming and frontmatter rules +- KB index update workflow automatically regenerates index on push to main + +--- + diff --git a/.github/LLM-Usage-Guide--tendril.md b/.github/LLM-Usage-Guide--tendril.md new file mode 100644 index 0000000..1ab01af --- /dev/null +++ b/.github/LLM-Usage-Guide--tendril.md @@ -0,0 +1,240 @@ +# LLM Usage Guide for Gitea Actions Workflows — tendril + +_Last updated: 2025-01-27_ + +## Purpose + +This guide provides instructions for AI assistants (LLMs) on how to work with Gitea Actions workflows, automation, and the `.github/` directory structure in this repository. + +**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure. + +--- + +## Repository Context + +**Repository**: tendril +**Repository URL**: https://git.parkingmeter.info/Mycelium/tendril +**Platform**: Gitea (self-hosted) +**Primary System**: Tendril - Zed IDE extension for Gitea integration +**Automation Focus**: KB system validation and index maintenance + +--- + +## Understanding .github Directory Structure + +### Workflows (`workflows/`) + +Gitea Actions workflows automate repository operations: + +- **`kb-lint.yml`** - Validates KB file naming, frontmatter, and structure +- **`kb-index-update.yml`** - Auto-updates KB index on push to main when KB files change + +### Documentation + +- **`README.md`** - Overview of .github directory and workflows +- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder +- **`decisions.md`** - Documents decisions about workflows and automation +- **`LLM-Usage-Guide--tendril.md`** (this file) - LLM instructions for this repo + +--- + +## Working with Workflows + +### When Modifying Workflows + +**MANDATORY**: When any workflow file is modified: + +1. **Update `.github/CHANGELOG.md`**: + - Add entry with date and description + - Document what changed and why + - Include affected workflow name + +2. **Update `.github/decisions.md`** (if decision-related): + - Document the decision behind the change + - Explain rationale and alternatives considered + - Note impact on automation + +3. **Update `.github/README.md`** (if structure changes): + - Update workflow descriptions if behavior changed + - Add new workflows to overview + - Remove references to deleted workflows + +4. **Test the workflow**: + - Use `workflow_dispatch` trigger if available + - Verify expected behavior + - Check for errors in Gitea Actions tab + +5. **Consult Gitea documentation**: + - Reference `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance + - Note any Gitea-specific differences from GitHub Actions + +### When Adding New Workflows + +1. Create workflow file in `.github/workflows/` +2. Update `.github/CHANGELOG.md` - Document new workflow +3. Update `.github/decisions.md` - Document why workflow was added +4. Update `.github/README.md` - Add to workflow overview +5. Test workflow - Verify it runs successfully +6. Update this guide - Add instructions if needed + +### When Removing Workflows + +1. Update `.github/CHANGELOG.md` - Document removal and reason +2. Update `.github/decisions.md` - Document why workflow was removed +3. Update `.github/README.md` - Remove from overview +4. Update this guide - Remove references + +--- + +## Workflow-Specific Instructions + +### KB Lint Workflow + +**File**: `.github/workflows/kb-lint.yml` + +**Purpose**: Validates KB file naming, frontmatter, and structure on push and pull requests + +**When to modify**: +- KB validation rules change +- KB file naming pattern changes +- Frontmatter requirements change +- New validation rules needed + +**Validation Rules**: +- Filename pattern: `YYYY-MM-DD--slug--type.md` +- Frontmatter must exist and be valid YAML +- All 18 required fields must be present +- Date in frontmatter must match filename date +- Type in frontmatter must match filename type +- `routing_confidence` must be numeric 0.00-1.00 +- Files with `routing_confidence < 0.60` must be in `_review_queue/` + +**Exclusions**: +- `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md` are excluded from validation + +**Validation**: +- Workflow runs on push and pull requests when `kb/**/*.md` files change +- Provides clear error messages for each validation failure +- Exits with error code if any validation fails + +--- + +### KB Index Update Workflow + +**File**: `.github/workflows/kb-index-update.yml` + +**Purpose**: Automatically regenerates `kb/_index.md` when KB files change on main branch + +**When to modify**: +- Index generation script changes +- Index update logic needs modification +- Commit message format needs change +- Branch name changes (if not using `main`) + +**Workflow Steps**: +1. Checkout repository +2. Run `kb/scripts/generate-index.sh` +3. Check if `kb/_index.md` changed +4. If changed, commit and push update +5. Use git user: "Gitea Actions" + +**Validation**: +- Workflow runs on push to `main` branch when `kb/**/*.md` files change +- Excludes `_guides/`, `_templates/`, `README.md`, `_index.md`, `CHANGELOG.md` +- Uses `|| exit 0` to handle case where index hasn't changed +- Requires `contents: write` permission to push changes + +--- + +## Documentation Maintenance + +### .github/CHANGELOG.md + +**Purpose**: Track all changes to workflows and .github folder + +**Format**: +```markdown +## [YYYY-MM-DD] Brief Description + +### Added +- New workflow or feature + +### Changed +- Modified workflow behavior + +### Fixed +- Bug fix or correction +``` + +**When to update**: Every time a workflow file is modified + +### .github/decisions.md + +**Purpose**: Document decisions about workflows and automation + +**Format**: +```markdown +### [YYYY-MM-DD] Decision Title + +**Context**: What prompted this decision +**Decision**: What was decided +**Rationale**: Why this approach +**Alternatives**: Other options considered +**Impact**: What this affects +``` + +**When to update**: When making significant workflow decisions + +--- + +## Common Tasks + +### Adding a New Workflow + +1. Create workflow file in `.github/workflows/` +2. Add workflow to `.github/README.md` overview +3. Document in `.github/CHANGELOG.md` +4. Document decision in `.github/decisions.md` (if applicable) +5. Test workflow with `workflow_dispatch` (if available) +6. Commit all changes together + +### Modifying an Existing Workflow + +1. Make workflow changes +2. Update `.github/CHANGELOG.md` with change description +3. Update `.github/decisions.md` if decision-related +4. Update `.github/README.md` if behavior changed significantly +5. Test workflow +6. Commit changes + +--- + +## Validation Checklist + +Before committing workflow changes: + +- [ ] Workflow file syntax is valid YAML +- [ ] Workflow tested with `workflow_dispatch` (if available) +- [ ] `.github/CHANGELOG.md` updated with change description +- [ ] `.github/decisions.md` updated (if decision-related) +- [ ] `.github/README.md` updated (if structure/behavior changed) +- [ ] All changes committed together +- [ ] Commit message follows conventional format: `ci(workflows): description` +- [ ] Consulted `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance + +--- + +## Gitea-Specific Notes + +- **Platform**: Gitea (self-hosted) +- **Actions**: Gitea Actions (compatible with GitHub Actions format) +- **Runners**: Must be configured on Gitea instance +- **Documentation**: See `docs/GITEA/Gitea-Actions-Guide.md` for detailed guidance +- **API**: See `docs/GITEA/Gitea-API-Reference.md` for API differences + +--- + +**Repository**: `tendril` +**Location**: `.github/LLM-Usage-Guide--tendril.md` +**Maintained by**: Tendril Project Team + diff --git a/.github/README.md b/.github/README.md new file mode 100644 index 0000000..6316967 --- /dev/null +++ b/.github/README.md @@ -0,0 +1,83 @@ +# .github Directory + +_Last updated: 2025-01-27_ + +## Purpose + +The `.github/` directory contains Gitea Actions workflows, issue templates, and documentation for repository automation and maintenance. + +**Note**: Gitea Actions is compatible with GitHub Actions, so workflows use the same YAML format and `.github/` directory structure. + +--- + +## Contents + +### Workflows (`workflows/`) + +Gitea Actions workflows that automate various aspects of the repository: + +- **`kb-lint.yml`** - Validates KB file naming, frontmatter, and structure +- **`kb-index-update.yml`** - Auto-updates KB index on push to main when KB files change + +### Documentation + +- **`README.md`** (this file) - Overview of .github directory structure and purpose +- **`CHANGELOG.md`** - Tracks all changes to workflows and .github folder +- **`decisions.md`** - Documents decisions about workflows, automation, and Gitea Actions +- **`LLM-Usage-Guide--tendril.md`** - LLM instructions for this repository's workflows and automation + +--- + +## Workflow Overview + +### KB Lint + +- **Triggers**: Push and pull requests when `kb/**/*.md` files change +- **Purpose**: Validates KB file naming, frontmatter, and structure +- **Output**: Pass/fail validation results + +### KB Index Update + +- **Triggers**: Push to `main` branch when `kb/**/*.md` files change +- **Purpose**: Automatically regenerates `kb/_index.md` when KB files are added or modified +- **Output**: Updated `kb/_index.md` file committed to repository + +--- + +## Maintenance + +### When Adding New Workflows + +1. **Update `CHANGELOG.md`** - Document the new workflow and its purpose +2. **Update `decisions.md`** - Document why this workflow was added +3. **Update this README** - Add workflow to the overview section +4. **Update `LLM-Usage-Guide--tendril.md`** - Add instructions for the new workflow + +### When Modifying Existing Workflows + +1. **Update `CHANGELOG.md`** - Document what changed and why +2. **Update `decisions.md`** - Document the decision behind the change +3. **Test workflow** - Verify changes work as expected +4. **Update documentation** - Ensure README and LLM guide reflect changes + +### When Removing Workflows + +1. **Update `CHANGELOG.md`** - Document removal and reason +2. **Update `decisions.md`** - Document why workflow was removed +3. **Update this README** - Remove from overview +4. **Update `LLM-Usage-Guide--tendril.md`** - Remove references + +--- + +## Gitea Platform Notes + +- **Repository**: https://git.parkingmeter.info/Mycelium/tendril +- **Platform**: Gitea (self-hosted) +- **Actions System**: Gitea Actions (compatible with GitHub Actions format) +- **Documentation**: See `docs/GITEA/Gitea-Actions-Guide.md` for Gitea-specific guidance + +--- + +**Location**: `.github/` +**Maintained by**: Tendril Project Team + diff --git a/.github/decisions.md b/.github/decisions.md new file mode 100644 index 0000000..ea1040c --- /dev/null +++ b/.github/decisions.md @@ -0,0 +1,111 @@ +# Decisions — .github Directory + +_Last updated: 2025-01-27_ + +## Purpose + +This document tracks decisions made about Gitea Actions workflows, automation, and the .github directory structure. Decisions are documented with context, rationale, and alternatives considered. + +--- + +## Decision Format + +Each decision entry includes: +- **Date**: When the decision was made +- **Context**: What problem or need prompted this decision +- **Decision**: What was decided +- **Rationale**: Why this approach was chosen +- **Alternatives**: Other options considered +- **Impact**: What this affects + +--- + +## Decisions + +### [2025-01-27] Use Gitea Actions (not GitHub Actions) + +**Context**: Repository is hosted on Gitea platform (self-hosted), not GitHub. Need to configure CI/CD automation for repository maintenance. + +**Decision**: Use Gitea Actions with GitHub Actions compatibility. + +**Rationale**: +- Gitea Actions uses the same YAML format as GitHub Actions +- Workflows are compatible and can be migrated seamlessly +- Same `.github/workflows/` directory structure +- Familiar syntax for developers +- No need to learn a different workflow system + +**Alternatives Considered**: +- Use GitHub Actions (not possible - repository is on Gitea) +- Use external CI/CD service (adds complexity, external dependency) +- Manual automation (not scalable, error-prone) + +**Impact**: +- All workflows use `.github/workflows/` structure +- Workflows use standard GitHub Actions YAML format +- Documentation references "Gitea Actions" with compatibility notes +- Workflows can be tested and run on Gitea platform + +--- + +### [2025-01-27] Automate KB Index Updates + +**Context**: KB index (`kb/_index.md`) must stay current with KB files. Manual updates are error-prone and easy to forget. + +**Decision**: Auto-update index on push to main branch when KB files change. + +**Rationale**: +- Reduces manual maintenance burden +- Ensures index always reflects current KB state +- Prevents index from becoming stale +- Automated process is more reliable than manual updates +- Index generation script already exists and works + +**Alternatives Considered**: +- Manual index updates (error-prone, easy to forget) +- Update on every push (too frequent, unnecessary commits) +- Scheduled updates (may miss recent changes) + +**Impact**: +- Index is automatically updated when KB files are added/modified on main +- Requires `contents: write` permission for workflow +- Creates automatic commits with index updates +- Index always reflects current KB state + +--- + +### [2025-01-27] Validate KB Files in CI + +**Context**: KB files must follow strict naming and frontmatter rules. Invalid files break the KB system and cause index generation to fail. + +**Decision**: Validate KB files on push and pull requests when KB files change. + +**Rationale**: +- Catch errors early before they reach main branch +- Maintain KB system integrity +- Prevent invalid files from breaking index generation +- Provide clear error messages for developers +- Enforce KB file standards automatically + +**Alternatives Considered**: +- Manual validation (error-prone, easy to miss) +- Validate only on main branch (errors caught too late) +- No validation (system breaks with invalid files) + +**Impact**: +- Invalid KB files block commits +- Developers get immediate feedback on errors +- KB system maintains high quality standards +- Requires `contents: read` permission for workflow + +--- + +## Future Decisions + +Decisions about new workflows, automation changes, or .github structure modifications should be added here with the same format. + +--- + +**Location**: `.github/decisions.md` +**Maintained by**: Tendril Project Team + diff --git a/.github/workflows/kb-index-update.yml b/.github/workflows/kb-index-update.yml new file mode 100644 index 0000000..b64b969 --- /dev/null +++ b/.github/workflows/kb-index-update.yml @@ -0,0 +1,43 @@ +name: Update KB Index + +on: + push: + branches: [ main ] + paths: + - 'kb/**/*.md' + +permissions: + contents: write + +jobs: + update: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + fetch-depth: 0 + + - name: Generate index + run: | + chmod +x kb/scripts/generate-index.sh + ./kb/scripts/generate-index.sh + + - name: Check for changes + id: check + run: | + if git diff --quiet kb/_index.md; then + echo "changed=false" >> $GITHUB_OUTPUT + else + echo "changed=true" >> $GITHUB_OUTPUT + fi + + - name: Commit changes + if: steps.check.outputs.changed == 'true' + run: | + git config user.name "Gitea Actions" + git config user.email "actions@gitea.io" + git add kb/_index.md + git commit -m "chore: update KB index [skip ci]" || exit 0 + git push + diff --git a/.github/workflows/kb-lint.yml b/.github/workflows/kb-lint.yml new file mode 100644 index 0000000..cf00f5e --- /dev/null +++ b/.github/workflows/kb-lint.yml @@ -0,0 +1,165 @@ +name: KB Lint + +on: + push: + paths: + - 'kb/**/*.md' + pull_request: + paths: + - 'kb/**/*.md' + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate KB Files + run: | + set -e + + # Colors for output + RED='\033[0;31m' + GREEN='\033[0;32m' + YELLOW='\033[1;33m' + NC='\033[0m' # No Color + + echo "Validating KB files..." + + # Find all KB files that changed + if [ "${{ github.event_name }}" = "pull_request" ]; then + # For pull requests, check changed files + changed_files=$(git diff --name-only --diff-filter=ACMR origin/${{ github.base_ref }}...HEAD -- 'kb/**/*.md' || true) + else + # For push, check all KB files + changed_files=$(git diff --name-only --diff-filter=ACMR HEAD~1...HEAD -- 'kb/**/*.md' || find kb -type f -name "*.md" 2>/dev/null || true) + fi + + if [ -z "$changed_files" ]; then + echo "No KB files changed, skipping validation" + exit 0 + fi + + errors=0 + + # Process each changed file + while IFS= read -r file; do + # Skip empty lines + [ -z "$file" ] && continue + + # Skip if file doesn't exist (deleted files) + [ ! -f "$file" ] && continue + + # Skip special directories and files + if [[ "$file" == *"/_guides/"* ]] || \ + [[ "$file" == *"/_templates/"* ]] || \ + [[ "$file" == "kb/README.md" ]] || \ + [[ "$file" == "kb/_index.md" ]] || \ + [[ "$file" == "kb/CHANGELOG.md" ]]; then + echo -e "${YELLOW}⏭️ Skipping: $file (excluded from validation)${NC}" + continue + fi + + filename=$(basename "$file") + relative_path="${file#kb/}" + file_errors=0 + + echo -e "\n${GREEN}Validating: $file${NC}" + + # Validate filename pattern + if ! [[ "$filename" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}--[a-z0-9-]+--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$ ]]; then + echo -e "${RED}❌ ERROR: Invalid filename pattern${NC}" + echo " Expected: YYYY-MM-DD--slug--type.md" + echo " Got: $filename" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + + # Extract date and type from filename + filename_date=$(echo "$filename" | sed -E 's/^([0-9]{4}-[0-9]{2}-[0-9]{2})--.*/\1/') + filename_type=$(echo "$filename" | sed -E 's/.*--([a-z]+)(--p[0-9]+)?\.md$/\1/') + + # Check frontmatter exists + if ! grep -q "^---$" "$file"; then + echo -e "${RED}❌ ERROR: Missing frontmatter delimiter${NC}" + echo " File must start with '---'" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + + # Extract frontmatter + frontmatter=$(sed -n '/^---$/,/^---$/p' "$file" | sed '1d;$d') + + if [ -z "$frontmatter" ]; then + echo -e "${RED}❌ ERROR: Empty frontmatter${NC}" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + + # Check required fields (14 base fields) + REQUIRED_FIELDS=("title" "date" "author" "source" "project" "topics" "tags" "type" "status" "routing_hint" "proposed_path" "routing_confidence" "related" "summary") + for field in "${REQUIRED_FIELDS[@]}"; do + if ! echo "$frontmatter" | grep -q "^${field}:"; then + echo -e "${RED}❌ ERROR: Missing required field: $field${NC}" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + done + + # Validate date matches + frontmatter_date=$(echo "$frontmatter" | grep "^date:" | sed -E 's/^date:[[:space:]]*["'\'']?([^"'\'']+)["'\'']?.*/\1/' | tr -d ' ' | head -1) + if [ "$frontmatter_date" != "$filename_date" ]; then + echo -e "${RED}❌ ERROR: Date mismatch${NC}" + echo " Filename date: $filename_date" + echo " Frontmatter date: $frontmatter_date" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + + # Validate type matches + frontmatter_type=$(echo "$frontmatter" | grep "^type:" | sed -E 's/^type:[[:space:]]*["'\'']?([^"'\'']+)["'\'']?.*/\1/' | tr -d ' ' | head -1) + if [ "$frontmatter_type" != "$filename_type" ]; then + echo -e "${RED}❌ ERROR: Type mismatch${NC}" + echo " Filename type: $filename_type" + echo " Frontmatter type: $frontmatter_type" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + + # Validate routing_confidence + routing_confidence=$(echo "$frontmatter" | grep "^routing_confidence:" | sed -E 's/^routing_confidence:[[:space:]]*([0-9.]+).*/\1/' | tr -d ' ' | head -1) + if ! awk -v conf="$routing_confidence" 'BEGIN {if (conf < 0.0 || conf > 1.0 || conf == "") exit 1}' 2>/dev/null; then + echo -e "${RED}❌ ERROR: Invalid routing_confidence value${NC}" + echo " Value: $routing_confidence" + echo " Must be numeric between 0.00 and 1.00" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + + # Enforce review queue policy + if awk -v conf="$routing_confidence" 'BEGIN {exit !(conf < 0.60)}' 2>/dev/null; then + if [[ "$file" != *"/_review_queue/"* ]]; then + echo -e "${RED}❌ ERROR: File has routing_confidence < 0.60 but is not in kb/_review_queue/${NC}" + echo " routing_confidence: $routing_confidence" + echo " File path: $file" + file_errors=$((file_errors + 1)) + errors=$((errors + 1)) + fi + fi + + if [ $file_errors -eq 0 ]; then + echo -e "${GREEN}✅ Valid: $file${NC}" + fi + done <<< "$changed_files" + + if [ $errors -gt 0 ]; then + echo -e "\n${RED}Validation failed with $errors error(s)${NC}" + exit 1 + else + echo -e "\n${GREEN}All KB files validated successfully${NC}" + exit 0 + fi + diff --git a/kb/_index.md b/kb/_index.md index ed57fd0..41cfeae 100644 --- a/kb/_index.md +++ b/kb/_index.md @@ -17,4 +17,4 @@ This index is automatically generated from KB file metadata. It provides searcha - **Unique Tags**: 0 - **Phases Referenced**: 0 -_Index generated on 2025-11-11 11:41:41_ +_Index generated on 2025-11-11 11:53:11_