t3 checkpoint ref=refs/t3/checkpoints/ZWM2OGU3MTQtNGQ5OS00MDZjLTg3NDgtNGMyOTAzOTJlODZi/turn/23

docs/agents/domain.md

@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo:
+
+```text
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept—in an issue title, refactor proposal, hypothesis, or test name—use the term as defined in `CONTEXT.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, or there's a real gap to note for `/domain-modeling`.
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders)—but worth reopening because…_

docs/agents/issue-tracker.md

@@ -0,0 +1,50 @@
+# Issue tracker: Forgejo
+
+Issues and PRDs for this repository live as Forgejo issues at
+`git.s1q.dev/phg/fuse-mail-dir-by-tag`.
+
+Use this base command for all operations:
+
+`fgj --hostname git.s1q.dev issue <command> -R phg/fuse-mail-dir-by-tag`
+
+## Conventions
+
+- **Create an issue**:
+  `fgj --hostname git.s1q.dev issue create -R phg/fuse-mail-dir-by-tag --title "..." --body "..."`
+- **Read an issue**:
+  `fgj --hostname git.s1q.dev issue view <number> -R phg/fuse-mail-dir-by-tag`
+- **Read an issue as JSON**:
+  `fgj --hostname git.s1q.dev issue view <number> -R phg/fuse-mail-dir-by-tag --json`
+- **List issues**:
+  `fgj --hostname git.s1q.dev issue list -R phg/fuse-mail-dir-by-tag --state open`
+- **List issues as JSON**:
+  `fgj --hostname git.s1q.dev issue list -R phg/fuse-mail-dir-by-tag --state open --json`
+- **Comment on an issue**:
+  `fgj --hostname git.s1q.dev issue comment <number> -R phg/fuse-mail-dir-by-tag --body "..."`
+- **Apply a label**:
+  `fgj --hostname git.s1q.dev issue edit <number> -R phg/fuse-mail-dir-by-tag --add-label "..."`
+- **Remove a label**:
+  `fgj --hostname git.s1q.dev issue edit <number> -R phg/fuse-mail-dir-by-tag --remove-label "..."`
+- **Close an issue with a comment**:
+  `fgj --hostname git.s1q.dev issue close <number> -R phg/fuse-mail-dir-by-tag --comment "..."`
+
+Pull requests are not part of the triage request surface.
+
+## When a skill says “publish to the issue tracker”
+
+Create a Forgejo issue with `fgj issue create` using the hostname and repository arguments above.
+
+## When a skill says “fetch the relevant ticket”
+
+Read it with `fgj issue view <number>` using the hostname and repository arguments above.
+
+## Wayfinding operations
+
+The **map** is a single Forgejo issue with child issues represented by links in its body.
+
+- **Map**: an issue labelled `wayfinder:map`, containing the Notes, Decisions-so-far, and Fog sections.
+- **Child ticket**: an issue with `Part of #<map>` at the top of its body and a `wayfinder:<type>` label, where the type is `research`, `prototype`, `grilling`, or `task`.
+- **Blocking**: record `Blocked by: #<number>, #<number>` at the top of the child issue body. A ticket is unblocked when every referenced blocker is closed.
+- **Frontier**: inspect the map’s open child issues, discard blocked or already claimed tickets, and take the first remaining ticket in map order.
+- **Claim**: record the acting developer or agent in a comment before starting work.
+- **Resolve**: comment with the answer, close the child issue, and append a pointer to the result under the map’s Decisions-so-far section.

docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| 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 (for example, “apply the AFK-ready triage label”), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.