# Template — `FEEDBACK.md` for a Magogi project

> **What this is.** Fork-and-fill template for the `FEEDBACK.md`
> file every Magogi project ships per **DOC-01** (universal-five)
> and **DOC-13** (sibling-scoped feedback).
> **Audience.** Maintainers setting up a new sibling, a consumer
> application, or an AI agent scaffolding a fresh project.
> **Reference shapes.**
> [mgf-common's FEEDBACK.md](../../FEEDBACK.md) (cornerstone),
> [mgf-http/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-http/src/branch/main/FEEDBACK.md)
> (federation sibling with shipped papers).

---

## How to use this template

1. **Copy** the block below into your repo's root as `FEEDBACK.md`.
2. **REPLACE-ME markers** (`<PROJECT-NAME>` / `<CODEBERG-PATH>`)
   point at the project this file lives in.
3. **Initial state:** §2 has a placeholder "no papers yet" line.
   When the first paper comes in, replace the placeholder with the
   PAPER-01 entry.
4. **Paper-numbering** is local-per-repo (rule FB-01). The
   federation-wide PAPER number — if the paper was originally
   filed in mgf-common's FEEDBACK and got moved here — goes in
   the metadata table as a cross-reference row.

---

## Template — copy from below

```markdown
# FEEDBACK — <PROJECT-NAME>

> Paper-tracking file for issues, friction, and requests against
> this project. Consumer projects (and any future adopter) file
> PAPER-NN entries here.
>
> **Where to file what:**
>
> - **<PROJECT-NAME>-specific** → file HERE.
> - **Federation-wide** (cross-sibling patterns, standards
>   proposals) → file in
>   [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md).
>
> **Numbering convention:** paper numbers (`PAPER-NN`) are local
> to this repo (FB-01). When a paper cross-references a
> federation-wide paper, the federation number appears in the
> metadata table as a cross-reference row.
>
> **Discipline:** see
> [mgf-common/docs/standards/DOCUMENTATION.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/DOCUMENTATION.md)
> §FEEDBACK (rules FB-01..FB-04, DOC-13).

---

## §1 Process

1. **File freely.** Any consumer hitting friction MUST file a
   PAPER-NN under §2. Don't wait for permission; the maintainer
   triages.
2. **Status flips** through `OPEN` → `SHIPPED` / `DEFERRED` /
   `WONTFIX` / `MOVED` as the paper resolves. A `SHIPPED` row
   carries a commit-SHA reference + release-version reference.
3. **Renumbering** never happens within this repo — papers keep
   their PAPER-NN forever (FB-01).

---

## §2 Open feedback (active)

*No papers filed yet. The first paper goes here with the shape:*

```
#### `PAPER-01` — <one-line title>

| Field | Value |
|---|---|
| Status | OPEN |
| Severity | 🟢 Low / 🟡 High / 🔴 Critical |
| Submitter | <consumer-name> (commit [`<sha>`](<url>)) |
| Submitted | YYYY-MM-DD |
| Federation paper | [PAPER-NN in mgf-common](...) (if cross-referenced) |

**Concern.** ...

**Why it matters.** ...

**Concrete evidence.** ...

**Suggested shape.** ...
```

---

## §3 Reviewer's meta-feedback

(none yet — placeholder for cross-cutting observations about
the FEEDBACK process itself.)

---

## §4 How consumers submit feedback

1. **Open a Codeberg issue** at
   <https://codeberg.org/<CODEBERG-PATH>/issues> if you have a
   quick question. Maintainer triages.
2. **For a structured pain point**: file a PAPER-NN here as a PR
   that adds the entry to §2.
3. **For AI-agent-driven consumer sessions**: see your project's
   `docs/CLAUDE.md` auto-block (managed by `mgf-fed catch-up`)
   — the `feedback-discipline` section spells out where to file
   what.

---

## §5 Cross-references

- [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
  — federation-wide PAPERs.
- [mgf-common/docs/standards/DOCUMENTATION.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/DOCUMENTATION.md)
  — FEEDBACK discipline rules (FB-01..FB-04, DOC-13).
```

---

## Mandatory metadata fields (per FB-02 / FB-03)

Every paper entry MUST carry:

| Field | When | Source-of-truth |
|---|---|---|
| **Status** | always | One of: `OPEN`, `SHIPPED`, `DEFERRED`, `WONTFIX`, `MOVED` |
| **Submitter** | always | The consumer project + a commit URL to the friction-site |
| **Submitted** | always | ISO-8601 date |
| **Severity** | recommended | `🟢 Low` / `🟡 High` / `🔴 Critical` |
| **Shipped in** | on `SHIPPED` | Commit SHA + release version |
| **Decided on** | on `SHIPPED` / `DEFERRED` / `WONTFIX` | ISO-8601 date |
| **Federation paper** | when applicable | Cross-reference link to mgf-common's PAPER-NN |

---

## When a paper moves (DOC-13 cross-reference)

If a paper is filed in mgf-common's FEEDBACK.md against a
sibling's surface, the **sibling-scoped rule (DOC-13)** says it
must move. The mgf-common entry gets replaced with a
**redirect stub** (see [mgf-common/FEEDBACK.md PAPER-36 / 37 /
39..42](../../FEEDBACK.md) for live examples). The sibling
copy keeps the FULL content, renumbered local-per-repo, with
the federation number in a cross-reference row.
