docs: Update handover and add lessons learned

- Update HANDOVER.md with AI agent skill section, API gotchas, session log
- Add lessons-learned.md with Gitea API findings and debugging insights

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

HANDOVER.md

@@ -203,6 +203,66 @@ To update Gitea to a new version:
 
 See `MIRRORING-GUIDE.md` for bidirectional GitHub ↔ Gitea mirroring setup.
 
+## AI Agent Skill (Gitea Task Management)
+
+Added 2026-02-18. Provides AI agents with project and task management via Gitea API.
+
+### Architecture
+
+Dual-mode: gitea-mcp (75+ tools for standard CRUD) + curl/jq shell helpers (milestones, workflow labels, dependencies -- areas where gitea-mcp has gaps).
+
+### Key Constraint
+
+Gitea 1.22.6 has NO project board REST API. Milestones serve as project containers with built-in progress tracking.
+
+### Files
+
+| File | Description |
+|------|-------------|
+| `.agents/skills/gitea/SKILL.md` | Agent skill document with all helpers |
+| `.agents/skills/gitea/setup-labels.sh` | Idempotent repo + 12 label creation |
+| `.agents/skills/gitea/test-gitea-skill.sh` | 10 integration tests (26 assertions) |
+| `.docs/RESEARCH-gitea-agent-skill.md` | Phase 1 research (verified against live) |
+| `.docs/DESIGN-gitea-agent-skill.md` | Phase 2 design document |
+
+### Default Task Repository
+
+`terraphim/agent-tasks` -- overridable via `GITEA_OWNER` and `GITEA_REPO` env vars.
+
+### Authentication
+
+```bash
+source ~/op_zesticai_non_prod.sh
+export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential")
+```
+
+### Workflow Labels
+
+12 scoped labels across 3 scopes (workflow, priority, type). Workflow state machine: `ready -> in-progress -> blocked -> done`.
+
+### Running Tests
+
+```bash
+source ~/op_zesticai_non_prod.sh
+export GITEA_TOKEN=$(op read "op://TerraphimPlatform/git.terraphim.cloud-admin-token/credential")
+.agents/skills/gitea/test-gitea-skill.sh
+```
+
+All 26 assertions pass against live Gitea 1.22.6 as of 2026-02-18.
+
+### Critical API Gotchas
+
+1. **Label exclusivity is UI-only** -- API POST `/labels` just appends. Must use PUT with label swap pattern (get current, filter `workflow:*`, add new, PUT all).
+2. **Assignees** -- Use `PATCH /issues/{index}` with `{"assignees": [...]}`. The `POST /issues/{index}/assignees` endpoint does not exist in 1.22.6.
+3. **Issue dependencies** -- Body uses `IssueMeta` format: `{"owner": "...", "repo": "...", "index": N}` (NOT `{"depends_on_id": N}`).
+
+## Pre-commit Hooks
+
+Added `.pre-commit-config.yaml` with:
+- Trailing whitespace, end-of-file fixer, YAML/JSON check
+- Merge conflict and private key detection
+- Secret detection via `detect-secrets` (baseline at `.secrets.baseline`)
+
 ## Key Files
 
 | File | Description |
@@ -213,6 +273,31 @@ See `MIRRORING-GUIDE.md` for bidirectional GitHub ↔ Gitea mirroring setup.
 | `s3_config.json.template` | SeaweedFS S3 config template |
 | `prometheus/prometheus.yml` | Prometheus scrape config |
 | `.github/workflows/*.yml` | GitHub Actions for mirroring |
+| `.agents/skills/gitea/SKILL.md` | AI agent Gitea skill |
+| `.agents/skills/gitea/setup-labels.sh` | Label setup script |
+| `.agents/skills/gitea/test-gitea-skill.sh` | Integration tests |
+| `.pre-commit-config.yaml` | Pre-commit hook config |
+
+## Session Log (2026-02-18)
+
+### Completed
+- Rewrote Gitea agent skill with verified API patterns (milestones, workflow labels, dependencies)
+- Created setup-labels.sh for idempotent repo + label creation
+- Created test-gitea-skill.sh with 10 tests (26 assertions), all passing
+- Found and fixed 3 API behavior bugs (label exclusivity, assignee endpoint, dependency format)
+- Added pre-commit hooks and fixed trailing whitespace across 15 files
+- Conducted disciplined research and design phases with live API verification
+
+### Commits (unpushed)
+- `b67284e` chore: Fix trailing whitespace across project files
+- `66b305d` feat(gitea-skill): Add integration tests and fix workflow label swap
+- `1fd202d` feat(gitea-skill): Rewrite Gitea agent skill with verified API patterns
+
+### Next Steps
+1. Push 3 commits to origin/main
+2. Consider adding gitea-mcp or forgejo-mcp as MCP server for Claude Code (see SKILL.md MCP Integration section)
+3. Create first real milestone and tasks in `terraphim/agent-tasks` for a project
+4. Consider Phase 4 (disciplined-verification) if more rigorous validation is needed
 
 ## Contacts
 

lessons-learned.md

@@ -0,0 +1,65 @@
+# Lessons Learned
+
+## Session: 2026-02-18 -- Gitea Agent Skill Implementation
+
+### Technical Discoveries
+
+1. **Gitea 1.22.6 has no project board REST API**
+   - `/api/v1/user/projects` returns 404
+   - The existing SKILL.md had endpoints that do not exist
+   - Project board API is tracked in Gitea issue #14299, targeted for 1.26+
+   - **Mitigation:** Use milestones as project containers -- they have built-in progress tracking
+
+2. **Scoped label exclusivity is UI-only in Gitea 1.22.6**
+   - Labels with `exclusive: true` display mutual exclusivity in the web UI
+   - The API `POST /repos/{owner}/{repo}/issues/{index}/labels` only appends -- it does NOT remove conflicting scoped labels
+   - **Fix:** Use a swap pattern: GET current labels, filter out old scope, add new label ID, PUT full set atomically
+   - This was the single biggest "gotcha" -- the documentation implies API enforcement that does not exist
+
+3. **POST /issues/{index}/assignees does not exist in Gitea 1.22.6**
+   - Returns 404
+   - **Fix:** Use `PATCH /repos/{owner}/{repo}/issues/{index}` with `{"assignees": ["username"]}`
+   - This is a general issue edit endpoint, not a dedicated assignee endpoint
+
+4. **Issue dependency format is IssueMeta, not simple ID**
+   - Wrong: `{"depends_on_id": 2}` -- returns "repository does not exist [id: 0]"
+   - Correct: `{"owner": "terraphim", "repo": "agent-tasks", "index": 2}`
+   - Must check the Swagger spec for exact body format rather than guessing
+
+### Debugging Approaches That Worked
+
+1. **Test against live API first, then write code**
+   - Verified all 7 open questions against the live Gitea instance before writing any helper functions
+   - This caught the project board API gap before writing fake endpoints
+
+2. **Integration tests with real cleanup**
+   - Each test run creates a timestamped repo (`skill-test-{timestamp}`), runs all tests, then deletes it
+   - Trap on EXIT ensures cleanup even on failure
+   - No mocks -- tests prove the actual API behavior
+
+3. **Incremental testing (run, fail, fix, rerun)**
+   - First test run: 23/26 pass, 3 fail -- immediately identified the label/assignee issues
+   - Fixed the swap pattern and PATCH approach, second run: 26/26 pass
+
+### Pitfalls to Avoid
+
+1. **Do not trust Gitea documentation for API behavior** -- always verify against the live instance. The swagger spec is the source of truth, but even that can be misleading for edge cases like scoped label exclusivity.
+
+2. **Do not assume POST endpoints exist for every resource subpath** -- Gitea's API is inconsistent. Some resources (labels) have POST, others (assignees) only work via PATCH on the parent resource.
+
+3. **Do not rely on UBS scanner for infrastructure projects** -- UBS found no scannable language files (expected for a project with only shell scripts, YAML, and markdown). Pre-commit hooks are more useful here.
+
+4. **Pre-commit python version** -- The system may not have the Python version specified in `.pre-commit-config.yaml`. Changed from `python3.9` to `python3.12` to match the system. Also needed `python3.12-venv` apt package for virtualenv support.
+
+### Best Practices Discovered
+
+1. **Disciplined development phases work well for API integration**
+   - Phase 1 (Research): Discovered the project board API gap before design
+   - Phase 2 (Design): Created the label swap architecture before implementation
+   - Phase 3 (Implementation): Tests caught 3 API bugs on first run
+
+2. **Default repository pattern** -- Using env vars with defaults (`GITEA_OWNER=${GITEA_OWNER:-terraphim}`) lets agents work out of the box while remaining configurable.
+
+3. **JSON output from all helpers** -- Every shell function outputs valid JSON, making it trivial for agents to parse results with jq.
+
+4. **Idempotent setup scripts** -- `setup-labels.sh` checks for existing resources before creating, making it safe to run repeatedly.