@convesoft/zban 0.0.0 → 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.
- package/README.md +4 -0
- package/bin/zban.cjs +60 -0
- package/docs/agents.mara.md +163 -0
- package/docs/cli.mara.md +159 -0
- package/docs/decisions.mara.md +294 -0
- package/docs/index.mara.md +37 -0
- package/docs/issues.mara.md +415 -0
- package/docs/mcp.mara.md +116 -0
- package/docs/product.mara.md +181 -0
- package/docs/verification.mara.md +146 -0
- package/package.json +16 -2
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# What zban is
|
|
2
|
+
|
|
3
|
+
zban is a file-based issue tracker for you and your coding agents. Issues are
|
|
4
|
+
Markdown files in your repository, managed through a CLI and an MCP server.
|
|
5
|
+
|
|
6
|
+
Coding agents lose track of work between sessions, after context compaction and
|
|
7
|
+
when work passes from one agent to another. Ad-hoc todo lists and chat history
|
|
8
|
+
don't survive any of that. zban gives agents and humans one shared, versioned
|
|
9
|
+
backlog that lives next to the code:
|
|
10
|
+
|
|
11
|
+
- **Plain files.** Each issue is one Markdown file in `.zban/`. You can read,
|
|
12
|
+
edit, grep and review issues without zban installed.
|
|
13
|
+
- **Branches and merges like code.** zban never talks to a server and never
|
|
14
|
+
runs Git. Issue changes travel with your commits.
|
|
15
|
+
- **Built for agents.** Every command has JSON output, the same operations are
|
|
16
|
+
available as MCP tools, and zban teaches agents its workflow itself.
|
|
17
|
+
- **Small on purpose.** A fixed vocabulary, a short command set and no hidden
|
|
18
|
+
state.
|
|
19
|
+
|
|
20
|
+
## What v1 includes
|
|
21
|
+
|
|
22
|
+
Issues with a fixed set of types, statuses and priorities; parent, blocker,
|
|
23
|
+
related and discovered-from relations; a computed list of ready work; automatic
|
|
24
|
+
archiving of closed issues; handoff notes for continuing work in a new session;
|
|
25
|
+
an integrity check; the CLI with JSON output; the MCP server; and the agent guide. See [Issues](issues.mara.md), [Command line](cli.mara.md),
|
|
26
|
+
[MCP server](mcp.mara.md) and [Using zban with agents](agents.mara.md).
|
|
27
|
+
|
|
28
|
+
## What zban deliberately does not do
|
|
29
|
+
|
|
30
|
+
zban does not run agents, manage worktrees, lock or claim issues across
|
|
31
|
+
worktrees, commit for you, serve a web or terminal UI, offer a query language,
|
|
32
|
+
templates or custom fields, or let projects redefine statuses and types. The
|
|
33
|
+
reasons are recorded in [[ADR-SMALL-SCOPE]] and [[ADR-NO-CLAIMS]]. A capability
|
|
34
|
+
outside this list needs a recorded need and decision before it is built.
|
|
35
|
+
|
|
36
|
+
## Goals
|
|
37
|
+
|
|
38
|
+
:::mara goal GOAL-REPO-ISSUES
|
|
39
|
+
:mid: 01M764FJ3Z3R4W2ZGMT5P434J0
|
|
40
|
+
:title: Keep issue tracking in the repository
|
|
41
|
+
:status: accepted
|
|
42
|
+
|
|
43
|
+
Issues live next to the code they describe and are versioned, branched, reviewed and merged with it. Tracking work needs no service, account or database. Anyone with a checkout has the backlog and its history.
|
|
44
|
+
:::
|
|
45
|
+
|
|
46
|
+
:::mara goal GOAL-AGENT-WORKFLOW
|
|
47
|
+
:mid: 01M764FJ3Z3VPB3JGPG1P94AXW
|
|
48
|
+
:title: Let coding agents manage their own work
|
|
49
|
+
:status: accepted
|
|
50
|
+
|
|
51
|
+
Coding agents find what to work on, record progress and outcomes, and file follow-up work through the tracker instead of chat history or ad-hoc todo lists. Work then survives session ends, context compaction and handoffs between agents and humans.
|
|
52
|
+
:::
|
|
53
|
+
|
|
54
|
+
:::mara goal GOAL-SMALL-TOOL
|
|
55
|
+
:mid: 01M764FJ3Z3P69KAH9C5ZFPZWD
|
|
56
|
+
:title: Stay understandable and predictable
|
|
57
|
+
:status: accepted
|
|
58
|
+
|
|
59
|
+
One person can understand the whole of zban, and an agent can predict what each operation does from the agent guide alone. This comes from a fixed data model, a short command set, a file format readable without zban, and no hidden state or background activity. Every added capability spends some of this, so it is added only for a demonstrated need.
|
|
60
|
+
:::
|
|
61
|
+
|
|
62
|
+
## Needs
|
|
63
|
+
|
|
64
|
+
:::mara need NEED-READABLE-FILES
|
|
65
|
+
:mid: 01M764FJ3Z2306WVCH858EK24P
|
|
66
|
+
:title: Read and edit issues without special tools
|
|
67
|
+
:status: accepted
|
|
68
|
+
:contributes_to: GOAL-REPO-ISSUES
|
|
69
|
+
:contributes_to: GOAL-SMALL-TOOL
|
|
70
|
+
|
|
71
|
+
Humans and agents can read, search, review and hand-edit issues as ordinary text files, with or without zban installed.
|
|
72
|
+
:::
|
|
73
|
+
|
|
74
|
+
:::mara need NEED-BRANCH-SAFE
|
|
75
|
+
:mid: 01M764FJ3Z4B0WDVBR7JXWBR5B
|
|
76
|
+
:title: Change issues on parallel branches
|
|
77
|
+
:status: accepted
|
|
78
|
+
:contributes_to: GOAL-REPO-ISSUES
|
|
79
|
+
|
|
80
|
+
People and agents working on separate branches or worktrees can create and update issues independently, and those changes merge through ordinary Git workflows.
|
|
81
|
+
:::
|
|
82
|
+
|
|
83
|
+
:::mara need NEED-ORGANIZE
|
|
84
|
+
:mid: 01M764FJ3ZG12XTG21J7XKEQFC
|
|
85
|
+
:title: Structure and prioritize work
|
|
86
|
+
:status: accepted
|
|
87
|
+
:contributes_to: GOAL-AGENT-WORKFLOW
|
|
88
|
+
|
|
89
|
+
Work can be classified, grouped into larger pieces, ordered by importance, and connected by dependencies and by where it was discovered.
|
|
90
|
+
:::
|
|
91
|
+
|
|
92
|
+
:::mara need NEED-FIND-NEXT
|
|
93
|
+
:mid: 01M764FJ3ZKQYBEXD73381XSPQ
|
|
94
|
+
:title: Find what to work on next
|
|
95
|
+
:status: accepted
|
|
96
|
+
:contributes_to: GOAL-AGENT-WORKFLOW
|
|
97
|
+
|
|
98
|
+
An agent or human can quickly see which issues can be started now, which are in progress, and why the others are waiting.
|
|
99
|
+
:::
|
|
100
|
+
|
|
101
|
+
:::mara need NEED-TRACK-PROGRESS
|
|
102
|
+
:mid: 01M764FJ3Z6S4M6YKX2NXB78TK
|
|
103
|
+
:title: Record progress and outcomes
|
|
104
|
+
:status: accepted
|
|
105
|
+
:contributes_to: GOAL-AGENT-WORKFLOW
|
|
106
|
+
|
|
107
|
+
Agents can create issues, record what is in progress, keep a task checklist current, and record what was done or why work was abandoned.
|
|
108
|
+
:::
|
|
109
|
+
|
|
110
|
+
:::mara need NEED-AGENT-ONBOARDING
|
|
111
|
+
:mid: 01M764FJ3Z8YQQEKPG1YMKZK0P
|
|
112
|
+
:title: Agents learn the workflow from the tool
|
|
113
|
+
:status: accepted
|
|
114
|
+
:contributes_to: GOAL-AGENT-WORKFLOW
|
|
115
|
+
|
|
116
|
+
An agent learns how to use zban, and the expected work discipline, from zban itself, whether it reaches zban through MCP or the command line, without the project writing its own instructions.
|
|
117
|
+
:::
|
|
118
|
+
|
|
119
|
+
:::mara need NEED-SESSION-CONTINUITY
|
|
120
|
+
:mid: 01M777QQGMVA28TW42QWJCGFX0
|
|
121
|
+
:title: Continue unfinished work in a new session
|
|
122
|
+
:status: accepted
|
|
123
|
+
:contributes_to: GOAL-AGENT-WORKFLOW
|
|
124
|
+
|
|
125
|
+
A developer can end an agent session with work unfinished and continue it in a new session, with the same or another agent, from the current state, the next steps and the approaches already rejected, without replaying the old conversation.
|
|
126
|
+
:::
|
|
127
|
+
|
|
128
|
+
:::mara need NEED-PROJECT-MEMORY
|
|
129
|
+
:mid: 01M764FJ3Z76TNN9PYF84SMRNB
|
|
130
|
+
:title: Keep finished work as project memory
|
|
131
|
+
:status: accepted
|
|
132
|
+
:contributes_to: GOAL-AGENT-WORKFLOW
|
|
133
|
+
|
|
134
|
+
Finished and abandoned issues stay available as context about past work, without crowding the list of active work.
|
|
135
|
+
:::
|
|
136
|
+
|
|
137
|
+
:::mara need NEED-INTEGRITY
|
|
138
|
+
:mid: 01M764FJ3Z8BV1YNJN9TA5QQDA
|
|
139
|
+
:title: Trust the issue data
|
|
140
|
+
:status: accepted
|
|
141
|
+
:contributes_to: GOAL-REPO-ISSUES
|
|
142
|
+
|
|
143
|
+
Users can detect and repair inconsistent issue data introduced by hand edits, interrupted writes or merges.
|
|
144
|
+
:::
|
|
145
|
+
|
|
146
|
+
:::mara need NEED-NPM-DISTRIBUTION
|
|
147
|
+
:mid: 01M81JC6J5RQMFZ60SKJN5XGHQ
|
|
148
|
+
:title: Install and run zban through npm
|
|
149
|
+
:status: accepted
|
|
150
|
+
:contributes_to: GOAL-AGENT-WORKFLOW
|
|
151
|
+
|
|
152
|
+
Developers and coding-agent setups can install and run zban through npm and `npx` on the supported platforms without manually downloading GitHub Release archives or compiling Rust from source.
|
|
153
|
+
:::
|
|
154
|
+
|
|
155
|
+
## Vocabulary
|
|
156
|
+
|
|
157
|
+
:::mara term TERM-ISSUE
|
|
158
|
+
:mid: 01M764FJ3Z16YDB0AKKDJWA6K0
|
|
159
|
+
:title: Issue
|
|
160
|
+
:status: accepted
|
|
161
|
+
:aliases: ticket
|
|
162
|
+
|
|
163
|
+
One tracked unit of work, stored as one file in the project's `.zban/` directory. Every issue has a type: epic, feature, bug or task. The file format is defined in [[DES-ISSUE-FILE]].
|
|
164
|
+
:::
|
|
165
|
+
|
|
166
|
+
:::mara term TERM-READY
|
|
167
|
+
:mid: 01M764FJ3ZM923FNVJ8RAPBF9T
|
|
168
|
+
:title: Ready issue
|
|
169
|
+
:status: accepted
|
|
170
|
+
:aliases: actionable issue
|
|
171
|
+
|
|
172
|
+
An issue that can be started now. Readiness is computed from status, type and relations whenever it is needed and is never stored; the rule is [[DES-READINESS]].
|
|
173
|
+
:::
|
|
174
|
+
|
|
175
|
+
:::mara term TERM-CLOSED
|
|
176
|
+
:mid: 01M764FJ3ZY93Z24QC6JRBVV5S
|
|
177
|
+
:title: Closed issue
|
|
178
|
+
:status: accepted
|
|
179
|
+
|
|
180
|
+
An issue with status `done` or `cancelled`. Closed issues are kept in `.zban/archive/` as project memory.
|
|
181
|
+
:::
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# Verification
|
|
2
|
+
|
|
3
|
+
How we establish that zban meets its requirements and goals. Each definition
|
|
4
|
+
says what to check and what to expect. A definition is not a result: results
|
|
5
|
+
come from actual test runs, cited when an issue is closed.
|
|
6
|
+
|
|
7
|
+
## Requirement checks
|
|
8
|
+
|
|
9
|
+
:::mara verification VER-ISSUE-FILES
|
|
10
|
+
:mid: 01M764FJ3ZP3SETQ9WX71Z5RYM
|
|
11
|
+
:title: Round-trip issue files
|
|
12
|
+
:status: accepted
|
|
13
|
+
:methods: test
|
|
14
|
+
:verifies: REQ-ONE-FILE
|
|
15
|
+
:verifies: REQ-PRESERVE-CONTENT
|
|
16
|
+
:verifies: REQ-FIXED-VOCABULARY
|
|
17
|
+
:verifies: REQ-NO-LOST-UPDATES
|
|
18
|
+
|
|
19
|
+
Load fixture projects, including a copy of this repository's `.zban/`, and write each issue back without changes. Files already in canonical form are byte-identical. Metadata-only updates leave body bytes and unknown keys intact. A hand-written header with comments, quoted scalars and flow lists loads, and rewriting it drops the comments and writes the canonical form. Titles that YAML would read as another type, or that contain `: ` or ` #`, survive a write and a read unchanged. The blank line after the header is not part of the body, and an issue with an empty body ends after the closing line. Values outside the fixed vocabulary are rejected by create and update and reported by check. A write interrupted before its rename leaves the original file unchanged and no partial issue file. When a file changes between the read and the write of an update, the update fails with `conflict` and the other change survives. Many processes of the real binary update one issue at the same time, each retrying after `conflict`; none fails with another error, and every change an update reported as written is in the final file exactly once. Processes that run `zban show` and `zban list --all` find the issue every time and warn about no file, both while another process keeps renaming a copy of the issue over it under the lock and while another process keeps closing and reopening it as `zban update` does, rewriting it in place and then moving it into the other directory, each step under the lock. An update, a delete and a move by `zban check --fix` wait while another process holds the lock on `.zban/`, and so do `show` and `list`, which do not wait while another process holds it shared. A failure to take the lock lets the write or read go ahead only when it means that locking is unsupported. Create never replaces an existing file. A test makes linking fail as on a file system without hard links, since CI has none: with `EPERM` on Linux or as unsupported, `init` and `create` rename the new file into place instead, a create skips an ID taken in `.zban/` or `.zban/archive/`, and no temporary file is left; any other linking error fails with `io` and creates no file. When writing the configuration of `init` fails, by linking or by the write itself, `init` leaves no `.zban/`, and running it again succeeds.
|
|
20
|
+
:::
|
|
21
|
+
|
|
22
|
+
:::mara verification VER-ID-GENERATION
|
|
23
|
+
:mid: 01M764FJ3ZJ4XPRVDCB25S8X0A
|
|
24
|
+
:title: Generate merge-safe IDs
|
|
25
|
+
:status: accepted
|
|
26
|
+
:methods: test
|
|
27
|
+
:methods: analysis
|
|
28
|
+
:verifies: REQ-MERGE-SAFE-IDS
|
|
29
|
+
|
|
30
|
+
Generated IDs match `<prefix>-[0-9a-hjkmnp-tv-z]{6}`. With an injected generator that returns an existing ID first, create retries and succeeds with a fresh ID, checking both `.zban/` and `.zban/archive/`. `zban init` without `--prefix` writes prefix `zb`, and an invalid `--prefix` is rejected without creating `.zban/`. The collision analysis in [[RISK-ID-COLLISION]] still holds for the implemented alphabet and length.
|
|
31
|
+
:::
|
|
32
|
+
|
|
33
|
+
:::mara verification VER-NO-GIT
|
|
34
|
+
:mid: 01M764FJ3ZRQW0D630KWF72XY9
|
|
35
|
+
:title: Work without version control
|
|
36
|
+
:status: accepted
|
|
37
|
+
:methods: test
|
|
38
|
+
:methods: inspection
|
|
39
|
+
:verifies: REQ-NO-GIT
|
|
40
|
+
|
|
41
|
+
Run every command in a temporary directory that is not a Git repository and confirm they all succeed. Snapshot the files outside `.zban/` before and after a full create, update, close, reopen and check cycle, and confirm nothing changed. Inspect the source and confirm that zban starts no external processes.
|
|
42
|
+
:::
|
|
43
|
+
|
|
44
|
+
:::mara verification VER-RELATIONS-READY
|
|
45
|
+
:mid: 01M764FJ3Z2PGEHD2FMGDY4N6G
|
|
46
|
+
:title: Compute relations and readiness
|
|
47
|
+
:status: accepted
|
|
48
|
+
:methods: test
|
|
49
|
+
:verifies: REQ-RELATIONS
|
|
50
|
+
:verifies: REQ-READY
|
|
51
|
+
|
|
52
|
+
The fixture contains: A blocking B; an independent C; an epic E; a child D whose parent is blocked; a task G under an epic that sits inside another epic blocked by an open epic J; a draft F; and issues of differing priority and age. The ready list contains exactly the expected issues in priority, age and ID order. Each non-ready issue reports its reasons. A `todo` child of a `draft` parent, and a `todo` issue below that child, report `ancestor_draft` naming that parent and become ready once it is `todo`, also through the real binary and the MCP server; an issue below two `draft` ancestors reports both, nearest first. A `todo` child of an `in-progress` parent is ready. Closing A makes B ready. G reports `ancestor_blocked` and becomes ready once J closes. An issue blocked by an unreadable file is not ready, and an unreadable parent ends the ancestor chain. Adding a `related` link that already exists in the reverse direction changes no file, and removing it from either side deletes it from the issue that stores it. References to unknown issues and self references fail with `invalid_reference`. Cycles through `parent`, through `blocked_by`, and through both together, such as an epic blocked by its own child, fail with `cycle`, and so does a `blocked_by` on an ancestor. Deleting a referenced issue is refused. `show` lists children, blocks, related and discovered issues in the reverse direction.
|
|
53
|
+
:::
|
|
54
|
+
|
|
55
|
+
:::mara verification VER-LIFECYCLE
|
|
56
|
+
:mid: 01M764FJ3Z7VZZATFZS034NZXH
|
|
57
|
+
:title: Close, archive and reopen issues
|
|
58
|
+
:status: accepted
|
|
59
|
+
:methods: test
|
|
60
|
+
:verifies: REQ-CLOSE-CHECKLIST
|
|
61
|
+
:verifies: REQ-AUTO-ARCHIVE
|
|
62
|
+
|
|
63
|
+
Setting `done` with an unchecked task item fails and changes nothing. With force it succeeds. Creating an issue as `done` with an unchecked task item fails with the same code and creates no file, through the command line and MCP alike, and `create` accepts no force. A task item inside a fenced code block does not count, including a block nested in list items whose fence is indented to their content. A fence line indented by four columns outside a list item, or by four columns more than the content of its list item, opens no block, so the task items after it count. Setting `done` or `cancelled` on an issue with an open child fails, names the child and changes nothing. With force it succeeds and leaves the child unchanged. Closing sets `closed_at` and moves the file to `.zban/archive/`, and reopening clears `closed_at` and moves it back. Archived issues appear in `show`, in search, in relations and in `list --all`, but not in the default listing. Listings report checklist progress.
|
|
64
|
+
:::
|
|
65
|
+
|
|
66
|
+
:::mara verification VER-HANDOFF
|
|
67
|
+
:mid: 01M777QQGM8AY4TX1GGM86HG6F
|
|
68
|
+
:title: Write and read handoff notes
|
|
69
|
+
:status: accepted
|
|
70
|
+
:methods: test
|
|
71
|
+
:verifies: REQ-HANDOFF
|
|
72
|
+
|
|
73
|
+
Through the real binary: `update --handoff` adds a timestamped `## Handoff` section to a body without one, and a second update replaces it in place while every byte outside the section stays unchanged. Text read from standard input works. `--no-handoff` removes the section. Text containing a level 2 heading is rejected, a `## Handoff` heading inside a fenced code block is ignored while one after a fence line indented by four columns outside a list item is found, a body with two handoff sections makes both options fail without writing, and so does `--handoff` on a body that leaves a fenced code block open. `show` returns the text and time, a heading without a timestamp gives `written_at: null`, and `list` reports `handoff_at`. Closing an issue leaves its handoff untouched, and `zban prime` and the MCP instructions contain no handoff text.
|
|
74
|
+
:::
|
|
75
|
+
|
|
76
|
+
:::mara verification VER-CHECK
|
|
77
|
+
:mid: 01M764FJ3ZPNVFEX72X29BGRTT
|
|
78
|
+
:title: Report and repair inconsistencies
|
|
79
|
+
:status: accepted
|
|
80
|
+
:methods: test
|
|
81
|
+
:verifies: REQ-CHECK
|
|
82
|
+
|
|
83
|
+
Use a corpus of broken projects, one for each finding code in [[DES-CHECK]]. `zban check` reports each problem with that code, its severity and path. It exits non-zero on errors, and exits 0 when it finds only the warnings named in [[REQ-CHECK]]. A clean project prints `No problems found.` and exits 0, and its `--json` output is `{"findings": []}`. A check that finds only warnings prints them without that line, and a `zban check --fix` that repairs every finding prints it. `zban check --fix` moves only misplaced files and deletes only leftover temporary files, leaving every other file and finding untouched, and a second check reports neither. A misplaced file whose target path is taken stays in place and is still reported. The temporary file of a real interrupted write is reported, and files whose names only resemble one are not.
|
|
84
|
+
:::
|
|
85
|
+
|
|
86
|
+
:::mara verification VER-CLI
|
|
87
|
+
:mid: 01M764FJ3ZZBZYQWC7EQ4093FG
|
|
88
|
+
:title: Exercise the command line contract
|
|
89
|
+
:status: accepted
|
|
90
|
+
:methods: test
|
|
91
|
+
:verifies: REQ-JSON-OUTPUT
|
|
92
|
+
:verifies: REQ-LIST-FILTERS
|
|
93
|
+
:verifies: REQ-BODY-EDITS
|
|
94
|
+
:verifies: REQ-DAMAGED-DATA
|
|
95
|
+
|
|
96
|
+
Run every command with `--json` through the real binary. The output parses as one document with the fields documented in [[DES-CLI]]. Failures return an error object and exit status 1, and invalid usage exits with 2. Each error code in [[DES-CLI]] is produced by at least one test. Each list filter alone and in combination, search and `--all` select the expected issues, in the order defined by [[DES-READINESS]], and `--parent` selects direct children only. A fixture holds issues that `--not-tag` keeps and issues it drops: one value, repeated values, and `--not-tag` combined with `--tag`, `--status`, `--type`, `--parent`, `--search`, `--ready` and `--all` leave out exactly the issues carrying an excluded tag, including an issue that also carries a tag of `--tag`, and a valid tag that no issue carries is accepted and excludes nothing. A `--tag` or `--not-tag` value that is not a valid tag fails with `invalid_value`. `child_counts` is `{closed: 0, total: 0}` for an issue without children, counts `done` and `cancelled` children as closed whether archived or not, leaves out grandchildren, also of an epic under an epic, and follows a child moved to another parent, in `list`, `show` and mutation results, and human output shows it only when `total` is above 0. A child whose ID names two files is left out of the parent's `child_counts` with `duplicate_id` warnings, while closing the parent fails with `open_children` naming it. `list --parent` with a malformed or unknown ID fails with `not_found`, and with an unreadable or duplicated ID fails like `show`. The short options `-s`, `-t` and `-p` of `list` select the same issues as `--status`, `--type` and `--priority`. The `not_found` message for an unknown ID in the project's format, in human and JSON output, carries the hint about another branch or worktree, and the message for any other value does not and shows the ID format instead. Commands run outside a project fail with `project_not_found`. `-C DIR`, given a project root or one of its subdirectories, behaves like starting in `DIR`. `init` inside a project returns that project's `.zban/` as `enclosing` and names it in human output, and `init` outside any project returns `enclosing: null` and prints no note. Replacing text that is absent or occurs more than once fails without writing. `--append` joins its text after exactly one blank line. An update that combines replacements, an append and metadata changes is all or nothing, and one update can check the last task item and set `done`. Body input from standard input works for create and update.
|
|
97
|
+
|
|
98
|
+
A fixture holds a file with Git conflict markers, an issue with an invalid status, an issue with a dangling `blocked_by` and an ID present in both `.zban/` and `.zban/archive/`. `list` and `show` of other issues succeed and report warnings for the broken files. Updating the issue with the dangling blocker, for example setting it `in-progress`, succeeds. Showing or updating an unreadable issue fails with `unreadable`, and showing the duplicated ID fails with `ambiguous_id`.
|
|
99
|
+
:::
|
|
100
|
+
|
|
101
|
+
:::mara verification VER-SURFACE-PARITY
|
|
102
|
+
:mid: 01M764FJ3Z01GJN91JB409C3GW
|
|
103
|
+
:title: Match CLI and MCP behaviour
|
|
104
|
+
:status: accepted
|
|
105
|
+
:methods: test
|
|
106
|
+
:verifies: REQ-SURFACE-PARITY
|
|
107
|
+
:verifies: REQ-MCP-STDIO
|
|
108
|
+
|
|
109
|
+
A real MCP client talks to `zban mcp` over stdio and runs a create, block, ready, update, close and check flow. For the same requests against identical fixtures, the tool results equal the CLI's JSON output, and invalid arguments produce the same error codes. The fixtures include a parent with a nested child, so the results compare `child_counts` too. The tool list matches [[DES-MCP-TOOLS]], `create_issue` and `list_issues` take `tags` and refuse `tag` as an unknown parameter, and `list_issues` takes `not_tags` and refuses `not_tag`. `list_issues` with `not_tags`, alone, repeated and combined with `tags`, `ready`, `parent`, `type`, `priority` and `all`, returns the CLI's JSON for the same `list --not-tag` request on a fixture where the parameter changes the result, and an invalid tag in `tags` or `not_tags` fails with `invalid_value` on both surfaces without changing any file. Started outside a project, the server sends the short note as its instructions and every tool without a `directory` fails with `project_not_found`. Calls whose `directory` points into another project or worktree read and write only that project, and a relative `directory` is rejected.
|
|
110
|
+
:::
|
|
111
|
+
|
|
112
|
+
:::mara verification VER-AGENT-GUIDE
|
|
113
|
+
:mid: 01M764FJ3ZZ9YTCWGRGCH00BBV
|
|
114
|
+
:title: Keep the agent guide consistent
|
|
115
|
+
:status: accepted
|
|
116
|
+
:methods: test
|
|
117
|
+
:methods: inspection
|
|
118
|
+
:verifies: REQ-AGENT-GUIDE
|
|
119
|
+
|
|
120
|
+
Snapshot tests cover `zban prime` and the MCP server instructions, both rendered from the same template. The vocabulary lists in the guide equal the enumerations in the code, and every command or tool the guide names exists. The command-line reference lists every option of each command it names, such as `list --not-tag`, and each option is a parameter of its tool under the names of [[DES-MCP-TOOLS]]. A test fails when the MCP rendering exceeds the character budget in [[DES-AGENT-GUIDE]]. `zban prime` outside a project prints nothing and exits 0, and `zban prime -C <project>` from there prints the full guide. `zban prime --json` prints `{"guide": ...}`, with `null` outside a project. A server started inside a project sends the full guide; one started outside sends the short note, which names `directory` and `zban prime -C`. Both renderings start with the heading `# zban workflow`, which the short note does not, and the line that the setup guidance in `docs/agents.mara.md` recommends names that heading and `zban prime`. Both renderings tell agents to park planned epics, backlog and human-only work as `draft`, and their readiness rule names `draft` ancestors. Inspection confirms the guide covers the sections in [[DES-AGENT-GUIDE]] and stays under about 150 lines.
|
|
121
|
+
:::
|
|
122
|
+
|
|
123
|
+
## Outcome checks
|
|
124
|
+
|
|
125
|
+
:::mara validation VAL-DOGFOOD
|
|
126
|
+
:mid: 01M764FJ3ZND8RM7NMZNT08MP6
|
|
127
|
+
:title: Track zban's own development with zban
|
|
128
|
+
:status: accepted
|
|
129
|
+
:methods: demonstration
|
|
130
|
+
:validates: GOAL-AGENT-WORKFLOW
|
|
131
|
+
:validates: GOAL-REPO-ISSUES
|
|
132
|
+
:exercises: SCN-AGENT-SESSION
|
|
133
|
+
:exercises: SCN-PARALLEL-BRANCHES
|
|
134
|
+
|
|
135
|
+
After the CLI works, zban's own backlog is managed only through zban. Over at least ten issues worked on by agents, including some in parallel worktrees, review the history. Whoever chose the work, a single agent or whoever ran the parallel agents ([[ADR-NO-CLAIMS]]), found it with `zban list --ready`. Given only an issue to work on, agents kept checklists and summaries and closed their issues without further prompting. Discovered work was filed as issues. No issue needed a manual frontmatter repair other than merge conflicts. `zban check` stayed clean on `main`. Record shortfalls as issues or as changes to this knowledge.
|
|
136
|
+
:::
|
|
137
|
+
|
|
138
|
+
:::mara validation VAL-SCOPE-REVIEW
|
|
139
|
+
:mid: 01M774FDH7HRY5CQ0DNGHYY3FG
|
|
140
|
+
:title: Review zban's size before each release
|
|
141
|
+
:status: accepted
|
|
142
|
+
:methods: inspection
|
|
143
|
+
:validates: GOAL-SMALL-TOOL
|
|
144
|
+
|
|
145
|
+
Before each release, review the knowledge and the agent guide. Every capability traces to an accepted need. The commands in [[DES-CLI]] and the keys in [[DES-ISSUE-FILE]] changed only through recorded decisions. The agent guide stays under about 150 lines and covers every operation. In [[VAL-DOGFOOD]], agents needed nothing beyond the guide to predict what zban would do. Record shortfalls as issues or as changes to this knowledge.
|
|
146
|
+
:::
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@convesoft/zban",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "1.0.0-rc.1",
|
|
4
|
+
"description": "A file-based issue tracker for you and your coding agents: Markdown issues in your repository, managed through a CLI and MCP server",
|
|
5
5
|
"license": "MIT OR Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -11,7 +11,21 @@
|
|
|
11
11
|
"publishConfig": {
|
|
12
12
|
"access": "public"
|
|
13
13
|
},
|
|
14
|
+
"bin": {
|
|
15
|
+
"zban": "bin/zban.cjs"
|
|
16
|
+
},
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=18"
|
|
19
|
+
},
|
|
20
|
+
"optionalDependencies": {
|
|
21
|
+
"@convesoft/zban-linux-x64": "1.0.0-rc.1",
|
|
22
|
+
"@convesoft/zban-linux-arm64": "1.0.0-rc.1",
|
|
23
|
+
"@convesoft/zban-darwin-arm64": "1.0.0-rc.1",
|
|
24
|
+
"@convesoft/zban-darwin-x64": "1.0.0-rc.1"
|
|
25
|
+
},
|
|
14
26
|
"files": [
|
|
27
|
+
"bin/zban.cjs",
|
|
28
|
+
"docs/",
|
|
15
29
|
"README.md",
|
|
16
30
|
"LICENSE-MIT",
|
|
17
31
|
"LICENSE-APACHE"
|