clavitor/docs/YURII-GITEA-CLI.md

Yurii's Gitea CLI Workflow

Tool: tea — Gitea command line interface
Installed: /usr/local/bin/tea
Gitea Server: https://git.clavitor.ai Repository Structure: Monorepo (johan/clavitor) — all issues go here, not sub-repos

⚠️ Important: Monorepo Pattern

Clavitor uses a monorepo — one repository contains all subprojects:

• clavis-vault/ → Issues in johan/clavitor
• clavis-telemetry/ → Issues in johan/clavitor
• clavitor.ai/ → Issues in johan/clavitor

Never create issues in johan/clavis-* repos — those are mirrors only.

Always use: --repo johan/clavitor

---

Setup (One-time)

# Login to Gitea server
tea login add --name clavitor --url https://git.clavitor.ai --token 775a12730a65cbaf1673da048b7d01859b8b58e0

# Verify
tea whoami
# Should show: johan (admin)

---

Yurii's Daily Workflow

Step 1: Audit Code (Read-only)

# Clone repo for analysis (local copy, no changes)
cd /tmp
tea repos clone johan/clavis-telemetry

# Or analyze existing checkout
cd /home/johan/dev/clavitor/clavis/clavis-telemetry

# Run audit per CLAVITOR-AGENT-HANDBOOK.md Section II
grep -rn "return nil" --include="*.go" | head -20
grep -rn "catch.*{" --include="*.js" | head -10

Step 2: Create Issues (Never Code)

# ⚠️ IMPORTANT: Use --repo johan/clavitor (monorepo)
# NOT --repo johan/clavis-telemetry (that repo has no issues enabled)

# Issue #1: Missing error codes
tea issues create --repo johan/clavitor \
  --title "Yurii: Missing unique error codes (Cardinal Rule #1)" \
  --description "$(cat <<'EOF'
## Violation
File: clavis/clavis-telemetry/main.go:45
Current: Generic error without ERR-XXXXX code

## Required
Per Section II: All errors must have unique codes

## Assignment
- Fix by: @hans
- Priority: Medium
EOF
)" \
  --assignees hans \
  --label "security,violation"

# Issue #2: Silent DB errors (CRITICAL)
tea issues create --repo johan/clavis-telemetry \
  --title "CRITICAL: Silent database error in updateSpan()" \
  --description "$(cat <<'EOF'
## Violation
File: main.go:187
Current: `if err != nil { return nil }` — silent failure

## Threat
Operational blindness during incidents. No forensic trail.

## Required
Per Cardinal Rule #1: Return explicit error with ERR-50004

## Assignment
- Fix by: Hans
- Priority: Critical
- Review by: Yurii (after fix)
EOF
)" \
  --assignee hans \
  --label "security,critical,cardinal-rule-1"

# Issue #3: Kuma silent failure (CRITICAL)
tea issues create --repo johan/clavis-telemetry \
  --title "CRITICAL: Silent failure in Kuma push" \
  --description "Violates Cardinal Rule #1. See kuma.go line 34." \
  --assignee hans \
  --label "security,critical"

# Issue #4: Tarpit flush error
tea issues create --repo johan/clavis-telemetry \
  --title "Yurii: Unchecked flush error in tarpit" \
  --description "main.go unchecked error. Add handling or explicit ignore with comment." \
  --assignee hans \
  --label "violation"

Step 3: Track Issues

# List all issues created by Yurii
tea issues list --repo johan/clavis-telemetry --assignee hans

# Check status
tea issues view <issue-number>

Step 4: Review Engineer PRs (After Hans Fixes)

# List open PRs
tea pulls list --repo johan/clavis-telemetry

# Review a specific PR
tea pulls view <pr-number>

# Comment on PR (requesting changes)
tea pulls comment <pr-number> --message "✓ Fixes Issue #2. ✗ Missing test coverage. Add test before merge."

# Approve PR (when ready)
tea pulls comment <pr-number> --message "✓ All issues addressed. Approved."

---

Yurii's Rules (From Handbook)

Can Do	Cannot Do
tea issues create	tea pulls create (no code)
tea pulls comment	tea pushes (no commits)
tea repos clone (read)	tea merges (no merging)
grep, audit, analyze	SSH to prod to fix

Violation = Process Failure: If Yurii pushes code instead of creating Issue → restart, assign to engineer.

---

Known CLI Limitations & Workarounds

1. Labels Don't Show in List View (Bug)

Problem: tea issues list shows empty LABELS column even when labels exist.
Workaround: View individual issue to see labels:

tea issues view <number>  # Shows labels properly

Status: Gitea CLI bug — labels ARE saved, just not displayed in list.

2. User Discovery is Hard

Problem: Can't find valid usernames for --assignees.
Workaround: Use these known agent usernames:

sarah, charles, maria, james, xiao, emma, arthur, victoria,
luna, thomas, hugo, hans, george, shakib, yurii

Or check web UI: https://git.clavitor.ai/johan/clavitor/settings/collaboration

3. "No gitea login detected" Noise

Problem: Every command shows: NOTE: no gitea login detected, falling back to login 'clavitor'
Workaround: Ignore it — it's just noise, commands still work.

4. --assignees Flag (Plural, Not --assignee)

Correct: --assignees hans
Incorrect: --assignee hans (this fails silently)

---

Quick Reference

# Create issue (use --assignees, not --assignee)
tea issues create --repo johan/clavitor \
  --title "Title" \
  --description "Body" \
  --assignees hans  # ← plural!

# List issues (labels won't show — use view for details)
tea issues list --repo johan/clavitor

# View specific (shows labels correctly)
tea issues view <number>

# List PRs
tea pulls list --repo johan/clavitor

# Comment
tea issues comment <number> --message "text"
tea pulls comment <number> --message "text"

# List labels (if you need to check)
curl -s https://git.clavitor.ai/api/v1/repos/johan/clavitor/labels | grep name

# Help
tea --help
tea issues --help
tea pulls --help

---

Example: Complete Yurii Session

# 1. Audit
cd /home/johan/dev/clavitor/clavis/clavis-telemetry
grep -n "return nil" clavis/clavis-telemetry/main.go
# Found: line 187 silent error

# 2. Create issue (NOTE: use johan/clavitor, NOT clavis-telemetry)
tea issues create --repo johan/clavitor \
  --title "CRITICAL: Silent error in telemetry at main.go:187" \
  --description "$(cat <<'EOF'
## Violation
File: clavis/clavis-telemetry/main.go:187
Current: `if err != nil { return nil }` — silent failure

## Threat
Operational blindness during incidents. No forensic trail.

## Required
Per Cardinal Rule #1: Return explicit error with ERR-50004

## Assignment
- Fix by: @hans
- Priority: Critical
EOF
)" \
  --assignees hans

# 3. Done. Hans gets notification, creates fix PR.

# 4. Later: Review Hans' PR
tea pulls list --repo johan/clavitor
tea pulls view 5
tea pulls comment 5 --message "✓ Fixes Issue #2. Approved."

---

**Yurii's output:** Issues in Gitea  
**Hans' input:** Issues assigned to him  
**Result:** Clean separation of audit and implementation