scratchboard

name	scratchboard
description	Repairs a scratchboard kanban board that reads a repo's markdown tickets wrong, and names the field an agent writes to move a card. Use when tickets are missing from the board, when the board shows them in the wrong lanes or in Unmapped, when scratchboard reports it cannot read a ticket format, or when writing a ticket's status field to move it to another lane.
license	MIT
metadata	{"version":"0.1.0"}

Detection finds the tickets, picks a preset, and proposes lanes and facets on its own, so the three jobs below are the parts that take judgement or code.

You write two files, scratchboard.json and scratchboard.parser.mjs, both at the repo root, and you ask the user before each. None of the three jobs changes a ticket.

Moving a card is the other job and it needs no config. A lane that matches on a field is moved by writing that field in the ticket, one line, in the vocabulary the repo already uses. The board never writes it, because the board is read-only.

The vocabulary a card is moved with

Read the repo's own values first, from its lanes in scratchboard.json and from the tickets themselves, and write what is already there. The list below is the vocabulary the skills speak in, which is what a repo that has none of its own should use.

Value	Means
needs-triage	A maintainer needs to evaluate this ticket
needs-info	Waiting on the reporter for information
ready-for-agent	Fully specified, ready for an agent working alone
ready-for-human	Needs a human to implement it
wontfix	Will not be actioned
done	Shipped and verifiable in the history

The first five are the canonical triage roles. done is scratchboard's own terminal state, because the five are a triage queue rather than a lifecycle. A repo may carry values outside both sets, as this one carries deferred for work someone looked at and chose later. Those pass through untouched, take their lane from local config, and are never rewritten into a value from the table.

The reader spec is docs/local-markdown-spec.md in the scratchboard repository. It names every value the board recognizes, the file shapes it reads, and what happens to input it does not recognize. Read it rather than guessing, and do not restate it in a repo's own docs.

1. Locate the tickets

Ask the user where their tickets live and take the glob from their answer. A repo can hold .scratch/, docs/issues/, and tasks/ at once, and detection takes the first one it finds.

Done when the user has confirmed a glob, listing it returns the files they call tickets, and you have read one of them.

2. Review detection

init writes scratchboard.json with no prompt in an agent run, so ask first, then read back what it produced:

npx scratchboard init --tickets '<glob>'
npx scratchboard --scan

counts.byLane and warnings in the scan payload are the report: a lane far short of the count the user expects, and a warning naming the values that matched nothing.

Tickets in the trailing Unmapped lane are drift: the config and the tickets disagree, and the tickets win. Correct the lanes against these rules.

• A lane matches on path or on field, never both. field takes in (any of) or equals.
• Matching is exact and case-sensitive. A field holding a list matches when any element matches.
• Lanes are tried in order and the first match wins. That order is also the order on screen.
• "collapsed": true renders a lane as a narrow rail, which is what a Done lane wants.
• A field used for lane matching drops out of the facet chips. Path lanes are what keeps folder and status as two separate filters.

init fills only the keys the config is missing, so a second run leaves your lanes alone. Edit scratchboard.json directly to change them.

Done when a fresh scan shows no Unmapped entry in counts.byLane and no warning about tickets matching no lane, or the user has named each value that is left there as one to leave out.

3. Write a parser when no preset matched

The trigger is a run that stops with ✗ Could not read ticket metadata. No preset read the format, so the board has nothing to render until you supply a reader.

Read three tickets from different corners of the set, so the parser covers the variation the set holds. Then write scratchboard.parser.mjs at the repo root. The block below is the contract it has to satisfy rather than code to copy: you supply the four values, and how you read them out of the file is yours.

export function parse(path, text) {
  return { id, title, body, fields };
}

• id is a string or null.
• title is a non-blank string. Fall back to the first heading, then to the file name.
• body is the markdown with the metadata block removed, because the board renders it.
• fields is a flat object of strings and string arrays. Lanes and facets address it by name, so keep the user's own field names.

Add "parser": "./scratchboard.parser.mjs" to scratchboard.json, beside the tickets and lanes keys. Those three are what lets a run skip detection, because parser covers the reading job on its own and format is optional once it is set. A named parser replaces the preset outright. A parser that fails to load stops the run with the reason and writes no board, which keeps a preset from misreading every ticket in silence.

Done when a scan reports format as parser: followed by your parser path, counts.total equal to the number of files the glob matches, warnings empty, and a non-blank title on every ticket.

For a working session, hand the user npx scratchboard --serve.