Frank
63219787af
Point the mattpocock-lineage skills (triage, to-tickets, to-spec, wayfinder) at repo facts instead of a parallel docs/ tree: Gitea is the issue tracker (credential-safe curl shape, token-only writes), the five canonical triage roles keep their default label strings (created on the tracker today), and GLOSSARY.md/docs/adr/ stay lazy with this vault owning operational facts. AGENTS.md gains the ## Agent skills pointer block; indices regenerated.
86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
---
|
|
type: reference
|
|
title: Issue Tracker
|
|
description: "How agent skills read and write Gitea issues here: credential-safe curl, label IDs, and wayfinding without sub-issues."
|
|
tags: [agent, gitea, issues, triage, api]
|
|
timestamp: 2026-10-20T00:00:00Z
|
|
---
|
|
|
|
# Issue Tracker
|
|
|
|
Issues and specs for this repo live as Gitea issues in `dank/serverAppConfigs`
|
|
on `http://192.168.0.143:3000` (Dankclaw). There is no `gh`/`glab` CLI here —
|
|
the door is the GitHub-compatible REST API driven with `curl`. The
|
|
mattpocock-lineage skills (`/triage`, `/to-tickets`, `/to-spec`, `/wayfinder`)
|
|
read this page as their tracker contract. The git workflow around issues and
|
|
PRs (branches, PR-only merges, attribution footer) is owned by
|
|
[[Deployment Flow]]; this page owns only the API shape.
|
|
|
|
## Auth
|
|
|
|
The token lives in the git credential file `~/.config/secrets/gitea`: one
|
|
line in git-credential URL form, `http://user:TOKEN@192.168.0.143`. Extract it
|
|
without echoing:
|
|
|
|
```bash
|
|
tok=$(sed -nE 's#^http://[^:/@]+:([^@]+)@192\.168\.0\.143.*#\1#p' ~/.config/secrets/gitea | head -1)
|
|
```
|
|
|
|
**A token on a command line is world-readable in `/proc/<pid>/cmdline`** (the
|
|
same leak class AGENTS.md records for HF tokens). Never pass it with `-H` —
|
|
put it in a mode-600 curl config and pass `-K`:
|
|
|
|
```bash
|
|
cfg=$(mktemp); chmod 600 "$cfg"
|
|
printf 'header = "Authorization: token %s"\n' "$tok" > "$cfg"
|
|
# ... every curl below uses -K "$cfg"; rm -f "$cfg" when done
|
|
```
|
|
|
|
**GETs also accept HTTP Basic; writes do not** — a POST/PATCH with Basic auth
|
|
is refused with `422 {"message":"token is required"}` (measured 2026-10-20).
|
|
Use the `Authorization: token` header for everything.
|
|
|
|
## Conventions
|
|
|
|
`$API=http://192.168.0.143:3000/api/v1/repos/dank/serverAppConfigs`
|
|
|
|
- **Create an issue**: `curl -s -K "$cfg" -X POST -H 'Content-Type: application/json' -d "$(jq -n --arg t "$TITLE" --rawfile b "$BODY" '{title:$t, body:$b}')" $API/issues`
|
|
- **Read an issue**: `curl -s -K "$cfg" $API/issues/<number>` (fields: `number`, `title`, `body`, `labels[].name`, `state`)
|
|
- **List issues**: `curl -s -K "$cfg" "$API/issues?state=open&limit=50"` — add `&labels=<id>` to filter
|
|
- **Comment**: `curl -s -K "$cfg" -X POST -d "$(jq -n --rawfile b "$BODY" '{body:$b}')" $API/issues/<number>/comments`
|
|
- **Apply labels**: `POST $API/issues/<number>/labels` with `{"labels":[<label-ID numbers>]}` — Gitea wants numeric label **IDs**, not names; resolve them from `GET $API/labels` (see [[Triage Labels]] for which labels exist)
|
|
- **Remove a label**: `DELETE $API/issues/<number>/labels/<label-id>`
|
|
- **Close**: `PATCH $API/issues/<number>` with `{"state":"closed"}`
|
|
- **Blocking relationships**: this instance has no native sub-issues or dependencies — put `Part of #<parent>` / `Blocked by: #<n>, #<n>` lines at the top of the child body. A ticket is unblocked when every listed blocker is closed.
|
|
- **Attribution footer (repo law)**: every issue body you open ends with `cwd: <working directory> · session: <omp session id>` — full rule in [[Deployment Flow]].
|
|
|
|
**PRs as a request surface: no.** Issues and PRs have separate number spaces on
|
|
Gitea; a bare `#42` is an issue, a PR is spelled "PR #42".
|
|
|
|
## When a skill says "publish to the issue tracker"
|
|
|
|
Create a Gitea issue as above.
|
|
|
|
## When a skill says "fetch the relevant ticket"
|
|
|
|
`GET $API/issues/<number>` and read `title` + `body` + `labels[].name` +
|
|
comments.
|
|
|
|
## Wayfinding operations
|
|
|
|
Used by `/wayfinder`. The **map** is a single issue labelled `wayfinder:map`,
|
|
holding the Notes / Decisions-so-far / Fog body.
|
|
|
|
- **Map**: create an issue, apply the `wayfinder:map` label (create it via `POST $API/labels` `{"name":"wayfinder:map","color":"#6f42c1"}` if missing).
|
|
- **Child ticket**: an issue carrying `Part of #<map>` at the top of its body, plus a `wayfinder:<type>` label (`research`/`prototype`/`grilling`/`task`).
|
|
- **Blocking**: the `Blocked by:` body line (see Conventions).
|
|
- **Frontier**: list open issues (`?state=open`), drop any with an open `Blocked by` target or an assignee; lowest `number` wins.
|
|
- **Claim**: `POST $API/issues/<n>/assignees` with `{"assignees":["dank"]}` — actually assign it or it stays in the frontier; the session's first write.
|
|
- **Resolve**: post the answer as a comment, `PATCH` to `closed`, then update the map issue's body (GET → edit Decisions-so-far → PATCH) with a context pointer.
|
|
|
|
## Related
|
|
|
|
- [[Triage Labels]] — the role strings these operations apply.
|
|
- [[Domain Docs]] — what a skill must read before touching the codebase.
|
|
- [[SSH and Remote Access]] — reaching the host when an issue needs live evidence.
|