diff --git a/AGENTS.md b/AGENTS.md index 4561d0a..6dd291d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -803,6 +803,20 @@ dies, its page is destroyed. Rollback is a commit, not a document. `serverAppConfigs-docs/index.md` is the locator for every page that survives; retired scripts live in `old/` and `.AGENTTRASH/`. +## Agent skills + +### Issue tracker + +Issues live in Gitea (`dank/serverAppConfigs` on Dankclaw), via its REST API with the stored credential. See `serverAppConfigs-docs/Agent/Issue Tracker.md`. + +### Triage labels + +The five canonical roles keep their default strings (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `serverAppConfigs-docs/Agent/Triage Labels.md`. + +### Domain docs + +Single-context: root `GLOSSARY.md` + `docs/adr/`, created lazily; this vault stays the owner of operational facts. See `serverAppConfigs-docs/Agent/Domain Docs.md`. + ## Why Direct edits on the remote drift from version control, and future agents diff --git a/serverAppConfigs-docs/Agent/Domain Docs.md b/serverAppConfigs-docs/Agent/Domain Docs.md new file mode 100644 index 0000000..39959a5 --- /dev/null +++ b/serverAppConfigs-docs/Agent/Domain Docs.md @@ -0,0 +1,55 @@ +--- +type: reference +title: Domain Docs +description: "Consumer rules for GLOSSARY.md and docs/adr/, and where this vault out-ranks them on operational facts." +tags: [agent, glossary, adr, documentation] +timestamp: 2026-10-20T00:00:00Z +--- + +# Domain Docs + +How the engineering skills (`/grill-with-docs`, `/domain-modeling`, +`/improve-codebase-architecture`, `/to-spec`) should consume this repo's design +vocabulary when exploring the codebase. + +## Before exploring, read these + +- **`GLOSSARY.md`** at the repo root +- **`docs/adr/`**: read ADRs that touch the area you're about to work in + +If either doesn't exist, **proceed silently**. Don't flag their absence; don't +suggest creating them upfront. `/domain-modeling` (reached via +`/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily +when terms or decisions actually get resolved. As of 2026-10-20 neither exists; +this page is the pointer, not a promise. + +## Ownership against this vault + +This repo already carries `serverAppConfigs-docs/` — the operational knowledge +base and, per repo law, the owner of operational facts (endpoint shapes, Eras, +Laws, runbooks). `GLOSSARY.md` / `docs/adr/` hold **design vocabulary and +decisions**. Where a term is defined in both, the vault page that owns the fact +wins — one fact, one owner. A glossary entry restating an endpoint number is +the bug, not the second source. + +## Use the glossary's vocabulary + +When output names a domain concept (an issue title, a refactor proposal, a +hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift +to synonyms the glossary explicitly avoids. + +If the concept you need isn't in the glossary yet, that's a signal: either +you're inventing language the project doesn't use (reconsider) or there's a +real gap (note it for `/domain-modeling`). + +## Flag ADR conflicts + +If output contradicts an existing ADR, surface it explicitly rather than +silently overriding: + +> _Contradicts ADR-0007 (…), but worth reopening because…_ + +## Related + +- [[Issue Tracker]] — where specs and tickets built on this vocabulary are published. +- [[Agent Docs and Edits]] — the edit-safety rules that apply while touching any doc in this checkout. diff --git a/serverAppConfigs-docs/Agent/Issue Tracker.md b/serverAppConfigs-docs/Agent/Issue Tracker.md new file mode 100644 index 0000000..cd53cce --- /dev/null +++ b/serverAppConfigs-docs/Agent/Issue Tracker.md @@ -0,0 +1,85 @@ +--- +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//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/` (fields: `number`, `title`, `body`, `labels[].name`, `state`) +- **List issues**: `curl -s -K "$cfg" "$API/issues?state=open&limit=50"` — add `&labels=` to filter +- **Comment**: `curl -s -K "$cfg" -X POST -d "$(jq -n --rawfile b "$BODY" '{body:$b}')" $API/issues//comments` +- **Apply labels**: `POST $API/issues//labels` with `{"labels":[]}` — 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//labels/` +- **Close**: `PATCH $API/issues/` with `{"state":"closed"}` +- **Blocking relationships**: this instance has no native sub-issues or dependencies — put `Part of #` / `Blocked by: #, #` 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: · session: ` — 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/` 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 #` at the top of its body, plus a `wayfinder:` 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//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. diff --git a/serverAppConfigs-docs/Agent/Triage Labels.md b/serverAppConfigs-docs/Agent/Triage Labels.md new file mode 100644 index 0000000..9ed1732 --- /dev/null +++ b/serverAppConfigs-docs/Agent/Triage Labels.md @@ -0,0 +1,39 @@ +--- +type: reference +title: Triage Labels +description: "The five canonical triage roles mapped to this repo's Gitea label strings, plus the numeric-ID quirk." +tags: [agent, gitea, triage, labels] +timestamp: 2026-10-20T00:00:00Z +--- + +# Triage Labels + +The mattpocock-lineage skills speak in terms of five canonical triage roles. +This page maps those roles to the actual label strings used in this repo's +tracker ([[Issue Tracker]] owns the API shape). + +| Label in mattpocock/skills | Label in our tracker | Meaning | +| -------------------------- | -------------------- | ---------------------------------------- | +| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | +| `needs-info` | `needs-info` | Waiting on reporter for more information | +| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `wontfix` | `wontfix` | Will not be actioned | + +When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the +corresponding label string from this table. Edit the "Label in our tracker" +column to match whatever vocabulary you actually use. + +## Instance quirks (Dankclaw Gitea) + +- Labels are applied by **numeric ID**, never by name: `POST /issues//labels` + with `{"labels":[]}`; resolve names via `GET /labels`. +- The repo also carries the pre-existing `human-only` label from the manual era + (e.g. the podcast-destination issues). `ready-for-human` maps to itself; the + `(HUMAN ONLY)` title prefixes on existing issues stay as they are — the label + is what the skills read. +- An issue with **no** triage label is simply untriaged; absence is not a state. + +## Related + +- [[Issue Tracker]] — the auth-safe curl shape that applies these labels. diff --git a/serverAppConfigs-docs/Agent/index.md b/serverAppConfigs-docs/Agent/index.md index c2424cd..69d8515 100644 --- a/serverAppConfigs-docs/Agent/index.md +++ b/serverAppConfigs-docs/Agent/index.md @@ -6,6 +6,9 @@ docs get edited safely, and how the agent's home is deployed. - [[OMP Harness]] — The omp harness as configured here: compaction chain arithmetic, per-model sampler routing, and the context-lean audits. - [[Agent Docs and Edits]] — Two self-inflicted doc damage classes from parallel agent edits, with the audit checks and recovery order for each. - [[Command Center Dotfiles]] — How the dotfiles repo deploys: stow-equivalent packages, full-replica rsync, the pre-overwrite audit, transport gotchas. +- [[Issue Tracker]] — How agent skills read and write Gitea issues here: credential-safe curl, label IDs, and wayfinding without sub-issues. +- [[Triage Labels]] — The five canonical triage roles mapped to this repo's Gitea label strings, plus the numeric-ID quirk. +- [[Domain Docs]] — Consumer rules for GLOSSARY.md and docs/adr/, and where this vault out-ranks them on operational facts. ## Related diff --git a/serverAppConfigs-docs/index.md b/serverAppConfigs-docs/index.md index cbba6a7..1f408d2 100644 --- a/serverAppConfigs-docs/index.md +++ b/serverAppConfigs-docs/index.md @@ -130,7 +130,10 @@ is a locator: one row, one clause, no numbers. |---|---| | [[Agent Docs and Edits]] | Two self-inflicted doc damage classes from parallel agent edits, with the audit checks and recovery order for each. | | [[Command Center Dotfiles]] | How the dotfiles repo deploys: stow-equivalent packages, full-replica rsync, the pre-overwrite audit, transport gotchas. | +| [[Domain Docs]] | Consumer rules for GLOSSARY.md and docs/adr/, and where this vault out-ranks them on operational facts. | +| [[Issue Tracker]] | How agent skills read and write Gitea issues here: credential-safe curl, label IDs, and wayfinding without sub-issues. | | [[OMP Harness]] | The omp harness as configured here: compaction chain arithmetic, per-model sampler routing, and the context-lean audits. | +| [[Triage Labels]] | The five canonical triage roles mapped to this repo's Gitea label strings, plus the numeric-ID quirk. | ## Research and methodology