@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 CHANGED
@@ -133,6 +133,10 @@ specification:
133
133
  - [Decisions and risks](docs/decisions.mara.md)
134
134
  - [Verification](docs/verification.mara.md)
135
135
 
136
+ The `@convesoft/zban` npm package carries these pages for its own version, in
137
+ `node_modules/@convesoft/zban/docs/`, so agents and developers can read them
138
+ without the repository.
139
+
136
140
  ## Development
137
141
 
138
142
  zban is written in Rust. The specification is maintained with
package/bin/zban.cjs ADDED
@@ -0,0 +1,60 @@
1
+ #!/usr/bin/env node
2
+
3
+ "use strict";
4
+
5
+ const path = require("node:path");
6
+ const { spawn } = require("node:child_process");
7
+
8
+ const packages = new Map([
9
+ ["linux:x64", "@convesoft/zban-linux-x64"],
10
+ ["linux:arm64", "@convesoft/zban-linux-arm64"],
11
+ ["darwin:arm64", "@convesoft/zban-darwin-arm64"],
12
+ ["darwin:x64", "@convesoft/zban-darwin-x64"],
13
+ ]);
14
+
15
+ const packageName = packages.get(`${process.platform}:${process.arch}`);
16
+ if (packageName === undefined) {
17
+ console.error(
18
+ `zban does not provide an npm binary for ${process.platform}/${process.arch}. ` +
19
+ "Supported targets are Linux (x64, arm64) and macOS (arm64, x64).",
20
+ );
21
+ process.exitCode = 1;
22
+ } else {
23
+ let binary;
24
+ try {
25
+ const manifest = require.resolve(`${packageName}/package.json`);
26
+ binary = path.join(path.dirname(manifest), "bin", "zban");
27
+ } catch {
28
+ console.error(
29
+ `The optional package ${packageName} is missing. ` +
30
+ "Reinstall @convesoft/zban with optional dependencies enabled.",
31
+ );
32
+ process.exitCode = 1;
33
+ }
34
+
35
+ if (binary !== undefined) {
36
+ const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });
37
+ const handlers = new Map();
38
+ for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
39
+ const handler = () => child.kill(signal);
40
+ handlers.set(signal, handler);
41
+ process.on(signal, handler);
42
+ }
43
+
44
+ child.once("error", (error) => {
45
+ console.error(`Could not start ${packageName}: ${error.message}`);
46
+ process.exitCode = 1;
47
+ });
48
+
49
+ child.once("exit", (code, signal) => {
50
+ for (const [name, handler] of handlers) {
51
+ process.off(name, handler);
52
+ }
53
+ if (signal !== null) {
54
+ process.kill(process.pid, signal);
55
+ } else {
56
+ process.exitCode = code ?? 1;
57
+ }
58
+ });
59
+ }
60
+ }
@@ -0,0 +1,163 @@
1
+ # Using zban with agents
2
+
3
+ zban teaches agents its workflow itself, so a project needs very little setup.
4
+
5
+ ## Setup
6
+
7
+ **With MCP** (recommended where supported): configure the [MCP server](mcp.mara.md).
8
+ The server's instructions carry the agent guide, and clients such as Claude Code
9
+ keep them in context across compaction. Started outside a zban project, the
10
+ server sends only a short note instead of the full guide.
11
+
12
+ **In your agent instructions**: add this line to your `AGENTS.md` or `CLAUDE.md`,
13
+ so that agents without the guide read it from `zban prime`:
14
+
15
+ ```markdown
16
+ **IMPORTANT**: this project tracks its work with zban. If your instructions already
17
+ contain the zban workflow guide (it starts with `# zban workflow`), for example from
18
+ the zban MCP server, follow it and use the zban tools. Otherwise, before anything
19
+ else, run `zban prime` and follow its output.
20
+ ```
21
+
22
+ An agent with the MCP server finds the guide in its instructions and skips
23
+ `zban prime`, so it does not read the guide twice. CLI-only agents, CI jobs and
24
+ clients that ignore server instructions run `zban prime`.
25
+
26
+ **Without MCP**, Claude Code can instead inject the guide with hooks in
27
+ `.claude/settings.json`:
28
+
29
+ ```json
30
+ {
31
+ "hooks": {
32
+ "SessionStart": [{ "hooks": [{ "type": "command", "command": "zban prime" }] }],
33
+ "PreCompact": [{ "hooks": [{ "type": "command", "command": "zban prime" }] }]
34
+ }
35
+ }
36
+ ```
37
+
38
+ `zban prime` prints nothing outside a zban project, so these hooks can also go in
39
+ your user-level settings. A hook adds the guide even when the MCP server has sent
40
+ it, so do not combine the hooks with the server.
41
+
42
+ > **Known limitation:** zban decides whether to deliver the guide from the
43
+ > directory where the session starts. If you start your agent in a folder above
44
+ > the project, such as a folder holding several repositories, or the top of a
45
+ > monorepo whose `.zban/` lives in a subfolder, the agent gets no guide from
46
+ > `zban prime`, and only the short note over MCP. Start the session inside the
47
+ > project, or ask the agent to run `zban prime -C <project>`.
48
+
49
+ Project-specific rules belong in your own `AGENTS.md`, for example "include the
50
+ issue ID in commit messages as `Refs: zb-xxxxxx`". zban does not configure them.
51
+
52
+ ## Things to ask your agent
53
+
54
+ - "Are there tasks we should be tracking? Create issues for them."
55
+ - "What should we work on next?"
56
+ - "Start on zb-n938cw."
57
+ - "Break the export feature into an epic with tasks and dependencies."
58
+ - "Write a handoff for zb-n938cw."
59
+ - "Continue where we left off on zb-n938cw."
60
+
61
+ ## Handoffs
62
+
63
+ A handoff is a short note on an issue that lets a new session continue
64
+ unfinished work without rereading the old conversation. Ask your agent to write
65
+ one while it still has the conversation, for example before you clear a long
66
+ session and start fresh instead of relying on compaction. The agent writes it
67
+ with `update --handoff`, which replaces any earlier note, so the issue always
68
+ holds the current state; Git keeps the history.
69
+
70
+ ```markdown
71
+ ## Handoff (2026-11-12T18:40:00Z)
72
+
73
+ - At 5b93272 on feat/parser, working tree clean.
74
+ - Done: reader and canonical writer.
75
+ - Next: preserve unknown keys.
76
+ - Uncertain: flow-style lists written by hand.
77
+ - Rejected: round-tripping through a generic YAML value, which loses key order.
78
+ - Files: src/store.rs, tests/files.rs
79
+ ```
80
+
81
+ zban stamps the heading with the time the note was written, and `list` and
82
+ `show` report its age. zban cannot see Git, so the agent records the commit and
83
+ branch itself. A new session reads a handoff only when you ask it to continue;
84
+ it then checks the note against the repository before acting on it, because a
85
+ stale note can mislead. When the issue is done, the agent replaces the handoff
86
+ with `## Summary of Changes` and keeps the approaches it rejected.
87
+
88
+ zban does not load handoffs into new sessions by itself: notes belong to
89
+ issues, and zban cannot tell which issue a new session is about.
90
+
91
+ ## Requirements
92
+
93
+ :::mara requirement REQ-AGENT-GUIDE
94
+ :mid: 01M764FJ3Z4GXPTR8FHAF3XX7E
95
+ :title: Teach agents the zban workflow
96
+ :status: accepted
97
+ :satisfies: NEED-AGENT-ONBOARDING
98
+
99
+ zban provides an agent workflow guide through `zban prime` and through the MCP server instructions. Both deliver the full guide only when a project is found, so sessions outside zban projects carry almost none of it. Both come from one source text and name the operations the way the surface does: commands for the CLI, tools for MCP. An agent can tell from its own context whether it already has the guide, so a project's agent instructions can load it through `zban prime` only where it is missing. The vocabulary in the guide comes from the binary itself, so it cannot disagree with the binary.
100
+ :::
101
+
102
+ :::mara requirement REQ-HANDOFF
103
+ :mid: 01M777QQGMEKBF23H6FN17YY39
104
+ :title: Hand off unfinished work through the issue
105
+ :status: accepted
106
+ :satisfies: NEED-SESSION-CONTINUITY
107
+
108
+ An issue can hold one handoff note in its body. An update writes the note, replacing any previous one, or removes it, and zban records when the note was written. Showing an issue returns the note and its time, and listing reports the time for each issue that has one. zban never writes, removes or delivers a handoff note on its own; the guide tells agents to write and read notes when the developer asks.
109
+ :::
110
+
111
+ ## Design
112
+
113
+ :::mara design DES-AGENT-GUIDE
114
+ :mid: 01M764FJ3ZPFMKF31AGPP8X9PA
115
+ :title: Agent guide content
116
+ :status: accepted
117
+ :satisfies: REQ-AGENT-GUIDE
118
+ :mitigates: RISK-SESSION-ABOVE-PROJECT
119
+
120
+ The guide is one template compiled into the binary and kept under about 150 lines, because it is paid for in every agent context. The MCP rendering also stays within 3,800 characters, a margin under the 4,096 at which Claude Code truncates server instructions. It leaves out what the tool schemas carry, such as each tool's parameters, and both renderings share tight wording rather than diverging text. Its sections are:
121
+
122
+ 1. **Track work in zban.** Use issues instead of ad-hoc todo lists. Park planned epics, backlog and work only a human can do as `draft`, which keeps them and everything under them out of ready work ([[ADR-DRAFT-HOLDS-DESCENDANTS]]).
123
+ 2. **Before starting.** Look for an existing issue, otherwise create one; set it `in-progress`.
124
+ 3. **While working.** Keep the body's checklist current. File newly discovered work as separate issues with `discovered_from` rather than widening the current one. On a `conflict` error, show the issue again and retry.
125
+ 4. **Finishing.** Add `## Summary of Changes` and set `done`. If unchecked items or open children remain, finish them, close them or move them into follow-up issues; force only when the user agrees. To abandon work, add `## Reasons for Cancelling` and set `cancelled`.
126
+ 5. **Committing.** Commit issue files together with the code they describe.
127
+ 6. **Handoffs.** Writing and resuming handoff notes, as in [[DES-HANDOFF]].
128
+ 7. **Finding work.** Use the ready list and offer the top candidates; show an issue before starting it.
129
+ 8. **Reference.** Types, statuses, priorities, relations and the readiness rule. The command-line rendering also lists every command with its options, such as `list --not-tag`, and says that it leaves out issues carrying any of its tags; the MCP rendering leaves the tools' parameters, such as `not_tags` of `list_issues`, to their schemas.
130
+
131
+ The MCP rendering also tells agents to pass `directory` on every call when they work in a worktree or outside the directory the server started in.
132
+
133
+ Delivery depends on the project found where the surface starts: from the working directory or `-C` for `prime`, and from the server's `-C` or working directory at startup for MCP. With a project, both deliver the full guide; a project whose configuration is invalid still counts, because the guide does not depend on it. Without one, `prime` prints nothing, and the MCP server sends a short note of a few lines instead: zban tracks issues in `.zban/` directories, no project was found where the server started, tools take `directory`, and `zban prime -C <dir>` prints the full guide.
134
+
135
+ Both renderings open with the heading `# zban workflow`, and the line that the setup guidance recommends for a project's agent instructions names it: an agent whose instructions already hold the guide, for example from the MCP server, follows it and uses the tools, and any other agent runs `zban prime`. An agent with both the server and the line therefore reads the guide once, with the operations of the surface it has.
136
+
137
+ Project-specific conventions are deliberately left out; projects add them in their own agent instructions.
138
+ :::
139
+
140
+ :::mara design DES-HANDOFF
141
+ :mid: 01M777QQGMQNB89NDDMPGRTTFA
142
+ :title: Handoff section
143
+ :status: accepted
144
+ :satisfies: REQ-HANDOFF
145
+
146
+ The handoff is the body section whose heading line is `## Handoff` or `## Handoff (<timestamp>)`, with a timestamp as in [[DES-ISSUE-FILE]]. It runs to the next level 1 or 2 heading or to the end of the body. Headings inside fenced code blocks, as [[DES-LIFECYCLE]] defines them, are ignored: a fence opens only when indented by at most three columns more than the content of the list item holding it, or than the line start outside list items.
147
+
148
+ - **Writing.** `update --handoff TEXT|-` writes `## Handoff (<now>)`, a blank line and the text. It replaces an existing section in place, or appends the section after a blank line. Text that contains a level 1 or 2 heading outside a fenced code block is rejected, because it would end the section early, and so is text that leaves a fenced code block open, because it would carry the section past the next heading. `update --no-handoff` removes the section, together with the blank lines before it when it ends the body. Both fail when the body has more than one handoff section, which must then be fixed by hand. Otherwise, bytes outside the section are unchanged. Writing also fails, changing nothing, when the new body would not give back the note just written, for example because the body leaves a fenced code block open before it.
149
+ - **Reading.** In JSON, `show` adds `handoff` as `{written_at, text}`, or `null` without a section, and `list` adds `handoff_at`. A heading without a timestamp gives `written_at: null`. With several sections, reading uses the first. Human output shows the age of the note.
150
+ - **Guide.** The guide section on handoffs says: write a handoff only when the developer asks, while the conversation is still available, and overwrite rather than append. Record the commit, the branch and whether the working tree is clean; what is done; what is next; what is blocked or uncertain; approaches tried and rejected; and the files touched. Use plain bullets, not task items, and no diffs. Resume only when asked to continue: show the matching in-progress issue, asking the developer if several could match, and check the note against the repository before acting on it. On `done`, replace the handoff with `## Summary of Changes` and keep the rejected approaches.
151
+
152
+ `prime` and the MCP instructions never include handoff notes ([[ADR-HANDOFF-ON-ISSUE]]).
153
+ :::
154
+
155
+ ## Scenario
156
+
157
+ :::mara scenario SCN-AGENT-SESSION
158
+ :mid: 01M764FJ3ZRJ3Q9GY8PMXWG7PF
159
+ :title: An agent works through an issue
160
+ :status: accepted
161
+
162
+ A developer starts a coding-agent session in a repository that uses zban. The agent receives the zban guide through MCP instructions or a `zban prime` hook. Asked what to do next, it lists ready work and proposes the highest-priority issue. With the developer's agreement it sets the issue `in-progress`, reads its body and the documents it references, and does the work while checking off task items. On noticing an unrelated bug, it files a bug with `discovered_from` pointing at the current issue and carries on. At the end it appends a summary, sets the issue `done`, which archives it, and commits the code together with the changed issue files. A later session, or a different agent, can see what was done and pick up the bug.
163
+ :::
@@ -0,0 +1,159 @@
1
+ # Command line
2
+
3
+ `zban` is a single binary. Every command prints human-readable output by default
4
+ and one JSON document with `--json`. Run `zban <command> --help` for full options.
5
+
6
+ ## Common tasks
7
+
8
+ ```sh
9
+ zban init # create .zban/ here, with ID prefix zb
10
+ zban init --prefix web # ... or with your own prefix
11
+ zban create "Parse issue files" -t feature -p high --parent zb-9jra34
12
+ zban create "Crash on empty title" -t bug --discovered-from zb-n938cw --body - < notes.md
13
+ zban list --ready # what can be started now
14
+ zban list --status in-progress # what is being worked on
15
+ zban list --parent zb-9jra34 # direct children of an epic
16
+ zban list --type bug --tag storage --search "frontmatter"
17
+ zban list --ready --not-tag maintainer # ready work, without issues tagged maintainer
18
+ zban show zb-n938cw zb-2b3mf7 # full issues, including body and reverse relations
19
+ zban update zb-n938cw -s in-progress
20
+ zban update zb-n938cw --replace-old "- [ ] Preserve unknown keys" --replace-new "- [x] Preserve unknown keys"
21
+ zban update zb-n938cw --append "## Summary of Changes
22
+
23
+ Parser and writer implemented." -s done
24
+ zban update zb-n938cw --handoff - < handoff.md # replace the handoff note
25
+ zban check # report problems in .zban/
26
+ zban check --fix # move misplaced files, delete leftover temporary files
27
+ ```
28
+
29
+ `create`, `list` and `update` take `-s`, `-t` and `-p` as short forms of
30
+ `--status`, `--type` and `--priority`, so `zban list -t bug -p high` lists the
31
+ open high-priority bugs.
32
+
33
+ Global options are `--json` and `-C, --directory DIR`. zban finds its project by
34
+ searching upward from the current directory to the nearest `.zban/`. With
35
+ `-C DIR` it behaves as if started in `DIR`, so any directory inside a project
36
+ works:
37
+
38
+ ```sh
39
+ zban -C ../other-repo list --ready
40
+ ```
41
+
42
+ `zban init` inside an existing project creates a nested project, and commands
43
+ run at or below it then use the nested project only. `init` prints a note naming
44
+ the enclosing project, and returns its `.zban/` as `enclosing` with `--json`.
45
+
46
+ ## Errors
47
+
48
+ Exit status is 0 on success, 1 when an operation fails or `check` finds errors,
49
+ and 2 for invalid usage. With `--json`, a failure prints one object such as
50
+ `{"error": {"code": "unchecked_items", "message": "..."}}`. The codes are stable
51
+ and listed in [[DES-CLI]]; agents can branch on them, for
52
+ example retrying after `conflict`.
53
+
54
+ ## Requirements
55
+
56
+ :::mara requirement REQ-JSON-OUTPUT
57
+ :mid: 01M764FJ3ZR331SYJPBK6THY9V
58
+ :title: Give machine-readable results for every command
59
+ :status: accepted
60
+ :satisfies: NEED-FIND-NEXT
61
+ :satisfies: NEED-TRACK-PROGRESS
62
+
63
+ Every command except `mcp` accepts `--json` and then writes exactly one JSON document to standard output, with documented and stable field names. A failure produces `{"error": {"code": "...", "message": "..."}}` with a documented, stable code and a non-zero exit status. Without `--json`, output is formatted for humans.
64
+ :::
65
+
66
+ :::mara requirement REQ-LIST-FILTERS
67
+ :mid: 01M764FJ3Z8MJPVMEH31KKANCY
68
+ :title: Find issues by their fields
69
+ :status: accepted
70
+ :satisfies: NEED-FIND-NEXT
71
+ :satisfies: NEED-PROJECT-MEMORY
72
+
73
+ Listing filters by status, type, priority, tag, parent and readiness, excludes issues by tag, and searches title and body case-insensitively. The parent filter matches direct children only. Repeated values of one filter match any of them, and different filters must all match. The tag exclusion leaves out every issue that carries any of its tags, even one that the other filters, the tag filter included, select. A status, type, priority or tag value that no issue could carry is refused rather than matching nothing. Closed issues are excluded unless the request includes them or asks for a closed status. Showing accepts several IDs in one request.
74
+ :::
75
+
76
+ :::mara requirement REQ-BODY-EDITS
77
+ :mid: 01M764FJ3ZZC411PJMKE9WERPY
78
+ :title: Edit issue bodies precisely
79
+ :status: accepted
80
+ :satisfies: NEED-TRACK-PROGRESS
81
+
82
+ An update can replace the whole body, append text to it, and replace exact text that occurs exactly once, failing when the text is absent or ambiguous. Body edits and metadata changes in one request are applied all or nothing. Multi-line input can be read from standard input.
83
+ :::
84
+
85
+ :::mara requirement REQ-SURFACE-PARITY
86
+ :mid: 01M764FJ3ZGF33SBBZTSCZ1FTM
87
+ :title: Offer the same operations through CLI and MCP
88
+ :status: accepted
89
+ :satisfies: NEED-FIND-NEXT
90
+ :satisfies: NEED-TRACK-PROGRESS
91
+
92
+ The command line and the MCP server expose the same operations with the same validation, results and error codes. Neither invokes the other.
93
+ :::
94
+
95
+ ## Design
96
+
97
+ :::mara design DES-CLI
98
+ :mid: 01M764FJ3Z6N3M80E0PMQZXSD4
99
+ :title: Command set
100
+ :status: accepted
101
+ :satisfies: REQ-JSON-OUTPUT
102
+ :satisfies: REQ-LIST-FILTERS
103
+ :satisfies: REQ-BODY-EDITS
104
+
105
+ | Command | Arguments and options |
106
+ | --- | --- |
107
+ | `init` | `[--prefix P]` |
108
+ | `create <title>` | `-t TYPE`, `-s STATUS`, `-p PRIORITY`, `--tag T`…, `--parent ID`, `--blocked-by ID`…, `--related ID`…, `--discovered-from ID`, `--body TEXT\|-` |
109
+ | `list` | `-s, --status S`…, `-t, --type T`…, `-p, --priority P`…, `--tag T`…, `--not-tag T`…, `--parent ID` (direct children), `--ready`, `--search TEXT`, `--all` |
110
+ | `show <id>…` | — |
111
+ | `update <id>` | `-s`, `-t`, `-p`, `--title`, `--add-tag`/`--remove-tag`, `--parent ID`/`--no-parent`, `--add-blocked-by`/`--remove-blocked-by`, `--add-related`/`--remove-related`, `--discovered-from ID`/`--no-discovered-from`, `--body TEXT\|-`, `--append TEXT\|-`, `--replace-old TEXT --replace-new TEXT` (repeatable, applied in order), `--handoff TEXT\|-`/`--no-handoff` ([[DES-HANDOFF]]), `--force` |
112
+ | `delete <id>` | — |
113
+ | `check` | `--fix` ([[DES-CHECK]]) |
114
+ | `prime` | Prints the agent guide ([[DES-AGENT-GUIDE]]). Outside a project it prints nothing and exits 0, so global hooks are harmless. With `--json` it prints `{"guide": "..."}`, with `null` outside a project. |
115
+ | `mcp` | Serves MCP over stdio ([[DES-MCP-TOOLS]]). Takes no `--json`. |
116
+
117
+ In `create`, `list` and `update`, `-s`, `-t` and `-p` are short for `--status`, `--type` and `--priority`. `list --not-tag` leaves out every issue that carries any of its tags, also when the issue carries a tag of `--tag`, and composes with every other filter. The values of `list --tag` and `--not-tag` must be valid tags ([[DES-ISSUE-FILE]]), or the request fails with `invalid_value`, as an unknown status, type or priority does: no readable issue can carry an invalid tag, so such a filter would silently select nothing, or exclude nothing. `list --parent` resolves its ID as `show` does, so an ID that is malformed or names no issue fails with `not_found`, and one naming two files or an unreadable file fails with `ambiguous_id` or `unreadable`. Every command accepts the global option `-C, --directory DIR` ([[DES-PROJECT-LAYOUT]]), and every command except `mcp` accepts `--json`. At most one option per request reads standard input. An update applies its body edits in the order `--body`, the replacements, `--append`, then the handoff.
118
+
119
+ Exit status is 0 on success, 1 when an operation fails or `check` finds errors, and 2 for invalid usage. Every command except `init`, `prime` and `mcp` fails with `project_not_found` when no project is found; `mcp` starts anyway and fails each tool call instead ([[DES-MCP-TOOLS]]). The error codes are:
120
+
121
+ | Code | When |
122
+ | --- | --- |
123
+ | `usage` | Unknown, missing or conflicting arguments, more than one input from standard input, or a relative MCP `directory`. Exit status 2. |
124
+ | `project_not_found` | No project is found ([[DES-PROJECT-LAYOUT]]) |
125
+ | `project_exists` | `init` where `.zban/` already exists |
126
+ | `invalid_config` | The configuration is malformed or has an unknown `format_version` |
127
+ | `not_found` | A named issue does not exist. For an ID in this project's format, with its prefix, the message adds a fixed hint that the issue may exist on another branch or worktree; zban does not look there ([[REQ-NO-GIT]]). Any other value, including an ID with another project's prefix, gets a message showing this project's ID format instead. |
128
+ | `ambiguous_id` | A named ID matches a file in both `.zban/` and `.zban/archive/` |
129
+ | `unreadable` | The operation needs an issue file that cannot be read ([[REQ-DAMAGED-DATA]]) |
130
+ | `invalid_value` | A value breaks [[DES-ISSUE-FILE]] or [[DES-PROJECT-LAYOUT]], such as an unknown status, a multi-line title or an invalid prefix |
131
+ | `invalid_reference` | A relation names an unknown issue or the issue itself |
132
+ | `cycle` | A relation would create a cycle or a blocker on an ancestor ([[REQ-RELATIONS]]) |
133
+ | `unchecked_items` | `done` with unchecked task items, without force |
134
+ | `open_children` | `done` or `cancelled` with open children, without force |
135
+ | `referenced` | Deleting an issue that another issue references |
136
+ | `text_not_found` | A replacement's old text does not occur in the body |
137
+ | `text_ambiguous` | A replacement's old text occurs more than once |
138
+ | `invalid_handoff` | Handoff text contains a level 1 or 2 heading or leaves a fenced code block open, the written note would not read back, or the body has several handoff sections ([[DES-HANDOFF]]) |
139
+ | `conflict` | The file changed between reading and writing ([[REQ-NO-LOST-UPDATES]]) |
140
+ | `io` | Any other file-system failure |
141
+
142
+ In JSON, an issue has `id`, `title`, `status`, `type`, `priority`, `tags`, `parent`, `blocked_by`, `related`, `discovered_from`, `created_at`, `closed_at`, `path` (the absolute path of the file), `checklist` (`{checked, total}`), `child_counts` (`{closed, total}`, counting the direct children only, the same issues as `show`'s `children` and `list --all --parent`; a child counts as closed when its status is `done` or `cancelled`, whether or not its file is archived), `ready` and `not_ready` (the reasons from [[DES-READINESS]]). A child whose file is unreadable or whose ID names two files is left out of `children` and of `child_counts` and is reported as a warning ([[REQ-DAMAGED-DATA]]); until it is repaired, closing the parent can still fail with `open_children`, because that check counts such a child as open when a readable copy of it is open. `show` adds `body`, `handoff` and the reverse relations `children`, `blocks`, `related_from` and `discovered` as lists of IDs. `list` adds `handoff_at`. `list` returns `{"issues": [...], "warnings": [...]}` without bodies, in the order defined by [[DES-READINESS]], and `show` returns `{"issues": [...], "warnings": [...]}` in the order requested. Each warning is `{code, path, message}` with a code from [[DES-CHECK]], for a file skipped as unreadable or an ID present twice; human output prints warnings to standard error. Mutations return the resulting issue, and `delete` returns the issue as it was. Human output of `list` and `show` shows checklist progress when the issue has task items and child progress when it has children: on a `list` line `[checked/total]` comes first, then `children closed/total closed`, then the handoff age, and `show` adds the lines `checklist: checked/total checked` and `child_counts: closed/total closed`. `init` returns `{path, prefix, enclosing}`, where `path` is the absolute path of the new `.zban/` and `enclosing` is the absolute path of the enclosing project's `.zban/` ([[DES-PROJECT-LAYOUT]]), or `null` when there is none; human output then adds a note naming the enclosing project. `check` returns `{"findings": [{severity, code, path, message}]}`, where `path` is the absolute path of the file.
143
+ :::
144
+
145
+ :::mara design DES-SHARED-CORE
146
+ :mid: 01M764FJ3ZNZPGXYJ4CS2QFHPK
147
+ :title: One core library with thin adapters
148
+ :status: accepted
149
+ :satisfies: REQ-SURFACE-PARITY
150
+ :satisfies: REQ-PRESERVE-CONTENT
151
+ :satisfies: REQ-NO-LOST-UPDATES
152
+ :satisfies: REQ-DAMAGED-DATA
153
+
154
+ The crate has a library holding the issue model, file store and operations (`init`, `create`, `list`, `show`, `update`, `delete`, `check` and `guide`), plus the `zban` binary. The CLI and MCP adapters only convert arguments into operation requests and operation results into output. Every operation reads the files fresh. There is no cache and no background process, so hand edits and branch switches are visible immediately, including to a running MCP server. Mutations validate the whole request against the loaded project before writing anything.
155
+
156
+ Loading never stops at a bad file. A file that cannot be parsed, or whose known keys break [[DES-ISSUE-FILE]], is kept as unreadable: it takes no part in listings, and readiness treats it as described in [[DES-READINESS]]. A mutation validates the values the request sets and the relations they form, not problems elsewhere in the project. It fails with `unreadable` when the issue it changes, or an issue its new relations name, is unreadable. Showing fails the same way for a named issue that is unreadable. Both fail with `ambiguous_id` when a named ID has two files.
157
+
158
+ Each mutation keeps the bytes of every issue file it read. Just before replacing or deleting a file, it reads the file again and fails with `conflict` if the bytes differ. Every step that replaces, moves or deletes an issue file holds an exclusive advisory lock on the `.zban/` directory, taken with `File::lock` on a handle of the directory, from that comparison until the rename or deletion is done ([[ADR-WRITE-LOCK]]). Loading the project holds the same lock, taken shared with `File::lock_shared`, from listing `.zban/` and `.zban/archive/` until it has read the bytes of every issue file listed, and parses them after releasing it. A load therefore never overlaps such a step of another zban process: it finds each issue file at the path and with the bytes that the last such step left, and loads do not wait for each other. `check` lists the temporary files under the shared lock too. A step that holds the exclusive lock never loads the project or lists the directories, because locks on two handles conflict even within one process. When taking the lock fails because the file system has no advisory locks (`Unsupported`, or the raw errors `ENOSYS`, `ENOTSUP` and `EOPNOTSUPP`), the step or load runs without it; any other failure to take the lock fails with `io`. Reading the project and writing the temporary file happen before the exclusive lock is taken, and no lock file is created. Two zban processes therefore never both pass the comparison for one file. Editors and Git do not take the lock, so a change they save in the instant between the comparison and the rename can still be lost, and a load that overlaps a rename or move of theirs can still leave a file out. `init` and `create` hard-link the temporary file to its new name, which fails rather than replacing an existing file, so there a create never replaces one. When linking fails because the file system has no hard links, with `EPERM` on Linux or as unsupported in the sense used for the lock above, the step instead holds the exclusive lock while it checks that the name is unused, for an issue in both `.zban/` and `.zban/archive/`, and renames the temporary file to it ([[ADR-CREATE-WITHOUT-HARD-LINKS]]); any other failure to link fails with `io`. A create then never replaces a file that exists at the check or that another zban process creates, but an editor, Git, or a zban process on a file system that has no advisory locks either can still create the name between the check and the rename.
159
+ :::