@convesoft/zban 0.0.0-stage → 1.0.0-rc.1

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.
@@ -0,0 +1,415 @@
1
+ # Issues
2
+
3
+ An issue is one Markdown file with a short YAML header. This page explains the
4
+ model for users. The specification items below it are the normative contract.
5
+
6
+ ## A quick look
7
+
8
+ ```markdown
9
+ ---
10
+ title: Parse issue files
11
+ status: in-progress
12
+ type: feature
13
+ priority: high
14
+ tags:
15
+ - storage
16
+ parent: zb-9jra34
17
+ blocked_by:
18
+ - zb-naex76
19
+ created_at: 2026-11-11T20:00:00Z
20
+ ---
21
+
22
+ Load every issue in `.zban/` and `.zban/archive/`.
23
+
24
+ - [x] Read frontmatter
25
+ - [ ] Preserve unknown keys
26
+ ```
27
+
28
+ The file is `.zban/zb-n938cw.md`. Its ID, `zb-n938cw`, is the filename, so you can
29
+ open any issue from its ID: `.zban/<id>.md`, or `.zban/archive/<id>.md` once it is
30
+ closed.
31
+
32
+ You can edit issues by hand. The header may contain YAML comments, but zban drops
33
+ them whenever it rewrites the header, so keep notes in the body.
34
+
35
+ ## Types, statuses and priorities
36
+
37
+ These sets are fixed for every project ([[ADR-FIXED-VOCABULARY]]).
38
+
39
+ | Type | Use for |
40
+ | --- | --- |
41
+ | `epic` | A larger outcome that groups features, tasks and smaller epics, such as phases. Not worked on directly. |
42
+ | `feature` | A user-facing capability or enhancement |
43
+ | `bug` | Something that is broken |
44
+ | `task` | A concrete piece of work: a chore, or a step of a feature |
45
+
46
+ | Status | Meaning |
47
+ | --- | --- |
48
+ | `draft` | Captured but not refined, or parked on purpose. Neither it nor anything under it is offered as ready work. |
49
+ | `todo` | Refined and waiting to be started |
50
+ | `in-progress` | Being worked on |
51
+ | `done` | Finished. Moved to the archive. |
52
+ | `cancelled` | Will not be done (duplicate, obsolete, rejected). Moved to the archive. |
53
+
54
+ Priorities, highest first: `critical`, `high`, `normal` (the default), `low`, `deferred`.
55
+
56
+ ## Relations
57
+
58
+ - `parent`: the issue this one belongs to, usually an epic or a feature. zban
59
+ does not restrict which types can be parents.
60
+ - `blocked_by`: issues that must be closed before this one can start.
61
+ - `related`: informational links with no effect on readiness.
62
+ - `discovered_from`: the issue that was being worked on when this one was found.
63
+
64
+ Each relation is written once, on one issue. zban shows the reverse direction
65
+ (children, blocks, related, discovered) when you read the other issue.
66
+
67
+ zban refuses relations that could never resolve: a loop through `parent` and
68
+ `blocked_by`, such as an epic blocked by its own child, and an issue blocked by
69
+ one of its own ancestors.
70
+
71
+ ## Ready work
72
+
73
+ `zban list --ready` shows `todo` issues that can start now: their blockers are
74
+ closed and nothing above them in the parent chain is closed, blocked or a
75
+ `draft`. Keep planned epics, backlog and work only a human can do as `draft`,
76
+ and move them out of `draft` when their work may start. A parent's status
77
+ `in-progress` does not by itself hold its children back. Epics are never ready,
78
+ because their children carry the work. Every listing uses the same order:
79
+ priority, then age, then ID. The precise rule is [[DES-READINESS]].
80
+
81
+ Because readiness follows the whole parent chain, nested epics can split larger
82
+ work into phases. A `blocked_by` between sibling epics puts the phases in order:
83
+
84
+ ```text
85
+ zb-9jra34 epic Deliver zban v1
86
+ ├─ zb-h4p1q7 epic Phase 1: core
87
+ │ └─ tasks, ready now
88
+ └─ zb-m2x8r5 epic Phase 2: integrations (blocked_by: zb-h4p1q7)
89
+ └─ tasks, ready once Phase 1 is closed
90
+ ```
91
+
92
+ Phase 1 can close only after all its children have closed, so Phase 2's work
93
+ appears in the ready list exactly when Phase 1 is finished.
94
+
95
+ ## Closing and the archive
96
+
97
+ Setting `done` or `cancelled` moves the file to `.zban/archive/` and records
98
+ `closed_at`. Reopening moves it back. Archived issues still show up in `show`,
99
+ in searches, in relations and in `list --all`.
100
+
101
+ zban refuses to close unfinished work unless you force it:
102
+
103
+ - `done` while the body still has unchecked `- [ ]` items;
104
+ - `done` or `cancelled` while the issue has open children.
105
+
106
+ `zban create -s done` also refuses a body with unchecked items, and `create`
107
+ has no `--force`: create the issue open, then close it with
108
+ `zban update ID -s done --force`.
109
+
110
+ zban never closes children for you. Close or cancel each child with its own
111
+ summary or reason first. A forced close leaves the children open, and
112
+ `zban check` warns about them.
113
+
114
+ By convention, a finished issue gets a `## Summary of Changes` section and a
115
+ cancelled one gets `## Reasons for Cancelling`. An unfinished issue can carry a
116
+ `## Handoff` note for the next session; see [Handoffs](agents.mara.md#handoffs).
117
+
118
+ ## Simultaneous changes
119
+
120
+ If an issue file changes between zban reading it and writing it, for example
121
+ because another agent or an editor saved it, zban stops with a `conflict` error
122
+ instead of overwriting the other change. Show the issue again and retry.
123
+
124
+ zban commands that write at the same moment take turns. Each holds a short
125
+ lock on `.zban/` while it checks and replaces a file, so when two agents update
126
+ one issue together, neither change is lost: at worst one of them gets `conflict`
127
+ and retries. The lock lasts only for that step and leaves no file behind.
128
+
129
+ Commands that read issues share the lock while they list `.zban/` and read the
130
+ issue files, so they never miss an issue that another zban command is replacing,
131
+ closing or reopening at that moment. Reads do not wait for each other, only for
132
+ a write's short step.
133
+
134
+ ## Broken files
135
+
136
+ A file zban cannot read, for example one left with Git conflict markers after a
137
+ merge, does not stop work on the other issues. `list` and `show` skip it with a
138
+ warning, and changes to other issues still work. Fix the file by hand, then run
139
+ `zban check`, which lists every problem with a stable code ([[DES-CHECK]]):
140
+
141
+ ```text
142
+ $ zban check
143
+ .zban/zb-k3m9x2.md: error: invalid YAML on line 3: mapping values are not allowed in this context [unparseable]
144
+ .zban/zb-n938cw.md: warning: unknown key `assignee` [unknown_key]
145
+ ```
146
+
147
+ `zban check` exits with status 1 when it finds an error. Warnings alone, such as
148
+ an open issue under a closed parent, exit 0. `zban check --fix` moves each file
149
+ that is in the wrong directory for its status, for example after an interrupted
150
+ close, deletes the `.zban-*.tmp` files that interrupted writes left behind, and
151
+ leaves every other problem for you to fix.
152
+
153
+ ## Requirements
154
+
155
+ :::mara requirement REQ-ONE-FILE
156
+ :mid: 01M764FJ3ZF9DQZ05TX19YZKPY
157
+ :title: Store each issue as one Markdown file
158
+ :status: accepted
159
+ :satisfies: NEED-READABLE-FILES
160
+
161
+ Each issue is stored as exactly one UTF-8 Markdown file with a YAML frontmatter header under the project's `.zban/` directory. zban needs no other state, such as a database, index or cache, to operate on issues.
162
+ :::
163
+
164
+ :::mara requirement REQ-PRESERVE-CONTENT
165
+ :mid: 01M764FJ3Z0CDR7D6WGHMJYWXK
166
+ :title: Preserve content an operation does not change
167
+ :status: accepted
168
+ :satisfies: NEED-READABLE-FILES
169
+ :satisfies: NEED-INTEGRITY
170
+
171
+ When zban rewrites an issue, the body bytes stay unchanged unless the operation edits the body, and frontmatter keys zban does not know are kept. Each file write replaces the file atomically, so an interrupted write never leaves a partially written issue.
172
+ :::
173
+
174
+ :::mara requirement REQ-NO-LOST-UPDATES
175
+ :mid: 01M76XFGSJMTW8EQ1TN4W3KV1F
176
+ :title: Never overwrite a concurrent change
177
+ :status: accepted
178
+ :satisfies: NEED-INTEGRITY
179
+
180
+ When an issue file changes between zban reading it and replacing it, for example through another zban process, an editor or a branch switch, zban does not replace it and the operation fails with the error code `conflict`. Of several zban processes that change one issue at the same time, each either writes its change without dropping another's or fails with `conflict`. Creating an issue never replaces an existing file. On a file system without hard links, this holds against other zban processes, but not against another program that creates a file under the new issue's name at the same moment.
181
+ :::
182
+
183
+ :::mara requirement REQ-DAMAGED-DATA
184
+ :mid: 01M779N58NATQJ611QCSYK1PWB
185
+ :title: Keep working when some issue data is broken
186
+ :status: accepted
187
+ :satisfies: NEED-INTEGRITY
188
+ :satisfies: NEED-BRANCH-SAFE
189
+
190
+ An issue file that cannot be parsed, or invalid data already in the project, such as a reference to a missing issue after a merge, does not stop work on the other issues. Listing and showing skip unreadable files and report each one as a warning. A mutation validates only what the request changes, and fails only when it must read or write an unreadable file. An ID that names more than one file is reported as ambiguous rather than resolved by guessing. `zban check` reports every such problem.
191
+ :::
192
+
193
+ :::mara requirement REQ-MERGE-SAFE-IDS
194
+ :mid: 01M764FJ3ZQ5N4A9NJC8NNK6SA
195
+ :title: Create issue IDs without coordination
196
+ :status: accepted
197
+ :satisfies: NEED-BRANCH-SAFE
198
+
199
+ zban assigns issue IDs without consulting other branches, checkouts or services. Independently created issues practically never share an ID, a new ID never repeats one already present in the local project, and any duplicates after a merge are reported by [[REQ-CHECK]].
200
+ :::
201
+
202
+ :::mara requirement REQ-NO-GIT
203
+ :mid: 01M764FJ3ZMN288AGT0HD4V1DW
204
+ :title: Leave version control to the user
205
+ :status: accepted
206
+ :satisfies: NEED-BRANCH-SAFE
207
+
208
+ zban never runs Git or another version-control command, and it writes only inside the project's `.zban/` directory. Issue changes reach other branches only through the user's ordinary commits and merges. zban works the same in a directory that is not a Git repository.
209
+ :::
210
+
211
+ :::mara requirement REQ-FIXED-VOCABULARY
212
+ :mid: 01M764FJ3ZJGRCCPD3K9XH12B0
213
+ :title: Use a fixed status, type and priority vocabulary
214
+ :status: accepted
215
+ :satisfies: NEED-ORGANIZE
216
+
217
+ Status is one of `draft`, `todo`, `in-progress`, `done`, `cancelled`. Type is one of `epic`, `feature`, `bug`, `task`. Priority is one of `critical`, `high`, `normal`, `low`, `deferred`. zban rejects other values on write and reports them when checking. Projects cannot change these sets.
218
+ :::
219
+
220
+ :::mara requirement REQ-RELATIONS
221
+ :mid: 01M764FJ3ZZZJS6M31EWC6TJMG
222
+ :title: Relate issues to each other
223
+ :status: accepted
224
+ :satisfies: NEED-ORGANIZE
225
+
226
+ An issue can name at most one parent of any type, any number of blocking issues, any number of related issues, and at most one issue it was discovered from. zban rejects references to unknown issues, references to the issue itself, cycles through `parent` and `blocked_by` edges taken together, and a `blocked_by` that names one of the issue's own ancestors, because each of these can never resolve without forcing a close. Reading an issue shows both directions of each relation. Deleting an issue that another issue references is refused.
227
+ :::
228
+
229
+ :::mara requirement REQ-READY
230
+ :mid: 01M764FJ3ZGP807YGG3R6CBPNN
231
+ :title: Report ready work and why other work waits
232
+ :status: accepted
233
+ :satisfies: NEED-FIND-NEXT
234
+
235
+ zban lists the issues that can be started now in a deterministic priority order. For any open issue it explains why the issue is not ready, naming the responsible status, type, blocker or ancestor.
236
+ :::
237
+
238
+ :::mara requirement REQ-CLOSE-CHECKLIST
239
+ :mid: 01M764FJ3Z4DX6RS09TWKY84QC
240
+ :title: Do not close unfinished work
241
+ :status: accepted
242
+ :satisfies: NEED-TRACK-PROGRESS
243
+
244
+ Setting an issue to `done` while its body contains unchecked Markdown task items is refused unless the request explicitly forces it. Setting an issue to `done` or `cancelled` while it has open children is refused unless forced, and zban never closes the children itself. Cancelling with unchecked task items is not restricted. Listings show checklist progress as checked and total item counts.
245
+ :::
246
+
247
+ :::mara requirement REQ-AUTO-ARCHIVE
248
+ :mid: 01M764FJ3ZKD4N35SRK3JR3Y3B
249
+ :title: Archive closed issues automatically
250
+ :status: accepted
251
+ :satisfies: NEED-PROJECT-MEMORY
252
+
253
+ Closing an issue as `done` or `cancelled` moves its file to `.zban/archive/`, and reopening it moves the file back to `.zban/`. Archived issues remain available to show, search and relations, and are excluded from default listings.
254
+ :::
255
+
256
+ :::mara requirement REQ-CHECK
257
+ :mid: 01M764FJ3ZBK44WBWNMZ4ZK98W
258
+ :title: Detect and repair inconsistent issue data
259
+ :status: accepted
260
+ :satisfies: NEED-INTEGRITY
261
+ :mitigates: RISK-ID-COLLISION
262
+
263
+ `zban check` examines the whole project and reports each problem with its file and a stable code: malformed configuration, filenames that are not valid IDs, unparseable files, missing required fields, invalid values, unknown keys, duplicate IDs, references to unknown issues or to the issue itself, cycles and blockers on an ancestor as defined in [[REQ-RELATIONS]], a `related` link stored on both issues, open issues under a closed parent, files in the wrong directory for their status, and temporary files left behind by an interrupted write. Unknown keys, a `related` link stored on both issues, an open issue under a closed parent and a leftover temporary file are warnings. Every other finding is an error, and only errors make the check fail. `zban check --fix` repairs only file placement and deletes leftover temporary files. Every other finding is left for a human or agent to edit.
264
+ :::
265
+
266
+ ## Design
267
+
268
+ :::mara design DES-PROJECT-LAYOUT
269
+ :mid: 01M764FJ3ZKR92J7WBBKRNMK2B
270
+ :title: Project directory layout
271
+ :status: accepted
272
+ :satisfies: REQ-ONE-FILE
273
+ :satisfies: REQ-AUTO-ARCHIVE
274
+
275
+ ```text
276
+ .zban/
277
+ config.toml
278
+ zb-k3m9x2.md open issues
279
+ archive/
280
+ zb-7hq2pd.md closed issues
281
+ ```
282
+
283
+ `config.toml` has exactly two keys:
284
+
285
+ ```toml
286
+ format_version = 1 # format of the .zban/ directory; zban refuses formats it does not know
287
+ prefix = "zb" # ID prefix: 1-8 lowercase ASCII letters or digits, starting with a letter
288
+ ```
289
+
290
+ Unknown configuration keys are errors. `zban init` creates the directory and the configuration. When a step after creating the directory fails, such as writing the configuration, `init` removes the directory again if it is still empty, so that `init` can be run again; a `.zban/` that already existed fails with `project_exists` and is left alone. The prefix is `zb` unless `--prefix` gives another one; a value that breaks the prefix rule above is rejected. zban finds the project by walking up from the working directory to the nearest `.zban/config.toml`, as far as the filesystem root. The global `-C, --directory DIR` option makes zban behave as if started in `DIR`: the search starts there, and `init` creates `.zban/` there.
291
+
292
+ `init` works inside an existing project too and creates a nested project there. Commands run at or below the nested root then find the nested project and no longer see the enclosing one, so `init` names the enclosing project: the nearest directory above the new root that holds `.zban/config.toml` ([[DES-CLI]]).
293
+
294
+ Every `*.md` file directly inside `.zban/` or `.zban/archive/` is an issue. Other files and subdirectories are ignored, except that `zban check` reports the temporary files of interrupted writes ([[DES-CHECK]]). Open issues (`draft`, `todo`, `in-progress`) belong in `.zban/`, and closed issues (`done`, `cancelled`) belong in `.zban/archive/`.
295
+ :::
296
+
297
+ :::mara design DES-ISSUE-ID
298
+ :mid: 01M764FJ3ZP2NBQPN65QHVH1XY
299
+ :title: Issue identifiers and filenames
300
+ :status: accepted
301
+ :satisfies: REQ-MERGE-SAFE-IDS
302
+
303
+ An ID is `<prefix>-` followed by six characters from the lowercase Crockford base32 alphabet `0123456789abcdefghjkmnpqrstvwxyz`, drawn from operating-system randomness. That gives 2^30 (about 1.07 billion) IDs per prefix. When a generated ID already exists in `.zban/` or `.zban/archive/`, zban draws again.
304
+
305
+ The filename is `<id>.md` and nothing else. The ID is read from the filename and is not repeated in the frontmatter, so it has a single source, and an issue's path follows from its ID and status alone. A Markdown file in `.zban/` or `.zban/archive/` whose name is not a valid ID is reported by `zban check`. Input IDs are matched case-insensitively.
306
+ :::
307
+
308
+ :::mara design DES-ISSUE-FILE
309
+ :mid: 01M764FJ3ZZGJNFXW9VV1NNVAD
310
+ :title: Issue file format
311
+ :status: accepted
312
+ :satisfies: REQ-ONE-FILE
313
+ :satisfies: REQ-PRESERVE-CONTENT
314
+ :satisfies: REQ-FIXED-VOCABULARY
315
+ :satisfies: REQ-RELATIONS
316
+ :mitigates: RISK-MERGE-CONFLICTS
317
+
318
+ A file starts with a line `---`, then a YAML mapping, then a closing `---` line. One blank line directly after the closing line separates header and body and is not part of the body. Everything after it is the body: free-form Markdown that zban treats as opaque text. The only exceptions are task-item counting in [[DES-LIFECYCLE]] and the handoff section in [[DES-HANDOFF]].
319
+
320
+ | Key | Required | Value |
321
+ | --- | --- | --- |
322
+ | `title` | yes | Non-empty single-line string |
323
+ | `status` | yes | A status from [[REQ-FIXED-VOCABULARY]] |
324
+ | `type` | yes | A type from [[REQ-FIXED-VOCABULARY]] |
325
+ | `priority` | no | A priority; omitted means `normal`, and zban omits `normal` when writing |
326
+ | `tags` | no | List of distinct lowercase words: letters, digits and single hyphens, starting with a letter |
327
+ | `parent` | no | One issue ID |
328
+ | `blocked_by` | no | List of distinct issue IDs |
329
+ | `related` | no | List of distinct issue IDs. The link is symmetric and stored on one of the two issues. |
330
+ | `discovered_from` | no | One issue ID |
331
+ | `created_at` | yes | Timestamp, set on creation |
332
+ | `closed_at` | when closed | Timestamp. Present exactly while the status is `done` or `cancelled`. |
333
+
334
+ Timestamps are RFC 3339 in UTC, written to whole seconds with a `Z` suffix, such as `2026-11-11T20:00:00Z`. Files use LF line endings.
335
+
336
+ Adding a `related` link that already exists in either direction changes nothing. Removing a link edits whichever issue stores it, which may be the other issue.
337
+
338
+ The header must be plain YAML: no anchors, aliases, custom tags, merge keys or duplicate keys. Hand-written headers may use plain, single-quoted or double-quoted scalars, block or flow lists, and comments. When zban writes a header, it uses the key order above, writes a string as a plain scalar when a YAML 1.2 parser reads it back as the same string and double-quoted otherwise, writes lists in block style with one item per line indented by two spaces, and places unknown keys, preserved verbatim, after the known ones. Comments are not kept when zban rewrites a header. Empty lists and absent optional values are omitted. There is no `updated_at`; Git history records changes ([[ADR-MERGE-FRIENDLY-FORMAT]]).
339
+
340
+ When zban writes a file, it writes the closing line, one blank line and the body, or ends the file after the closing line when the body is empty. Text given as a new body, appended text and a handoff note are stored ending with exactly one LF. Appending to a non-empty body joins the text after exactly one blank line.
341
+ :::
342
+
343
+ :::mara design DES-READINESS
344
+ :mid: 01M764FJ3ZXCS66TCPPJ3HF04V
345
+ :title: Readiness and ordering
346
+ :status: accepted
347
+ :satisfies: REQ-READY
348
+
349
+ An issue is ready when all of these hold:
350
+
351
+ 1. its status is `todo`;
352
+ 2. its type is not `epic`;
353
+ 3. every `blocked_by` target is closed;
354
+ 4. no ancestor in its `parent` chain is closed;
355
+ 5. no ancestor has a `blocked_by` target that is still open;
356
+ 6. no ancestor has the status `draft`.
357
+
358
+ Only closed, blocked and `draft` ancestors hold an issue back ([[ADR-DRAFT-HOLDS-DESCENDANTS]]). An ancestor's type, or its status `in-progress`, does not. An unknown or unreadable issue ([[REQ-DAMAGED-DATA]]) counts as open: as a blocker it holds its dependents back, and as a parent it ends the ancestor chain. Ready issues, like every listing, are ordered by priority (`critical` first), then `created_at` (oldest first), then ID. For an open issue that is not ready, zban reports every applicable reason: `status`, `epic`, `blocked_by:<id>`, `ancestor_closed:<id>`, `ancestor_blocked:<id>` and `ancestor_draft:<id>`. It reports them in this order, and the ancestors of one `ancestor_` reason nearest first. In `blocked_by:<id>` the ID is the open blocker. In the three `ancestor_` reasons it is the ancestor, one reason per affected ancestor; showing that ancestor tells what blocks it.
359
+ :::
360
+
361
+ :::mara design DES-LIFECYCLE
362
+ :mid: 01M764FJ3ZPNXY2WFB1Y624PFS
363
+ :title: Status changes and archiving
364
+ :status: accepted
365
+ :satisfies: REQ-CLOSE-CHECKLIST
366
+ :satisfies: REQ-AUTO-ARCHIVE
367
+ :satisfies: REQ-PRESERVE-CONTENT
368
+
369
+ Any status can change to any other status; zban enforces no workflow beyond these rules. New issues default to status `todo`, type `task` and priority `normal`.
370
+
371
+ - **Done with open tasks.** A task item is a list line starting with `- [ ]`, `* [ ]` or `+ [ ]` (unchecked) or the same with `[x]` or `[X]` (checked), at any indentation and outside fenced code blocks. Changing the status to `done` while an unchecked item exists fails unless forced.
372
+ - **Fenced code blocks.** A fence line holds a run of at least three backticks or tildes, with no backtick after a backtick run, indented by at most three columns more than its margin: the content of the list item holding the line, or the line start outside list items. A tab advances to the next multiple of four columns. A fence line opens a block, which ends at a fence line of the same character, at least as long and with nothing after it, or at the end of the body. A list item starts at a line that, within the same indentation limit, begins with `-`, `*`, `+`, or one to nine digits and `.` or `)`, followed by a space, a tab or the line end; the text after the marker is read like a line of its own, so it can start a nested item or a fence. The item's content starts after the marker and the whitespace that follows it, or one column after the marker when that whitespace is wider than four columns or ends the line. The item holds the following lines that are blank or indented at least to its content, and any other line ends it. Lines inside a block neither start nor end list items, so a closing fence has the margin of the opening one.
373
+ - **Close with open children.** Changing the status to `done` or `cancelled` while an issue whose `parent` is this one is open fails unless forced. The error names the open children.
374
+ - **Checked state.** Both rules apply to the issue as the request leaves it, so one update can check the last task item, append a summary and set `done`.
375
+ - **Creating closed.** Creating an issue as `done` while it has an unchecked task item fails the same way, and `create` cannot be forced. To record such an issue, create it open, then force setting `done` with an update. A new issue has no children, so creating it closed never fails for open children.
376
+ - **Closing.** Entering `done` or `cancelled` sets `closed_at`. Leaving them removes it. Closing never changes children or dependents ([[ADR-NO-CASCADE]]).
377
+ - **Placement.** After a status change crosses between open and closed, zban first rewrites the file atomically in place (a temporary file renamed over the original), then renames it into the other directory. If the second step is interrupted, the file has the right content in the wrong place, which `zban check --fix` repairs.
378
+ :::
379
+
380
+ :::mara design DES-CHECK
381
+ :mid: 01M779N2S6013TMF0ZXVSNVZBN
382
+ :title: Check findings and repair
383
+ :status: accepted
384
+ :satisfies: REQ-CHECK
385
+
386
+ `zban check` reports findings ordered by path, then code. In JSON each finding is `{severity, code, path, message}`; human output prints one line per finding, or `No problems found.` when there are none, so a clean run is visibly distinct from no output. The line appears only in human output and only when there are no findings at all, so a check that finds only warnings prints the warnings alone; it changes neither the JSON output nor the exit status.
387
+
388
+ | Code | Severity | Finding |
389
+ | --- | --- | --- |
390
+ | `invalid_config` | error | `config.toml` is unparseable, has an unknown key or `format_version`, or an invalid prefix. When it is reported, check reports nothing else. |
391
+ | `invalid_filename` | error | A Markdown file whose name is not a valid ID ([[DES-ISSUE-ID]]) |
392
+ | `unparseable` | error | No frontmatter, invalid YAML, or YAML outside the plain subset of [[DES-ISSUE-FILE]], such as Git conflict markers |
393
+ | `missing_field` | error | A required key is absent, including `closed_at` on a closed issue |
394
+ | `invalid_value` | error | A value breaks [[DES-ISSUE-FILE]], including `closed_at` on an open issue |
395
+ | `unknown_key` | warning | A frontmatter key zban does not know |
396
+ | `duplicate_id` | error | One ID names a file in both `.zban/` and `.zban/archive/` |
397
+ | `invalid_reference` | error | A relation names an unknown issue or the issue itself. A reference to an existing but unreadable file is not reported again. |
398
+ | `cycle` | error | The issue is on a cycle through `parent` and `blocked_by`, or is blocked by one of its own ancestors ([[REQ-RELATIONS]]) |
399
+ | `related_both_sides` | warning | The same `related` link is stored on both issues |
400
+ | `open_under_closed` | warning | An open issue whose parent is closed |
401
+ | `misplaced` | error | A file in the wrong directory for its status |
402
+ | `temporary_file` | warning | A file named `.zban-*.tmp` directly inside `.zban/` or `.zban/archive/`. zban writes through such files ([[REQ-PRESERVE-CONTENT]]), and an interrupted write leaves one behind. |
403
+
404
+ `--fix` moves each misplaced file into the directory its status requires, unless a file already exists at the target path; that finding then remains. It also deletes each leftover temporary file. The fixed findings are not reported. Because zban writes its temporary files before it takes the lock of [[DES-SHARED-CORE]], `--fix` can delete the temporary file of a write that is still running; that write then fails with `io` and leaves its issue unchanged.
405
+ :::
406
+
407
+ ## Scenario
408
+
409
+ :::mara scenario SCN-PARALLEL-BRANCHES
410
+ :mid: 01M764FJ3Z89Y0KG9KKRR216PZ
411
+ :title: Two agents change issues on separate branches
412
+ :status: accepted
413
+
414
+ Two agents work in separate worktrees of one repository. Each creates new issues and updates an issue the other does not touch. One agent closes its issue, which moves the file into the archive. Both branches merge through ordinary pull requests without conflicts, because new issues have distinct filenames and the edited issues are different files. A conflict appears only when both branches change the same lines of the same issue, and it is resolved like any text conflict. After the merges, `zban check` reports no problems. Neither agent saw the other's status changes before the merge.
415
+ :::
@@ -0,0 +1,116 @@
1
+ # MCP server
2
+
3
+ `zban mcp` serves zban to MCP clients over stdio. It provides the same operations
4
+ as the [command line](cli.mara.md) and tells the client how to use them.
5
+
6
+ ## Setup
7
+
8
+ One server can serve every project, so you can configure it once for your user.
9
+
10
+ Claude Code, for all projects:
11
+
12
+ ```sh
13
+ claude mcp add --scope user zban -- zban mcp
14
+ ```
15
+
16
+ or for one project, in its `.mcp.json`:
17
+
18
+ ```json
19
+ {
20
+ "mcpServers": {
21
+ "zban": { "command": "zban", "args": ["mcp"] }
22
+ }
23
+ }
24
+ ```
25
+
26
+ Or without a global `zban` binary on `PATH`, via `npx`:
27
+
28
+ ```json
29
+ {
30
+ "mcpServers": {
31
+ "zban": { "command": "npx", "args": ["-y", "@convesoft/zban", "mcp"] }
32
+ }
33
+ }
34
+ ```
35
+
36
+ Codex, in `~/.codex/config.toml`:
37
+
38
+ ```toml
39
+ [mcp_servers.zban]
40
+ command = "zban"
41
+ args = ["mcp"]
42
+ ```
43
+
44
+ ## Tools
45
+
46
+ The tools mirror the [commands](cli.mara.md): `list_issues`, `show_issues`,
47
+ `create_issue`, `update_issue`, `delete_issue` and `check_issues`. Their
48
+ parameters are the command's options with underscores for hyphens, a list for
49
+ an option that can repeat and `true` for a flag. The exceptions are `--tag` of
50
+ `create` and `list`, which is `tags` over MCP, like the field in issue files,
51
+ and `--not-tag` of `list`, which is `not_tags`:
52
+
53
+ | Command line | MCP tool call |
54
+ | --- | --- |
55
+ | `zban list --status todo --status in-progress --ready` | `list_issues {"status": ["todo", "in-progress"], "ready": true}` |
56
+ | `zban list --tag cli --tag storage` | `list_issues {"tags": ["cli", "storage"]}` |
57
+ | `zban list --ready --not-tag maintainer` | `list_issues {"ready": true, "not_tags": ["maintainer"]}` |
58
+ | `zban update zb-n938cw --add-tag cli --no-parent` | `update_issue {"id": "zb-n938cw", "add_tag": ["cli"], "no_parent": true}` |
59
+
60
+ Each result is the JSON document that the command prints with `--json`. A
61
+ failure is a tool error carrying the same `{"error": {"code": ..., "message": ...}}`.
62
+
63
+ ## Choosing the project
64
+
65
+ Every tool takes an optional `directory`: an absolute path that zban searches
66
+ upward from, as if it had been started there. Agents pass their working
67
+ directory, which matters when they work in a worktree or outside the directory
68
+ the server started in. Otherwise the tool would change issues in a different
69
+ checkout, on a different branch.
70
+
71
+ Without `directory`, the server uses the directory given with `-C` in `args`,
72
+ or else its own working directory. If no project is found, the server still
73
+ starts, but its tools report `project_not_found`.
74
+
75
+ The server sends the full [agent guide](agents.mara.md) only when it starts
76
+ inside a zban project. Otherwise it sends a short note, so a user-scope server
77
+ costs almost nothing in sessions outside zban projects. See the known limitation
78
+ in [Using zban with agents](agents.mara.md#setup).
79
+
80
+ ## Requirement
81
+
82
+ :::mara requirement REQ-MCP-STDIO
83
+ :mid: 01M764FJ3ZY1HWBNVEGEVYMDFR
84
+ :title: Serve zban over MCP
85
+ :status: accepted
86
+ :satisfies: NEED-FIND-NEXT
87
+ :satisfies: NEED-TRACK-PROGRESS
88
+ :satisfies: NEED-BRANCH-SAFE
89
+
90
+ `zban mcp` runs an MCP server over stdio. Each tool call may name the directory to search for the project from, so one server serves any project or worktree. Without it, the server searches from the directory given with `-C`, or else from its working directory. It exposes listing, showing, creating, updating, deleting and checking issues as tools whose input schemas accept the same arguments as the command line.
91
+ :::
92
+
93
+ ## Design
94
+
95
+ :::mara design DES-MCP-TOOLS
96
+ :mid: 01M764FJ3Z6VP70QDFVWGMZFB8
97
+ :title: MCP tools and server instructions
98
+ :status: accepted
99
+ :satisfies: REQ-MCP-STDIO
100
+ :satisfies: REQ-AGENT-GUIDE
101
+
102
+ | Tool | Operation |
103
+ | --- | --- |
104
+ | `list_issues` | `list` |
105
+ | `show_issues` | `show`, for one or more IDs |
106
+ | `create_issue` | `create` |
107
+ | `update_issue` | `update`, including body edits, the handoff and `force` |
108
+ | `delete_issue` | `delete` |
109
+ | `check_issues` | `check`, with optional `fix` |
110
+
111
+ The parameters of each tool are the options of its command, named with underscores for hyphens: a repeatable option takes a list and a flag a boolean. The positional arguments become `title`, `id` and `ids`. The renamed options are the repeatable `--tag` of `create` and `list`, which becomes `tags` after the issue field it sets or filters on, because agents guess that name from issue files and JSON output, and the repeatable `--not-tag` of `list`, which becomes `not_tags` to match it; `tag` and `not_tag` are then unknown parameters like any other. The `--add-tag` and `--remove-tag` options of `update` keep their names, as `add_tag` and `remove_tag`.
112
+
113
+ Every tool accepts an optional `directory`, an absolute path with the meaning of the CLI's `-C`: the project is searched upward from it. A relative path is rejected. The project is resolved on every call, from the call's `directory`, then the server's `-C`, then the server's working directory.
114
+
115
+ Each tool result carries the JSON document the CLI prints with `--json`, both as structured content and as text. Failures are tool errors with the same error codes; a check that finds errors is not a failure, because its findings are the result. The server's `instructions` are the agent guide rendered for MCP, in full when a project is found at startup and as the short note otherwise ([[DES-AGENT-GUIDE]]). When no project is found, the server still starts, and every tool without a `directory` fails with `project_not_found`, with a message suggesting `directory`. v1 offers no resources or prompts, and no tool for `init`, which is a one-time human action.
116
+ :::