Achievements and Team Challenges

Achievements and team challenges are the opt-in progress surface of Mockarty. They answer two questions: “how much have I built here” and “what have I tried for the first time” — and, for a team, “how many of us have got there”. They are a foundation: the measuring engine and its rules, not a points or ranking system.

Opt-in, always. Nothing is measured about you until you turn it on, and turning it off stops it. See Turning it on and off.

What it measures, and what it will not

Progress is read from work the platform already recorded. There is no second bookkeeping: an achievement never counts anything a run, a mock or a captured request did not already prove.

Every input an achievement may read is listed in one place, and the list is closed. Two kinds of input are refused on purpose, and the refusal names the rule:

A “learning” achievement is stricter still: it must be satisfied by something you did — a run that finished — never by how much you own. Owning a hundred mocks is accumulation; running a contract test for the first time is learning.

An achievement naming an input that does not exist is refused as well. Neither case silently awards nothing, and neither silently awards everything.

How progress is counted

Two properties protect the numbers, and both are visible from outside:

• Distinct work, not attempts. One finished run is one run, however many times the platform is asked about it. Repeatedly requesting the same thing cannot raise a number.
• Measured, or not measured — never a fabricated zero. If an input cannot be read, the surface says so rather than showing 0 of 10. A zero is a measurement, and Mockarty does not invent one.

Achievements and team challenges

An achievement is a personal record: a list of inputs, a “how much is enough” for each, and optionally a rolling window (“in the last 30 days”). It has no window of its own.

A team challenge is the same measurement with a start, an end and a lifecycle (draft, active, ended). Its score counts enrolled people only: a colleague who has not opted in is in neither the numerator nor the denominator. The score is always reported together with how many people are enrolled, so “3” cannot be misread as “everybody”.

Both kinds share one namespace-wide name space, so the same name can never mean two different goals.

A definition is permanent

An achievement or challenge cannot be edited. That is deliberate: editing one in place would retroactively change what people had already earned against it.

To change a goal, retire it and create a new one. Retiring frees the name, and awards already earned survive — they are facts about the past, and removing them would rewrite it.

Turning it on and off

Progress tracking is off until you turn it on, and it is always about you: there is no way to read or settle somebody else’s record, not even as a namespace owner.

• Opting in starts (or resumes) your own tracking. It is idempotent — asking twice changes nothing.
• Opting out stops it and hides your progress from you. Awards you already earned are kept, not deleted.
• Opting back in resumes with the work you have already done, because progress is read from the record rather than stored.

Until you opt in, reading progress answers “not enrolled” rather than a row of zeros — so “I have not opted in” and “I have opted in and nothing has happened yet” never look the same.

Using the API

All routes are namespace-scoped and require a token with access to that namespace. Replace $MOCKARTY_API_TOKEN and sandbox with your own.

See what may be measured

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/catalogue \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

The answer lists every input with allowed: true (with the class of evidence it is, how it is counted, and whether it takes a window) and every input that is refused, with the rule that refuses it. Read this before defining anything — it is the complete vocabulary.

Define an achievement

Defining what a namespace measures is an owner-level action: a member must not be able to decide what their colleagues are measured by.

curl -X POST http://localhost:5770/api/v1/namespaces/sandbox/gamification/definitions \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "first-test-plan-week",
    "title": "Ran a test plan three times this week",
    "description": "Settle three test-plan runs in the last seven days.",
    "category": "progress",
    "kind": "achievement",
    "idempotency_key": "define-first-test-plan-week",
    "terms": [
      {"source": "run.test_plan.settled", "threshold": 3, "window_days": 7}
    ]
  }'

idempotency_key makes the call safe to retry: the same key from the same person produces the same definition rather than a duplicate. A key already in use by a live definition is refused — retire the old one first.

Refusals are specific, and they are the useful part:

List and retire definitions

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/definitions \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

curl -X DELETE http://localhost:5770/api/v1/namespaces/sandbox/gamification/definitions/first-test-plan-week \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Opt in, read your progress, opt out

curl -X POST http://localhost:5770/api/v1/namespaces/sandbox/gamification/enrolment \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/progress \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

curl -X DELETE http://localhost:5770/api/v1/namespaces/sandbox/gamification/enrolment \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

progress returns whether you are enrolled, how far each achievement is, what you have earned, and the namespace’s team challenges. Each term carries its own reading and whether it is measured, so a partially readable achievement is reported honestly rather than rounded to a number.

Settle an award

curl -X POST http://localhost:5770/api/v1/namespaces/sandbox/gamification/awards/first-test-plan-week \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

There is nothing to send: the server re-reads the underlying record and decides. You cannot award yourself something you did not do.

Repeating a settlement is safe, and it is the point: the second call returns the same award, so no amount of asking changes what you have earned.

Team challenges

curl http://localhost:5770/api/v1/namespaces/sandbox/gamification/challenges \
  -H "Authorization: Bearer $MOCKARTY_API_TOKEN"

Each challenge reports earned_members (enrolled people who have earned it inside the window) together with enrolled_members (how many people are enrolled at all).

Who may do what

Defining and retiring are written to the audit trail, including which inputs the definition reads. Awards are not: they are your own record, not a change of authority over anybody else.