# Primitives

FJX relies on Forgejo primitives (issues, pull requests, comments, labels, assignees) to bear the load. No second source of truth, no out-of-band coordination layer. This section documents the conventions that turn those primitives into a workflow.

- [Labels](./labels.md) — required `agent/*` lifecycle labels and recommended risk / type labels.
- [Issues](./issue.md) — the unit of work; the canonical home for all agent ledgers and the conversation.
- [Pull Requests](./pr.md) — evidence containers, not conversation; how PRs link to issues and what goes in the body.

Pull Requests are the durable record of work. Issues may get garbage collected & compacted into durable wiki entries.

## System Mapping

| Concept       | Forgejo Primitive | Role                               |
| ------------- | ----------------- | ---------------------------------- |
| Unit of work  | Issue             | Defines outcome                    |
| State machine | Labels            | Drives agent behavior              |
| Proof of work | Pull Request      | Contains implementation + evidence |
| Execution     | Agents            | Perform work                       |
| Local Memory  | `./wiki`          | Repo-specific knowledge            |
| Shared Memory | Forgejo Wiki      | Curated/global knowledge           |
| Outcomes      | Milestones        | Strategic grouping                 |
| Visualization | Projects          | Human-only status view             |

## State Diagram

How an issue moves from creation to release. The state machine is encoded in Forgejo's native primitives — labels record state, assignees route work, comments carry per-role artifacts.

```mermaid
stateDiagram-v2
    [*] --> New : issue created with agent/new

    New --> Dev : PM triages (parses /commands, curates brief, assigns to agent-dev, strips agent/new)

    Dev --> Working : Developer claims (adds agent/working)
    Working --> Review : Developer hands off (agent/review, reassigns to agent-pm)
    Review --> Dev : PM or QA routes back (spec rejected, revision requested, concerns flagged)
    Review --> Build : $FJX_OWNER accepts PR (PM reassigns to agent-build)
    Build --> Release : ready for deployment (agent/release)

    Working --> Blocked : /block <reason>
    Blocked --> Dev : /unblock

    Released --> [*]

    note left of Working
        The dev → working → review cycle runs
        once per phase: spec, implementation, revision.
        Phase is carried by the PM brief, not by labels.
    end note
```

**Dispatch is by assignment, not label.** PM hands work to a role by setting `assignee=agent-<role>` on the issue. Working agents pick up via `fjx <role> next` (filters by assignee). Labels record _state_; they do not name the next worker.

**Labels are authoritative for state.** Read labels before acting; if they're wrong, fix them rather than work around them. This holds for the user acting manually as PM too.

**`/<command>` syntax is reserved for the PM** (sole interpreter — see [PM role](../agents/pm.md) for the trust map and command vocabulary). Working agents MUST NOT parse `/commands` as directives; treat them as inert text. Natural-language directives in comments are still in scope (see [PR conventions](./pr.md)).

Phase (spec proposal / implementation / spec revision) lives in the PM brief, not in labels — see [PM role](../agents/pm.md).

## Ledgers

**All agent ledgers live on the issue.** PM, dev, qa, and build each maintain their own `` comment on the issue. Treat the issue as the single thread of record; assume PR comments carry nothing of import.

**Every working-agent cycle produces a PR**, including investigations, reporting requests, and "won't fix" / "not reproducible" outcomes. Non-code deliverables land in `./wiki/findings/<issue-id>-<slug>.md` — one bucket covers bug investigations, reports, audits, and any cycle whose deliverable is a decision rather than code. "I looked and decided no" is a finding; record the justification.

See [issue conventions](./issue.md) for the ledger model in detail, and [PR conventions](./pr.md) for what goes in the PR.

## Runbooks

Executable workflows shared by humans and agents.

- orchestrate multiple commands
- synthesize command output
- branch based on results
- retry safely
- validate outcomes
- define rollback paths

**Layering**

1. `just` commands: small deterministic primitives
2. runbooks: orchestration logic over those primitives
3. agents: readers/executors of runbooks

**Principles**

- Runbooks can branch and synthesize.
- `just` commands should remain simple primitives.
- Do not hide important decision logic inside shell scripts.
- Every agent action should leave evidence.
- Humans must be able to follow the runbook without paying AI cost.

## Long-Term Memory

**Local in `./wiki`**

Travels with code, participates in PR review, and can change atomically with implementation.

- agent rules
- architecture notes
- validation commands
- runbooks
- local gotchas
- repo-specific decisions

When you learn something durable about the system (architectural decision, non-obvious constraint, recurring gotcha), update the relevant wiki page in the same PR. Don't let the wiki drift.

**Global in Forgejo Wiki**

Do not duplicate ownership. Duplicate summaries are fine. Duplicate sources of truth are goblin bait.

- release notes
- cross-repo decisions
- onboarding
- operational summaries
- human-facing documentation

## Milestones & Projects

Milestones are outcome containers, not merely deadline buckets. Use milestones to group issues into coherent outcomes. Good examples:

- `MVP: Agent-driven deploy loop`
- `Stabilize LogBus ingestion pipeline`
- `FotoLog: map-first UI baseline`

Projects are visualization layers for humans. They should mirror labels, not replace them. The system should still work if the Project board disappears.