@verevoir/aigency-work 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,143 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.4.0] - 2026-11-18
9
+
10
+ ### Added
11
+
12
+ - Notion: `createNotionPageReader` (with `NotionPageReader`,
13
+ `NotionPageReaderConfig` and `NotionPageReadResult`) reads an ordinary
14
+ Notion page, not only a database row; `GetResult`'s `absent` gains an
15
+ optional `reason`, and `ListResult`'s `unreachable` an optional
16
+ `notFound`, so a not-found cause is named; `AnnotatePatch` accepts number
17
+ values, which Notion writes as numbers and flat-string boards store as
18
+ `String(n)`, refusing `NaN` and `Infinity` (#38).
19
+
20
+ ### Changed
21
+
22
+ - CI: the review job is granted `checks: read`, which the governance
23
+ review workflow needs (#35).
24
+ - CI: the governance review workflow is pinned by commit sha instead of
25
+ `@main` (#37).
26
+ - CI: the reviewer is repinned to governance 8f7df77, `@verevoir/review`
27
+ 0.3.5 (#39).
28
+ - BACKLOG.md only: cards for consolidating `@verevoir/workflows` into this
29
+ library and for Jira Cloud and Data Center; no code change (#40).
30
+
31
+ ## [0.3.0] - 2026-11-05
32
+
33
+ 0.2.2 was never published to npm (the latest published version is 0.2.1), so
34
+ 0.3.0 is the first release to carry the 0.2.2 changes below.
35
+
36
+ ### Added
37
+
38
+ - `Card` gains optional fields (`src/card.ts`): `title` (string), `body`
39
+ (Markdown string), `requires` (array of prerequisite card ids in the
40
+ board's own id space), `parent` (a card id) and `status`. `parseCard`
41
+ validates each when present and refuses a wrong type by name.
42
+ - A normalized `Status` vocabulary (`backlog`, `ready`, `in-progress`,
43
+ `in-review`, `blocked`, `done`, `retracted`) with `StatusMap` and the
44
+ `normalizeStatus` / `nativeStateFor` helpers, exported from the package
45
+ entry. A board derives `Card.status` from its native `state` through a map
46
+ it owns; `state` stays the native name and `status` is never stored. A
47
+ state with no mapping leaves `status` absent. The in-memory board accepts
48
+ an optional status map.
49
+ - The BACKLOG.md board (`createBacklogBoard`, `BACKLOG_STATUS_MAP`,
50
+ `BacklogBoardOptions`): a `CardSource`/`CardSink` over a BACKLOG.md-style
51
+ markdown file, with all IO injected as `read`/`write`.
52
+ - Reads: the marker (` `, `~`, `x`, `!`, `R`) is the `state`; entries
53
+ map to `title`, `body`, `requires` (the `requires:` line plus any id
54
+ after "Blocked on" in the entry's text), `parent`, and a `retracted`
55
+ property for `[R]` entries. `list()` also reports `danglingIds`: ids
56
+ that are required but match no card (an `archived` option supplies ids
57
+ kept elsewhere).
58
+ - Nothing is dropped silently: an unknown marker, missing id, blank
59
+ title, malformed `requires:`/`parent:`/`retracted:` line, an `[R]` with
60
+ no reason, a duplicated id, or an indented line attached to no card is
61
+ reported in `unparseable`.
62
+ - Writes: `writeState` changes only the marker character, and refuses a
63
+ move into or out of `R`. `expectedRevision` is `unsupported`;
64
+ `createCard` and `annotate` are `unsupported` for now.
65
+ - The Notion board now carries the new `Card` fields: `title`, `body`,
66
+ `requires`, `parent` and a normalized `status` (`NOTION_DEFAULT_STATUS_MAP`
67
+ is exported).
68
+ - `get` renders the page's blocks to Markdown as `body` (paragraphs,
69
+ headings, lists, to-dos, quotes, code, dividers, nested children to a
70
+ depth limit). Blocks it cannot render, or children cut off at the depth
71
+ limit, are counted in `unknownFields.body`; a failed or malformed
72
+ block fetch fails the `get` rather than returning a shorter body.
73
+ `list` does not fetch bodies.
74
+ - Properties Notion truncates at 25 items (relation, title, rich text,
75
+ people) are paged in full; one that cannot be paged is named in
76
+ `unknownFields.propertiesIncomplete`.
77
+ - A configured title, requires or parent property that is missing from a
78
+ page, or of the wrong type, makes the page `unparseable`.
79
+ - A `unique_id` property is flattened into a string property
80
+ (`PREFIX-N`, or just the number when there is no prefix).
81
+ - The Trello board (`createTrelloBoard`, `TrelloBoard`, `TrelloBoardConfig`
82
+ and the `TrelloFetch*` types): a `CardSource`/`CardSink` over one Trello
83
+ board through Trello's REST API with raw `fetch` and no new dependency.
84
+ - A Trello list name is the card's `state`; `statusMap` optionally maps
85
+ list names to `status`, and `writeState` also accepts a normalized
86
+ status and resolves it back to a list name. A card in a list not on the
87
+ board is `unparseable`.
88
+ - Credentials come only from the injected `getAuth`, are asked for on
89
+ every call, and never appear in any outcome or reason.
90
+ - Trello is flat, so `requires` and `parent` are not set (each card
91
+ names them in `unknownFields.unsupported`). `createCard` and `annotate`
92
+ are `refused`, and `expectedRevision` is `unsupported`.
93
+
94
+ ## [0.2.2] - 2026-11-01
95
+
96
+ Not published to npm; first released in 0.3.0.
97
+
98
+ ### Fixed
99
+
100
+ - `asfBoard`'s raw-task to `Card` mapping no longer drops or misroutes
101
+ custom properties. Before 0.2.2, a task whose `ticket` or `builtBy` was
102
+ not a string, or whose `requires` was neither a string nor an array of
103
+ strings (for example a number), failed validation: it was reported
104
+ under `unparseable` with the failing field named, and left out of
105
+ `cards`, never silently dropped. A task that did validate had only its
106
+ string-valued properties copied into `Card.properties`; every
107
+ non-string value, including an array-valued `requires`, numbers,
108
+ booleans and objects, went to `Card.unknownFields` instead. From 0.2.2,
109
+ JSON-safe values are carried in `Card.properties` as they are.
110
+ - Exercised explicitly: a task whose `properties` field itself is not a
111
+ plain object is reported as `unparseable` by both `list()` and
112
+ `get()`, never silently dropped and never reported `absent`/missing —
113
+ this was already this file's behaviour for other schema violations,
114
+ now also proven for the properties shape itself.
115
+ - `asfBoard.createCard`'s write-path property reads now share one rule:
116
+ write paths refuse a present-but-wrong-type property by name instead
117
+ of replacing or forwarding it. In 0.2.1, `createCard` forwarded only
118
+ string-valued properties: non-string values never reached the write.
119
+ An absent or non-string `title` or `ticket` fell back to `card.id`;
120
+ a non-string `subtype` was written as `'task'`, and a non-string
121
+ `body` was omitted. Now that `Card.properties` carries JSON-safe
122
+ values (this release), `createCard` checks `title`, `ticket`,
123
+ `subtype` and `body` through one helper: a value that is present but
124
+ not a string is refused by name and nothing is sent; an absent value
125
+ keeps the previous fallback.
126
+
127
+ ### Changed
128
+
129
+ - `Card.properties` (`src/card.ts`) is now typed
130
+ `Readonly<Record<string, PropertyValue>>` — `PropertyValue` being any
131
+ JSON-safe value (string, number, boolean, `null`, or an array/object
132
+ of those) — widened from `Readonly<Record<string, string>>`. This is
133
+ additive for every existing producer: a flat string record is still a
134
+ valid `PropertyValue` record. `parseCard`'s own validation, and so
135
+ every payload-sourced board (the in-memory/store/payload fixtures), is
136
+ UNCHANGED — it still only accepts a flat string-to-string bag on the
137
+ way in from an untrusted payload; only a board that builds a `Card`
138
+ directly from its own already-typed read (`asfBoard`) populates this
139
+ field with anything wider.
140
+ - `NotionBoard.createCard` now explicitly refuses, by name, a
141
+ `card.properties` entry whose value is not a string, since Notion's
142
+ own write mapping can only ever write a flat string regardless of
143
+ what `Card.properties` is now typed to allow.
144
+
8
145
  ## [0.2.1] - 2026-10-31
9
146
 
10
147
  ### Fixed
package/README.md CHANGED
@@ -13,6 +13,65 @@ Design lives in the meta repo, `verevoir/aigency-rebuild` — `design/architectu
13
13
  for why this boundary is here, `recon/constraints.md` for the defects it must
14
14
  not reproduce.
15
15
 
16
+ ## Reading ordinary Notion pages
17
+
18
+ `createNotionBoard(...).get(id)` only reads rows of the configured database: it needs the
19
+ status property. A backlog row's design page, or a row of another database (an ADRs
20
+ relation), has none, so use the page reader:
21
+
22
+ ```ts
23
+ import { createNotionPageReader } from '@verevoir/aigency-work';
24
+
25
+ const reader = createNotionPageReader({ getToken: async () => token });
26
+ const page = await reader.readPage(pageId);
27
+ if (page.ok) {
28
+ page.title; // the title property, whatever it is named
29
+ page.markdown; // content blocks as markdown (same renderer as get()); '' means no RENDERABLE content
30
+ page.truncated; // true if nested blocks below the depth limit were not fetched
31
+ page.skippedBlocks; // blocks that could not be rendered, counted not dropped
32
+ page.lastEditedTime;
33
+ } else {
34
+ page.kind; // 'not-found' | 'unreachable' | 'unparseable'
35
+ page.reason;
36
+ }
37
+ ```
38
+
39
+ It shares the board's request, retry and `sleep`/`fetch`/`maxAttempts`/`baseDelayMs` knobs and
40
+ API version (2022-06-28), so a 409/429 is retried with the same backoff. A failure is always
41
+ named, never an empty body. `markdown: ''` with `skippedBlocks: 0` is a page with no content;
42
+ `markdown: ''` with `skippedBlocks: N` is a page whose N blocks were all unrenderable.
43
+
44
+ A not-found answer on a read path (`not-found` here, `absent` with a `reason` from `get`,
45
+ `unreachable` from `list`, with `notFound: true` so it is distinguishable from an outage;
46
+ a non-404 `list` failure never sets `notFound`) usually means the
47
+ integration behind the token is not connected to that page or database (Notion: ••• →
48
+ Connections). The page paths (`get`, `readPage`) name the page id and give only that hint.
49
+ `list`, which is keyed by a database id, also warns that a data-source (collection) id is not a
50
+ database id under 2022-06-28 and is reported as not found. The write paths (`writeState`,
51
+ `annotate`, `createCard`) do not carry this hint: they report their own named `refused` reason.
52
+
53
+ ## Annotating Notion properties
54
+
55
+ `board.annotate(id, { properties })` patches properties other than the state. The Notion
56
+ board writes three property types and refuses the rest by name:
57
+
58
+ - `rich_text` and `url`: a string (`''` clears).
59
+ - `number`: a finite number, or a string that is wholly a finite decimal (`"12"`, `"-3.5"`,
60
+ `"0.0123"`, `"1e3"`). `NaN`, `Infinity`, `"12abc"`, `""`, blank and hex strings are
61
+ refused, naming the property and why. A bad value is never written as `0`. Clearing a
62
+ number with `null` is not supported.
63
+
64
+ The shared `AnnotatePatch` is `{ properties: Record<string, string | number> }`. Boards that
65
+ store flat string properties (in-memory, payload, store, ASF) store a number as `String(n)`
66
+ (a `NaN` or `Infinity` is refused by name on every board, never stored as `"NaN"`); Trello cannot annotate and refuses as before. Widening `properties` from string to
67
+ `string | number` means an out-of-tree `CardSink.annotate` implementation can now receive a
68
+ number and must handle it. The Notion board writes a real number to a `number` property.
69
+ A number given to any other Notion property type is refused, not stringified. A non-string given to a `rich_text` or
70
+ `url` property is refused as "needs a string value".
71
+
72
+ `createCard` uses the same write rules for `card.properties` (a number or a strict decimal
73
+ string for a `number` property); one bad value refuses the whole create and nothing is posted.
74
+
16
75
  ## Verify
17
76
 
18
77
  ```
package/dist/asf-board.js CHANGED
@@ -60,9 +60,11 @@
60
60
  // instead of it. `get()` by native id is unaffected either way: each task
61
61
  // is still found by its own unambiguous id.
62
62
  //
63
- // READ LOGIC (the one GET per read, the properties/column mapping,
64
- // non-string properties landing in `unknownFields`) maps the API's task
65
- // shape to this boundary's `CardSource`/`CardSink` shape. `Card.state` is
63
+ // READ LOGIC (the one GET per read, the properties/column mapping, every
64
+ // JSON-safe property value -- strings, numbers, booleans, null, arrays,
65
+ // nested objects -- carried through `Card.properties` verbatim, NEVER
66
+ // demoted to `unknownFields` for not being a plain string) maps the API's
67
+ // task shape to this boundary's `CardSource`/`CardSink` shape. `Card.state` is
66
68
  // deliberately the RAW column the API returns, never mapped onto a closed
67
69
  // status union: board.ts's own `State` doc is explicit it "must not become
68
70
  // a union" -- there is no tracker-independent taxonomy this boundary owns.
@@ -85,15 +87,28 @@
85
87
  // with no `If-Match` at all, which would silently overwrite the resource's
86
88
  // real properties with whatever this file guessed.
87
89
  import { z } from 'zod';
88
- const PropertiesSchema = z
89
- .object({
90
- ticket: z.string().optional(),
91
- builtBy: z.string().optional(),
92
- requires: z.union([z.string(), z.array(z.string())]).optional(),
93
- })
94
- .passthrough()
95
- .optional()
96
- .default({});
90
+ import { nonFiniteNumberReason, stringifyPatchProperties } from './board.js';
91
+ // Before 0.2.2, a task whose `ticket` or `builtBy` was not a string, or
92
+ // whose `requires` was neither a string nor an array of strings (for
93
+ // example a number), failed validation: it was reported under
94
+ // `unparseable` with the failing field named, and left out of `cards`,
95
+ // never silently dropped. A task that did validate had only its
96
+ // string-valued properties copied into `Card.properties`; every
97
+ // non-string value, including an array-valued `requires`, numbers,
98
+ // booleans and objects, went to `Card.unknownFields` instead. From
99
+ // 0.2.2, JSON-safe values are carried in `Card.properties` as they are.
100
+ //
101
+ // Now every key's value is carried through verbatim into
102
+ // `Card.properties`, whatever its JSON shape -- a string, number,
103
+ // boolean, null, array or nested object -- never narrowed per key and
104
+ // never split off into `unknownFields` by type. ASF's own task API
105
+ // already hands back JSON, so every value already IS JSON-safe. Callers
106
+ // that need a specific key as a string (`ticketOf`, `cardFrom`'s
107
+ // ticket/title overrides) check that for themselves at the point of use,
108
+ // exactly as they did before; this schema's only remaining job is
109
+ // confirming `properties` itself is a plain object when present, not any
110
+ // one key's shape within it.
111
+ const PropertiesSchema = z.object({}).passthrough().optional().default({});
97
112
  // No refine requiring a non-empty ticket-or-id: `id` alone is this file's
98
113
  // identity now (see the file header), so it is the only field that must be
99
114
  // non-empty.
@@ -131,25 +146,17 @@ function ticketOf(task) {
131
146
  const ticket = task.properties.ticket;
132
147
  return typeof ticket === 'string' && ticket.trim() !== '' ? ticket : undefined;
133
148
  }
134
- /** Splits a raw properties bag into the flat string record `Card.properties`
135
- * can carry, and everything else -- arrays, numbers, nested objects -- which
136
- * goes to `Card.unknownFields` instead of being silently dropped or coerced. */
137
- function splitProperties(properties) {
138
- const stringProps = {};
139
- const nonStringProps = {};
140
- for (const [key, value] of Object.entries(properties)) {
141
- if (typeof value === 'string') {
142
- stringProps[key] = value;
143
- }
144
- else {
145
- nonStringProps[key] = value;
146
- }
147
- }
148
- return { stringProps, nonStringProps };
149
- }
150
149
  function cardFrom(task, spaceId, baseUrl) {
151
- const { stringProps, nonStringProps } = splitProperties(task.properties);
152
- const properties = { ...stringProps };
150
+ // Every value ASF's task API handed back for `properties` is already
151
+ // JSON-safe by construction (it arrived as JSON) -- carried through
152
+ // verbatim into `Card.properties` rather than split off into
153
+ // `unknownFields` for not being a plain string. See the file header's
154
+ // note on non-string custom properties, and `Card.properties`'s own
155
+ // doc in card.ts for why this boundary is allowed to populate it with
156
+ // more than flat strings.
157
+ const properties = {
158
+ ...task.properties,
159
+ };
153
160
  // A real `properties.title` string ASF already set is never overwritten
154
161
  // by the top-level `title` field below -- silently replacing one
155
162
  // property's value with an unrelated field of the same name would be
@@ -187,7 +194,7 @@ function cardFrom(task, spaceId, baseUrl) {
187
194
  reference: `${baseUrl}/api/spaces/${encodeURIComponent(spaceId)}/tasks/${encodeURIComponent(task.id)}`,
188
195
  source: `asf:${spaceId}`,
189
196
  properties,
190
- unknownFields: { ...nonStringProps, ...extraTop },
197
+ unknownFields: extraTop,
191
198
  ...(typeof task.revision === 'string' ? { revision: task.revision } : {}),
192
199
  };
193
200
  }
@@ -349,6 +356,33 @@ function looseRunIdOf(body) {
349
356
  return undefined;
350
357
  return typeof body.id === 'string' && body.id.trim() !== '' ? body.id : undefined;
351
358
  }
359
+ /**
360
+ * Reads `bag[key]` as an optional string, for the one rule every
361
+ * write-path property read in this file now follows: PRESENT but not a
362
+ * string is `wrongType` -- a case for the caller to refuse by name, never
363
+ * to silently substitute a fallback for it. `bag` is deliberately typed
364
+ * as any string-keyed record, not specifically `card.properties` --
365
+ * `createCard` calls this against both `card.properties` (`title`,
366
+ * `ticket`) and `card.unknownFields` (`subtype`, `body`), the two bags
367
+ * this file reads a typed value with a fallback out of.
368
+ *
369
+ * In 0.2.1, `createCard` forwarded only string-valued properties:
370
+ * non-string values never reached the write. An absent or non-string
371
+ * `title` or `ticket` fell back to `card.id`; a non-string `subtype` was
372
+ * written as `'task'`, and a non-string `body` was omitted. Now that
373
+ * `Card.properties` carries JSON-safe values (this release), `createCard`
374
+ * checks `title`, `ticket`, `subtype` and `body` through this helper: a
375
+ * value that is present but not a string is refused by name and nothing
376
+ * is sent; an absent value keeps the previous fallback.
377
+ */
378
+ function readOptionalString(bag, key) {
379
+ const value = bag[key];
380
+ if (value === undefined)
381
+ return { kind: 'absent' };
382
+ if (typeof value !== 'string')
383
+ return { kind: 'wrongType' };
384
+ return { kind: 'value', value };
385
+ }
352
386
  export function asfBoard(options) {
353
387
  const fetchFn = options.fetchImpl;
354
388
  async function authorizedFetch(url, init) {
@@ -485,19 +519,59 @@ export function asfBoard(options) {
485
519
  return { outcome: 'applied' };
486
520
  }
487
521
  async function createCard(card) {
488
- const { stringProps } = splitProperties(card.properties ?? {});
489
- const subtype = typeof card.unknownFields.subtype === 'string'
490
- ? card.unknownFields.subtype
491
- : 'task';
492
- const title = stringProps.title ?? card.id;
493
- const bodyField = typeof card.unknownFields.body === 'string' ? card.unknownFields.body : undefined;
494
- const key = stringProps.ticket ?? card.id;
522
+ // Sent through verbatim, whatever JSON shape each value is -- same
523
+ // discipline as the read side's `cardFrom` (see its own comment):
524
+ // this boundary no longer splits `card.properties` into a
525
+ // string-only subset before sending it to ASF.
526
+ const propertiesToSend = { ...(card.properties ?? {}) };
527
+ // `title` and `ticket` are both read as typed values below, via the
528
+ // shared `readOptionalString` -- see its own doc for the one rule every
529
+ // write-path property read here follows: PRESENT but not a string is a
530
+ // named refusal, with NOTHING sent; ABSENT is the only case where the
531
+ // `card.id` fallback below applies.
532
+ //
533
+ // In 0.2.1, createCard forwarded only string-valued properties:
534
+ // non-string values never reached the write. An absent or non-string
535
+ // `title` or `ticket` fell back to `card.id`; a non-string `subtype`
536
+ // was written as `'task'`, and a non-string `body` was omitted. Now
537
+ // that `Card.properties` carries JSON-safe values (this release),
538
+ // createCard checks `title`, `ticket`, `subtype` and `body` through
539
+ // one helper: a value that is present but not a string is refused by
540
+ // name and nothing is sent; an absent value keeps the previous
541
+ // fallback.
542
+ const titleRead = readOptionalString(propertiesToSend, 'title');
543
+ if (titleRead.kind === 'wrongType') {
544
+ return { outcome: 'refused', reason: 'title must be a string' };
545
+ }
546
+ const ticketRead = readOptionalString(propertiesToSend, 'ticket');
547
+ if (ticketRead.kind === 'wrongType') {
548
+ return { outcome: 'refused', reason: 'ticket must be a string' };
549
+ }
550
+ // `subtype` and `body` live in `card.unknownFields`, not `properties`,
551
+ // but the same rule applies: PRESENT but not a string is a named
552
+ // refusal, never a silent substitute. A present-but-wrong-type
553
+ // `subtype` used to be silently written as the literal `'task'`; a
554
+ // present-but-wrong-type `body` used to be silently DROPPED from the
555
+ // request entirely -- both are exactly the "fallback stands in while
556
+ // the bad value either rides along or vanishes" trap `readOptionalString`
557
+ // exists to close, so they go through the same helper.
558
+ const subtypeRead = readOptionalString(card.unknownFields, 'subtype');
559
+ if (subtypeRead.kind === 'wrongType') {
560
+ return { outcome: 'refused', reason: 'subtype must be a string' };
561
+ }
562
+ const bodyRead = readOptionalString(card.unknownFields, 'body');
563
+ if (bodyRead.kind === 'wrongType') {
564
+ return { outcome: 'refused', reason: 'body must be a string' };
565
+ }
566
+ const subtype = subtypeRead.kind === 'value' ? subtypeRead.value : 'task';
567
+ const title = titleRead.kind === 'value' ? titleRead.value : card.id;
568
+ const bodyField = bodyRead.kind === 'value' ? bodyRead.value : undefined;
569
+ const key = ticketRead.kind === 'value' ? ticketRead.value : card.id;
495
570
  // `title` is sent as its own top-level field above; `cardFrom` copies a
496
571
  // read task's `title` into `Card.properties.title` purely as a read-side
497
572
  // convenience (see cardFrom), so strip it back out here -- otherwise a
498
573
  // round-tripped card writes the same title into ASF's properties bag a
499
574
  // second time, alongside the dedicated `title` field.
500
- const propertiesToSend = { ...stringProps };
501
575
  delete propertiesToSend.title;
502
576
  const fields = {
503
577
  subtype,
@@ -579,12 +653,16 @@ export function asfBoard(options) {
579
653
  currentRevision,
580
654
  };
581
655
  }
656
+ const nonFinite = nonFiniteNumberReason(patch.properties);
657
+ if (nonFinite !== undefined) {
658
+ return { outcome: 'refused', reason: nonFinite };
659
+ }
582
660
  // Merges into the RAW properties object -- every non-string property
583
661
  // ASF returned survives untouched unless `patch` itself replaces that
584
662
  // key. See the file header's "annotate's READ-MERGE-WRITE".
585
663
  const mergedProperties = {
586
664
  ...currentProperties,
587
- ...patch.properties,
665
+ ...stringifyPatchProperties(patch.properties),
588
666
  };
589
667
  const putResult = await authorizedFetch(resourceUrl, {
590
668
  method: 'PUT',
@@ -0,0 +1,21 @@
1
+ import type { StatusMap } from './status.js';
2
+ import type { CardSink, CardSource } from './board.js';
3
+ /**
4
+ * Native marker character to normalized status. '~' is `in-progress`
5
+ * because the reference reads it as `assigned`; it is also written for
6
+ * planning and in-review work, which one marker cannot tell apart.
7
+ */
8
+ export declare const BACKLOG_STATUS_MAP: StatusMap;
9
+ export interface BacklogBoardOptions {
10
+ readonly read: () => Promise<string>;
11
+ readonly write: (text: string) => Promise<void>;
12
+ readonly statusMap?: StatusMap;
13
+ /**
14
+ * Cards kept elsewhere (an archive file). Their ids resolve references that
15
+ * would otherwise be reported as dangling. Not listed, not writable.
16
+ */
17
+ readonly archived?: readonly {
18
+ readonly id: string;
19
+ }[];
20
+ }
21
+ export declare function createBacklogBoard(options: BacklogBoardOptions): CardSource & CardSink;