0004: Configurable status lifecycle

Context#

Teams disagree on lifecycle vocabulary. One wants accepted, another approved; some track in-review, some do not. A fixed list either forces a vocabulary or leaves the status field unchecked. At the same time a few behaviours depend on the meaning of a status, not on its name: which records are still being decided, and which ones describe the system as it is today.

Decision#

Statuses are a map in inkan.config.ts. Each status has a label and two optional flags: open (still being decided) and current (describes how things are now). The site reads only these flags; it never hard-codes a status name except to pick a sticker.

The package ships nine statuses. Setting statuses in the config replaces that list, so the vocabulary is entirely yours. A record whose status is not in the map fails the build.

How to use it#

Default statuses#

What open does#

• The record is listed on /backlog/, sorted by reviewBy. Records without a date go in a “No deadline” group.
• The backlog counter in the sidebar and the overdue count in the backlog lede include it.
• The landing page’s “Review overdue” counter does not count it: that number is the overdue periodic reviews of decided records, as on /reviews/.

What current does#

• The record number in the header and on its card gets a foil finish. implemented gets gold foil, every other current status gets holographic foil. This is the visual meaning of “this is how things are”.
• The landing page’s stats count it as a decision in force, per site and per project.
• The record gets periodic reviews: it is listed on /reviews/ and reported by inkan check when reviewBy, reviewEvery or reviews.every schedules it. reviews.statuses in the config picks other statuses instead of the current ones. See Review decisions on a schedule.

A status with neither flag is terminal and quiet: it is shown with its sticker and can be filtered, nothing more.

Every status, flagged or not, appears in the status filter on /decisions/ with its count and can be linked with /decisions/?status=accepted.

Defining your own statuses#

1
import { defineConfig } from '@tilaven/inkan';
2

3
export default defineConfig({
4
  statuses: {
5
    idea: { label: 'Idea', open: true, sticker: 'draft' },
6
    proposed: { label: 'Proposed', open: true },
7
    approved: { label: 'Approved', current: true, sticker: 'accepted' },
8
    live: { label: 'Live', current: true, sticker: 'implemented' },
9
    declined: { label: 'Declined', sticker: 'rejected' },
10
    archived: { label: 'Archived', color: '#8a8f98' },
11
  },
12
});

Sticker resolution, in order: the sticker field when it names a built-in; the status key itself when it is a built-in name (so a custom map that keeps accepted keeps its sticker); otherwise a generic sticker with the first letter of the label, filled with color.

A smaller change, such as adding one status, still needs the full map:

1
statuses: {
2
  draft: { label: 'Draft', open: true },
3
  proposed: { label: 'Proposed', open: true },
4
  'in-review': { label: 'In review', open: true },
5
  accepted: { label: 'Accepted', current: true },
6
  implemented: { label: 'Implemented', current: true },
7
  rejected: { label: 'Rejected' },
8
  withdrawn: { label: 'Withdrawn' },
9
  deprecated: { label: 'Deprecated' },
10
  superseded: { label: 'Superseded' },
11
  'on-hold': { label: 'On hold', open: true, sticker: 'in-review' },
12
},

Unknown fields on a status (colour, icon) are rejected with a “did you mean” hint when a known key is close.

Changing a status#

Edit the status line of the record. For superseded, also fill supersededBy on the old record and supersedes on the new one so the lineage shows on both; see Link records by path. The timeline and backlog update on the next build.

Consequences#

• One vocabulary per site, enforced at build time. Filters and the backlog are never polluted by Accepted next to accepted.
• Behaviour follows the two flags, so renaming statuses costs nothing. A status that is both open and current is allowed but confusing; avoid it.
• Replacing rather than merging means the common case “add one status” repeats nine lines. The trade-off buys the ability to remove statuses.
• Only nine sticker shapes exist. A tenth custom status gets the letter sticker, which looks plainer than the built-ins.