@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,294 @@
|
|
|
1
|
+
# Decisions and risks
|
|
2
|
+
|
|
3
|
+
The choices behind zban and the risks we knowingly carry.
|
|
4
|
+
|
|
5
|
+
## Decisions
|
|
6
|
+
|
|
7
|
+
:::mara decision ADR-FILES-IN-REPO
|
|
8
|
+
:mid: 01M764FJ3Z76SNWB69FYE8BQRG
|
|
9
|
+
:title: Store issues as plain files in the repository
|
|
10
|
+
:status: accepted
|
|
11
|
+
:justifies: REQ-ONE-FILE
|
|
12
|
+
:justifies: DES-SHARED-CORE
|
|
13
|
+
|
|
14
|
+
Agents work in a checkout. External trackers need network access and credentials, and they drift from the branch being worked on. A side database adds locking and recovery problems. zban stores issues only as Markdown files under `.zban/`, with no database, cache or daemon. As a consequence, issue state is local to each branch, and every command reads all issue files. That is fast enough up to several thousand issues.
|
|
15
|
+
:::
|
|
16
|
+
|
|
17
|
+
:::mara decision ADR-SMALL-SCOPE
|
|
18
|
+
:mid: 01M764FJ3ZAAC9D0V2C1WQY9CB
|
|
19
|
+
:title: Limit v1 to the issue loop
|
|
20
|
+
:status: accepted
|
|
21
|
+
:justifies: REQ-NO-GIT
|
|
22
|
+
:justifies: DES-CLI
|
|
23
|
+
|
|
24
|
+
Issue trackers for agents tend to grow into platforms: query engines, terminal and web UIs, agent chat, worktree and terminal management, claims, named sessions and handoff machinery. Each addition looks reasonable, but together they make the tool hard to reason about. zban v1 contains issue files, relations, readiness, lifecycle and archive, handoff notes on issues, the check command, the CLI, the MCP server and the agent guide.
|
|
25
|
+
|
|
26
|
+
Excluded are claims and locking, state shared across worktrees, running Git, running agents or managing worktrees, terminal and web UIs, a query language, templates, custom fields, configurable vocabulary, manual ordering, assignees and time tracking. Adding a capability requires a recorded need and a decision first, not just precedent in another tool.
|
|
27
|
+
:::
|
|
28
|
+
|
|
29
|
+
:::mara decision ADR-NO-CLAIMS
|
|
30
|
+
:mid: 01M764FJ3ZDTFAZ4GG9A8BJ03S
|
|
31
|
+
:title: Rely on the in-progress status instead of claims
|
|
32
|
+
:status: accepted
|
|
33
|
+
:justifies: DES-READINESS
|
|
34
|
+
:accepts: RISK-DUPLICATE-WORK
|
|
35
|
+
|
|
36
|
+
Agents in different worktrees cannot see each other's status changes until their branches merge. Lock files shared through the Git common directory can coordinate them, but at great cost in complexity. zban v1 has no claims and no assignee field. `in-progress` is a durable status in the file, and whoever runs parallel agents (a human or an orchestrator) decides who works on what. If claims prove necessary later, they will be an additional ephemeral layer that leaves the file format and the `in-progress` status unchanged.
|
|
37
|
+
:::
|
|
38
|
+
|
|
39
|
+
:::mara decision ADR-FIXED-VOCABULARY
|
|
40
|
+
:mid: 01M764FJ3ZYNNKFADFY3G06GRD
|
|
41
|
+
:title: Hardcode statuses, types and priorities
|
|
42
|
+
:status: accepted
|
|
43
|
+
:justifies: REQ-FIXED-VOCABULARY
|
|
44
|
+
|
|
45
|
+
A configurable vocabulary forces every tool and agent to read configuration first, and it makes the agent guide differ per project. zban fixes all three sets. `draft` keeps unrefined ideas, and work parked on purpose, out of ready work together with everything under them ([[ADR-DRAFT-HOLDS-DESCENDANTS]]). `cancelled` keeps abandoned work apart from delivered work. There is no milestone type. Nested epics, ordered with `blocked_by`, cover phases inside larger work, and a tag groups a release that cuts across epics. Priorities are five named levels because names read better than numbers in prompts.
|
|
46
|
+
:::
|
|
47
|
+
|
|
48
|
+
:::mara decision ADR-RANDOM-IDS
|
|
49
|
+
:mid: 01M764FJ3ZADMY1PJZ654H5PHK
|
|
50
|
+
:title: Use short random IDs with a project prefix
|
|
51
|
+
:status: accepted
|
|
52
|
+
:justifies: DES-ISSUE-ID
|
|
53
|
+
|
|
54
|
+
Sequential numbers collide when parallel branches create issues, and they need a shared counter. UUIDs never collide but are noisy, and the short forms people cite are only prefixes, which can become ambiguous. Four random base36 characters, about 1.7 million values, leave a noticeable chance of collisions across branches in a long-lived project. zban uses its prefix plus six random Crockford base32 characters, about a billion values per prefix, and `zban check` detects any duplicate. IDs carry no order; `created_at` provides it.
|
|
55
|
+
|
|
56
|
+
The filename is the bare ID, without a slug of the title. A slug goes stale when the title changes, or causes rename churn if it follows the title. Without one, an agent opens an issue straight from its ID, two issues that share an ID land on the same path so Git reports the collision when merging, and there are no slugging rules to specify. Listing titles is left to `zban list`.
|
|
57
|
+
:::
|
|
58
|
+
|
|
59
|
+
:::mara decision ADR-AUTO-ARCHIVE
|
|
60
|
+
:mid: 01M764FJ3ZWDY1N7FRADERZ3XJ
|
|
61
|
+
:title: Archive when closing rather than on command
|
|
62
|
+
:status: accepted
|
|
63
|
+
:justifies: REQ-AUTO-ARCHIVE
|
|
64
|
+
:justifies: DES-LIFECYCLE
|
|
65
|
+
|
|
66
|
+
Archiving in bulk on an explicit command depends on someone running it, and agents may run it only when asked, so closed issues pile up among active ones. zban moves a file into `.zban/archive/` as soon as the issue closes, and back when it reopens. The status stays authoritative, and `zban check --fix` repairs a misplaced file. The costs: a close shows up as a rename plus an edit in diffs, and an edit on one branch combined with a close on another merges as a rename/modify, which Git normally resolves.
|
|
67
|
+
:::
|
|
68
|
+
|
|
69
|
+
:::mara decision ADR-MERGE-FRIENDLY-FORMAT
|
|
70
|
+
:mid: 01M764FJ3Z8SW2MT7EAP58RF8R
|
|
71
|
+
:title: Shape the file format for Git merges
|
|
72
|
+
:status: accepted
|
|
73
|
+
:justifies: DES-ISSUE-FILE
|
|
74
|
+
:justifies: REQ-RELATIONS
|
|
75
|
+
|
|
76
|
+
Issue files are merged by Git, so the format avoids needless conflicts and drift. Each relation is stored once, on one issue. Storing both directions, such as `blocking` and `blocked_by`, lets the two disagree. There is no `updated_at`, which would conflict on every concurrent edit; Git history already records changes. Lists hold one item per line, the key order is fixed, and the ID exists only in the filename. Relations hold bare IDs, not Markdown links: a link would need rewriting in every referring issue whenever its target is archived, so closing one issue would touch others and conflict with their edits on other branches. Editors find an issue by its ID because the ID is the filename.
|
|
77
|
+
:::
|
|
78
|
+
|
|
79
|
+
:::mara decision ADR-HANDOFF-ON-ISSUE
|
|
80
|
+
:mid: 01M777QQGMRG4N17FAT4EGF628
|
|
81
|
+
:title: Keep handoffs as notes on issues, written and read on request
|
|
82
|
+
:status: accepted
|
|
83
|
+
:justifies: REQ-HANDOFF
|
|
84
|
+
:justifies: DES-HANDOFF
|
|
85
|
+
|
|
86
|
+
Agents lose context between sessions, and a short note written while the conversation is still available carries it best. Notes generated automatically when a session ends come too late: the model is gone and session-end hooks get little time. Stop hooks that force a note after every turn are noisy. So agents write a note only when the developer asks.
|
|
87
|
+
|
|
88
|
+
The note lives in the issue body, overwritten in place, rather than in a separate handoff file or entity. The issue is already the record that outlives a session, a note there travels with the branch, and Git keeps earlier versions. A body section stays readable in Markdown previews and keeps the frontmatter small. zban stamps only the time, because it cannot read Git; the agent records the commit and branch.
|
|
89
|
+
|
|
90
|
+
zban does not deliver notes into new sessions. Notes belong to issues, and zban cannot tell which issue a session is about. Including every in-progress note in `prime` or the MCP instructions would cost every session and show other people's work after merges. Choosing by the current worktree or branch would need Git access or worktree tracking, which [[REQ-NO-GIT]] and [[ADR-SMALL-SCOPE]] exclude. The developer asks the agent to continue, and the agent shows the issue.
|
|
91
|
+
:::
|
|
92
|
+
|
|
93
|
+
:::mara decision ADR-CLI-AND-MCP
|
|
94
|
+
:mid: 01M764FJ3Z27M3C4E700KAKEE6
|
|
95
|
+
:title: Offer CLI and MCP over one core, plus prime
|
|
96
|
+
:status: accepted
|
|
97
|
+
:justifies: REQ-SURFACE-PARITY
|
|
98
|
+
:justifies: REQ-AGENT-GUIDE
|
|
99
|
+
|
|
100
|
+
MCP gives agents typed tools and server instructions in clients that support them. The CLI works everywhere: in shells, CI and agents without MCP. v1 ships both over one shared core. The agent guide is delivered as MCP server instructions, and through `zban prime` for agents that use only the CLI or whose clients ignore server instructions.
|
|
101
|
+
:::
|
|
102
|
+
|
|
103
|
+
:::mara decision ADR-RUST-BINARY
|
|
104
|
+
:mid: 01M764FJ3ZRYT7TB8RKNHPFM8K
|
|
105
|
+
:title: Ship one Rust binary through GitHub Releases, dual-licensed
|
|
106
|
+
:status: accepted
|
|
107
|
+
:justifies: DES-SHARED-CORE
|
|
108
|
+
|
|
109
|
+
zban is written in Rust and ships as one self-contained binary. It is distributed through GitHub Releases and npm ([[ADR-NPM-DISTRIBUTION]]): each GitHub release attaches prebuilt binaries and a SHA-256 checksum file, each npm release publishes `@convesoft/zban` with four per-platform binary packages, and any release tag can be built from source with `cargo install --locked --git https://github.com/convesoft/zban --tag vX.Y.Z`. zban is not published to crates.io, and its manifest sets `publish = false` so that nobody publishes it by accident: zban is an application, not a library other crates depend on. The license is `MIT OR Apache-2.0`.
|
|
110
|
+
|
|
111
|
+
v1 supports Linux and macOS on x86_64 and aarch64. Windows is deferred until there is a need for it, because it needs its own handling of atomic file replacement, CRLF line endings and paths.
|
|
112
|
+
|
|
113
|
+
Release binaries are built for `x86_64-unknown-linux-musl`, `aarch64-unknown-linux-musl`, `x86_64-apple-darwin` and `aarch64-apple-darwin`. On Linux, musl is chosen over glibc because the binary is then statically linked: one file runs on every distribution, whatever its glibc version, including musl-based ones such as Alpine. A glibc binary would instead have to be built against the oldest glibc it should support. musl's slower memory allocator does not matter to a short-lived command that reads small files.
|
|
114
|
+
|
|
115
|
+
A release is cut from `main` (or a `release/*` branch) after bumping `Cargo.toml` and `Cargo.lock` with `pnpm nx release version`, by dispatching `.github/workflows/release.yml` ([[ADR-NPM-DISTRIBUTION]]). The workflow runs the test suite on the commit being released, on each platform whose binary it can run, before publishing to npm, tagging `vX.Y.Z` and creating the GitHub Release. A release then ships only code that has landed and passes its tests.
|
|
116
|
+
|
|
117
|
+
CI and the release workflow build with one exact Rust version, pinned in `rust-toolchain.toml` together with the `rustfmt` and `clippy` components and the four release targets. A new Rust release then cannot fail `main` through a changed format or lint while the repository stays the same, and a release tag can be rebuilt with the compiler that built it. The pin is bumped deliberately, in a pull request of its own that also carries whatever the new version requires, such as reformatting. `rust-version` in `Cargo.toml` separately declares the oldest Rust that builds zban from source, and a CI job runs the test suite with that version, read from the manifest, so that the declared minimum stays true. Following the floating `stable` channel was rejected because Rust 1.100.0 failed `main` through a rustfmt change alone, and because release builds could not be reproduced.
|
|
118
|
+
|
|
119
|
+
Each release archive holds the binary, the README, zban's two license files and `THIRD-PARTY-LICENSES`, which gives the license texts of the crates in `Cargo.lock` that the build for its platform uses and names the crates under each. Most of these crates are licensed under MIT or Apache-2.0, which ask anyone who redistributes them in binary form to pass on their notices. The release workflow writes the file on each build with `cargo-about`, installed at a pinned version with `cargo install --locked`, from `about.toml` and the template `about.hbs` in the repository. `about.toml` lists the licenses the crates may use, and the license files to quote for crates whose licensing `cargo-about` cannot read on its own. A crate under another license, or a quoted file whose checksum changed, fails the release until someone reviews it. `cargo-about` is a release tool only: it is not a dependency in `Cargo.toml`, and contributors never run it. The file is plain text, like the rest of the archive, so it reads in a terminal. A hand-maintained notices file was rejected because nothing would keep it in step with `Cargo.lock`, and pointing at the source tree because the archives would still lack the notices.
|
|
120
|
+
:::
|
|
121
|
+
|
|
122
|
+
:::mara decision ADR-NPM-DISTRIBUTION
|
|
123
|
+
:mid: 01M81JCJFBWY36PNAJD0Y3B125
|
|
124
|
+
:title: Distribute zban on npm as platform binary packages and adopt Nx with nx-rust for releases
|
|
125
|
+
:status: accepted
|
|
126
|
+
:justifies: DES-SHARED-CORE
|
|
127
|
+
|
|
128
|
+
[[ADR-RUST-BINARY]] limited v1 distribution to GitHub Releases and deferred package-manager wrappers pending a recorded decision. In practice, developers and coding-agent setups benefit from installing or running zban through npm and `npx` without manually fetching release archives or installing a Rust toolchain ([[NEED-NPM-DISTRIBUTION]]).
|
|
129
|
+
|
|
130
|
+
zban is therefore distributed on npm alongside GitHub Releases as five packages under the `@convesoft` scope:
|
|
131
|
+
|
|
132
|
+
- `@convesoft/zban`: the main dispatcher package containing `bin/zban.cjs`, the `docs/` folder, `README.md`, `LICENSE-MIT`, `LICENSE-APACHE` and `optionalDependencies` pinning all four platform packages to the exact release version.
|
|
133
|
+
- `@convesoft/zban-linux-x64` (`x86_64-unknown-linux-musl`, `os: ["linux"]`, `cpu: ["x64"]`),
|
|
134
|
+
- `@convesoft/zban-linux-arm64` (`aarch64-unknown-linux-musl`, `os: ["linux"]`, `cpu: ["arm64"]`),
|
|
135
|
+
- `@convesoft/zban-darwin-arm64` (`aarch64-apple-darwin`, `os: ["darwin"]`, `cpu: ["arm64"]`), and
|
|
136
|
+
- `@convesoft/zban-darwin-x64` (`x86_64-apple-darwin`, `os: ["darwin"]`, `cpu: ["x64"]`).
|
|
137
|
+
|
|
138
|
+
Each platform package holds `bin/zban`, `README.md`, `LICENSE-MIT`, `LICENSE-APACHE` and `THIRD-PARTY-LICENSES`. Because the Linux binaries are statically linked against musl ([[ADR-RUST-BINARY]]), the Linux packages run on both glibc and musl distributions and set no `libc` restriction.
|
|
139
|
+
|
|
140
|
+
`@convesoft/zban` carries every file of the repository's `docs/` folder as it is, in a `docs/` folder beside its `README.md`, so that coding agents and developers read, under `node_modules/@convesoft/zban/docs/`, the user guide and specification of the version they installed rather than those of `main`. The maintainer decided this on 22 November 2026, following the pattern that `@convesoft/nx-rust` adopted for its own documentation. Only the main package carries the pages: every installation gets it, so copies in the four platform packages would add nothing, and the release archives stay as [[ADR-RUST-BINARY]] describes them. `scripts/package-npm.mjs` copies the folder whole, so a new page ships without a change to the script, and the release workflow fails if the packed `@convesoft/zban` lacks `docs/index.mara.md` or any other file of `docs/`. The README's links into `docs/` resolve inside the installed package, so a sentence in the README is the only pointer to the bundled pages: no separate pointer file is added, because the `PLUGIN.md` of `@convesoft/nx-rust` follows an Nx plugin convention that has no counterpart for zban, and the agent guide does not change.
|
|
141
|
+
|
|
142
|
+
Three consequences are accepted. The pages ship as they are, so a relative link that leaves `docs/`, such as the documentation index's link to `.zban/`, does not resolve inside the package, nor do the README's links to `.zban/`, `.mara/` and `AGENTS.md`. The README in the platform packages and the release archives links into a `docs/` folder that they do not carry. And `@convesoft/zban` grows from about 21 kB to about 133 kB unpacked, 46 kB packed, as measured when this was decided. A pull request that changes only the pages does not run the release workflow, because packing does not depend on their content; the check runs on every release and on every pull request that changes the packaging.
|
|
143
|
+
|
|
144
|
+
The repository adopts Nx with `@convesoft/nx-rust` at the root (`package.json`, `pnpm-lock.yaml`, `nx.json`) for release versioning and changelog generation, while keeping `Cargo.toml` as the single source of truth for the version:
|
|
145
|
+
|
|
146
|
+
- `pnpm nx release version` bumps `Cargo.toml` and `Cargo.lock` from Conventional Commits (or an explicit specifier) in a release pull request so that `zban --version`, `cargo install --locked --git ... --tag vX.Y.Z`, GitHub Release archives and all five npm packages stay on one version.
|
|
147
|
+
- `scripts/package-npm.mjs` reads metadata and the version directly from `Cargo.toml` to assemble the main and platform npm packages.
|
|
148
|
+
- `.github/workflows/release.yml` runs via `workflow_dispatch` (with `dist_tag` and `dry_run`, defaulting to `dry_run: true`), builds and tests all four targets, generates `THIRD-PARTY-LICENSES`, packs both the `.tar.gz` archives and the npm `.tgz` packages, and runs a local pre-publish npm install smoke test on each runner.
|
|
149
|
+
- Publishing runs in the `npm` GitHub Environment via npm OIDC Trusted Publishing (`id-token: write`, `--provenance`, no long-lived npm token): it publishes the four platform packages first (skipping any whose registry `dist.shasum` already matches), waits until `npm view` reports all four, publishes `@convesoft/zban` last, runs an `npx` smoke test, runs `pnpm nx release changelog` to create the `vX.Y.Z` tag and GitHub Release from Conventional Commits, and uploads the four `.tar.gz` archives and `SHA256SUMS` to that release.
|
|
150
|
+
|
|
151
|
+
Rejected alternatives:
|
|
152
|
+
|
|
153
|
+
- **A single npm package with a `postinstall` script downloading from GitHub Releases.** Breaks when `--ignore-scripts` is enabled, needs network access during installation and reimplements checksum verification.
|
|
154
|
+
- **Tag-only version stamping in CI without bumping `Cargo.toml` in git.** Leaves the tagged commit with a stale `Cargo.toml` version, breaking `cargo install --locked --git ... --tag vX.Y.Z`.
|
|
155
|
+
- **Publishing to crates.io instead of npm.** Does not help Node-based agent setups (`npx`) without a Rust toolchain, and zban remains an application rather than a library crate.
|
|
156
|
+
|
|
157
|
+
Costs accepted: the repository carries a minimal Node/pnpm/Nx root configuration alongside the Rust crate, and all five `@convesoft/zban*` packages require one-time Trusted Publisher configuration on npmjs.com bound to `convesoft/zban`, `release.yml` and the `npm` environment.
|
|
158
|
+
:::
|
|
159
|
+
|
|
160
|
+
:::mara decision ADR-DEPENDENCIES
|
|
161
|
+
:mid: 01M779N7PPXZEFMF6M942DMS6H
|
|
162
|
+
:title: Build on established crates
|
|
163
|
+
:status: accepted
|
|
164
|
+
:justifies: DES-SHARED-CORE
|
|
165
|
+
:justifies: DES-MCP-TOOLS
|
|
166
|
+
:justifies: DES-ISSUE-FILE
|
|
167
|
+
|
|
168
|
+
zban needs argument parsing, JSON, a YAML parser for issue headers, an MCP server and graph checks over relations. Writing these by hand keeps the dependency tree small, but spends effort on parser and protocol details that maintained crates already handle, and hand-written protocol code tends to lag behind MCP revisions. zban builds on established crates: `clap` for arguments, `serde` and `serde_json` for JSON, `saphyr-parser` for YAML, whose parse events expose enough detail to reject anchors, aliases, tags and duplicate keys, the official MCP Rust SDK `rmcp` for the server, `petgraph` for cycle and reachability checks over `parent` and `blocked_by`, and `getrandom` for IDs.
|
|
169
|
+
|
|
170
|
+
The YAML crate parses header values only. A thin text layer splits the header into top-level entries, so unknown keys are kept verbatim and known keys are written in the canonical form of [[DES-ISSUE-FILE]] without a generic YAML serializer. The two keys of `config.toml` are read by a small parser in zban rather than a TOML crate. `rmcp` needs the `tokio` runtime; only `zban mcp` starts it, and the core library stays synchronous. The costs are a larger binary and dependency tree. Adding a runtime dependency beyond these needs a recorded decision.
|
|
171
|
+
|
|
172
|
+
The tests have one dependency of their own, `tempfile`, which is not built into the binary. Each test builds a fresh fixture project in a `TempDir`: a directory with a random name under the system's temporary directory, owned by the test and deleted when it ends. No two tests share a directory, even under a runner that starts one process per test, and no fixture lies inside this repository, whose own `.zban/` a test would otherwise find.
|
|
173
|
+
:::
|
|
174
|
+
|
|
175
|
+
:::mara decision ADR-NO-CASCADE
|
|
176
|
+
:mid: 01M76XFGSJ81ZR60CGYEMESP5K
|
|
177
|
+
:title: Refuse to close unfinished work rather than cascade
|
|
178
|
+
:status: accepted
|
|
179
|
+
:justifies: REQ-CLOSE-CHECKLIST
|
|
180
|
+
:justifies: DES-LIFECYCLE
|
|
181
|
+
|
|
182
|
+
Closing an issue while its checklist or children are unfinished hides that work. Open children of a closed parent silently drop out of the ready list ([[DES-READINESS]]). Cascading the close to the children would avoid that, but one command would then rewrite many files, could stop part-way, and would give every child the parent's reason, although some may be finished, moved elsewhere or still wanted. zban refuses such a close unless it is forced, and it never closes another issue implicitly. A forced close leaves the open children in place, and `zban check` warns about them. Closing `done` and `cancelled` is treated the same way; only unchecked task items are specific to `done`.
|
|
183
|
+
:::
|
|
184
|
+
|
|
185
|
+
:::mara decision ADR-DRAFT-HOLDS-DESCENDANTS
|
|
186
|
+
:mid: 01M81NANBTX4F8FH8A3NVBPCTA
|
|
187
|
+
:title: Let a draft ancestor hold back its descendants
|
|
188
|
+
:status: accepted
|
|
189
|
+
:justifies: DES-READINESS
|
|
190
|
+
:justifies: DES-AGENT-GUIDE
|
|
191
|
+
|
|
192
|
+
`draft` keeps an issue out of ready work ([[ADR-FIXED-VOCABULARY]]), but zban 0.1.0 still offered its `todo` descendants: only closed or blocked ancestors held an issue back. Projects plan an epic and refine its children as `todo` before the epic should start, and they keep backlog and work only a human can do away from agents. Under autonomous orchestrators that pick from the ready list, the children of such planned epics were dispatched as soon as they were filed, and every orchestrator prompt had to filter parked and human-only work out by tag and priority conventions, such as `backlog`, `deferred` or `maintainer`, which zban neither defines nor checks.
|
|
193
|
+
|
|
194
|
+
The maintainer decided that a `draft` ancestor holds back every descendant, as a closed or blocked one does, and zban reports `ancestor_draft:<id>` for each `draft` ancestor ([[DES-READINESS]]). Setting one issue to `draft` parks its whole subtree: a planned epic stays `draft` and leaves `draft` when its work may start. The agent guide tells agents to park planned epics, backlog and human-only work as `draft` ([[DES-AGENT-GUIDE]]). An ancestor's status `in-progress` still holds nothing back by itself, because its children carry its work; like any open ancestor, it holds its descendants back while it has an open blocker.
|
|
195
|
+
|
|
196
|
+
Rejected alternatives:
|
|
197
|
+
|
|
198
|
+
- **Tag or priority conventions.** zban stays unchanged, but each project and orchestrator invents its own, and the ready list stays wrong for every agent that does not know them.
|
|
199
|
+
- **A new status for parked work.** It would tell unrefined work apart from work held back on purpose, but it enlarges the fixed vocabulary for a distinction readiness does not need.
|
|
200
|
+
- **Setting each child to `draft`.** It works without a change, but each child has to be promoted when the epic starts, and a `todo` child filed later is offered at once.
|
|
201
|
+
|
|
202
|
+
The costs: a refined child under a `draft` epic waits until the epic becomes `todo`, and after upgrading, `todo` issues under an existing `draft` leave the ready list. Their `not_ready` names the `draft` ancestor.
|
|
203
|
+
:::
|
|
204
|
+
|
|
205
|
+
:::mara decision ADR-WRITE-LOCK
|
|
206
|
+
:mid: 01M77YZD0BXR4H9NYMR7CFMW6R
|
|
207
|
+
:title: Lock the project directory only around each write and read
|
|
208
|
+
:status: accepted
|
|
209
|
+
:justifies: DES-SHARED-CORE
|
|
210
|
+
|
|
211
|
+
Comparing a file's bytes just before renaming over it leaves a window between the comparison and the rename. The v0.1.0 review saw two `zban update` runs on one issue both pass the comparison, and the later rename dropped the earlier change while both reported success. zban therefore holds an exclusive advisory lock on the `.zban/` directory from each such comparison until the rename or deletion that follows, and while it moves a file between `.zban/` and the archive. The standard library's `File::lock` provides it on Linux and macOS without another dependency; it needs Rust 1.89, which the manifest declares as `rust-version`.
|
|
212
|
+
|
|
213
|
+
Reads take the same lock, shared, from listing `.zban/` and `.zban/archive/` until they have read the bytes of every issue file listed, and parse the files after releasing it. POSIX leaves it unspecified whether a directory listing returns an entry that is renamed while the listing runs, and on btrfs a listing that overlapped a rename over an issue file left that issue out: `show` and `update` failed with `not_found` for an issue that existed throughout, and a listing could also miss a referrer or an open child. Holding the lock only while listing was not enough: a close or reopen that moved a listed file into the other directory before it was read left the issue out, or kept it as unreadable, about once in 16,000 `show` runs while another process kept closing and reopening the issue. Under the lock, a read finds each file at the path and with the bytes that the last zban write left. Writes wait while a read lists the directories and reads the files, but not while it parses them, and reads never wait for each other. Looking for a listed file that has gone in the other directory was rejected, because the file can move back before that second look and it needs more code than holding the lock a little longer. Looking a named issue up by its path as well was rejected because it does not help listings, referrers or children, and listing again because no number of attempts guarantees a complete listing.
|
|
214
|
+
|
|
215
|
+
A lock file was rejected: a crash can leave it behind and it can be committed by accident, whereas the operating system releases a lock on the directory when the process ends, even when it is killed. Holding the lock for a whole command is not needed: the byte comparison already reports stale reads as `conflict`, and short locks keep other zban processes from waiting while a command parses the files and prepares its change.
|
|
216
|
+
|
|
217
|
+
The lock is not a claim: it covers one file operation or one read of the files, not an issue between commands, so the exclusion of claims and locking in [[ADR-SMALL-SCOPE]] stands. It coordinates zban processes that share one `.zban/` directory. Editors, Git and other worktrees do not take it. On a file system without advisory locks, taking the lock fails as unsupported, and zban then writes or reads without it, a write guarded by the byte comparison alone as before; any other failure to take the lock fails the command with `io`.
|
|
218
|
+
:::
|
|
219
|
+
|
|
220
|
+
:::mara decision ADR-CREATE-WITHOUT-HARD-LINKS
|
|
221
|
+
:mid: 01M785TJ0TQG6K5K6WJS3G8GBE
|
|
222
|
+
:title: Create issue files by renaming where hard links are unsupported
|
|
223
|
+
:status: accepted
|
|
224
|
+
:justifies: DES-SHARED-CORE
|
|
225
|
+
:justifies: REQ-NO-LOST-UPDATES
|
|
226
|
+
|
|
227
|
+
`init` and `create` write a temporary file and then hard-link it to its name, so that the write is atomic ([[REQ-PRESERVE-CONTENT]]) and a create fails rather than replacing an existing file. Some file systems have no hard links. On Linux, linking then fails with `EPERM`, which `link(2)` documents for a file system that "does not support the creation of hard links"; FAT and exFAT drives and many FUSE mounts are such file systems. On macOS, `linkat(2)` documents `ENOTSUP` for a file system that "does not support this call". With zban 0.1.0 on an `rclone mount` of a local directory, mounted by an ordinary user, `init` and every `create`, open or closed, failed with `io` and "Operation not permitted (os error 1)". `update`, closing, reopening and `delete`, which rename or remove files, worked, and so did advisory locks.
|
|
228
|
+
|
|
229
|
+
zban keeps the hard link. When linking fails with `EPERM` on Linux, or as unsupported (`Unsupported`, or the raw errors `ENOSYS`, `ENOTSUP` and `EOPNOTSUPP`, as for the lock of [[ADR-WRITE-LOCK]]), `init` and `create` instead take the exclusive lock, check that the name is unused, for an issue in both `.zban/` and the archive, and rename the temporary file to it, as closing and reopening already move a file. Any other failure to link fails with `io`. Writes stay atomic, and an interrupted create leaves only a temporary file. File systems with hard links keep the absolute guarantee that a create never replaces a file. On the others, no other zban process can take the name between the check and the rename, but a writer that does not take the lock can: an editor, Git, or zban on a file system that has no advisory locks either. It would have to create the same freshly drawn random ID, one of 2^30 values that neither directory held an instant before, in that instant. [[ADR-WRITE-LOCK]] accepts the same caveat for replacing and moving a file. Falling back on an `EPERM` with another cause is harmless: each such cause that can apply to a file zban has just created also makes the rename fail, so the command fails with `io` as before.
|
|
230
|
+
|
|
231
|
+
The rejected alternatives:
|
|
232
|
+
|
|
233
|
+
- **Keep hard links only.** Name the missing support in the `io` message and document that zban needs hard links. No promise changes, but zban cannot create issues on these file systems.
|
|
234
|
+
- **Create the issue file exclusively.** Open the issue's name with exclusive creation, then write and sync it. A create still never replaces a file, but an interrupted create leaves an empty or partial issue file, which breaks [[REQ-PRESERVE-CONTENT]]. `check` would report it as unreadable, and `check --fix` could not tell it from a damaged hand edit. A read during the write would see the partial file unless the write held the lock.
|
|
235
|
+
- **Rename without replacing.** `renameat2` with `RENAME_NOREPLACE` on Linux and `renamex_np` with `RENAME_EXCL` on macOS are atomic and never replace. The standard library offers neither, so they need a new dependency ([[ADR-DEPENDENCIES]]), and FUSE mounts support them only when their server does, so another fallback would still be needed.
|
|
236
|
+
- **Always check, then rename.** Dropping the hard link would remove one code path, but every file system would then carry the caveat above.
|
|
237
|
+
:::
|
|
238
|
+
|
|
239
|
+
## Risks
|
|
240
|
+
|
|
241
|
+
:::mara risk RISK-DUPLICATE-WORK
|
|
242
|
+
:mid: 01M764FJ3ZM69JRX3088WM98RP
|
|
243
|
+
:title: Parallel agents duplicate work
|
|
244
|
+
:status: accepted
|
|
245
|
+
:likelihood: possible
|
|
246
|
+
:consequence: moderate
|
|
247
|
+
:threatens: NEED-FIND-NEXT
|
|
248
|
+
|
|
249
|
+
Two agents on different branches may both see an issue as ready and start it, because `in-progress` on one branch is invisible on the other until merge. Two agents that find the same problem may likewise each file an issue for it, because an issue created on one branch is invisible on the other until merge. The work is duplicated and one result is discarded. [[ADR-NO-CLAIMS]] accepts this for v1, and [[ADR-SMALL-SCOPE]] excludes the state shared across worktrees that could prevent it.
|
|
250
|
+
:::
|
|
251
|
+
|
|
252
|
+
:::mara risk RISK-ID-COLLISION
|
|
253
|
+
:mid: 01M764FJ3Z4YEGWP7Z0Y8VZE9N
|
|
254
|
+
:title: Issues created independently share an ID
|
|
255
|
+
:status: accepted
|
|
256
|
+
:likelihood: rare
|
|
257
|
+
:consequence: minor
|
|
258
|
+
:threatens: REQ-MERGE-SAFE-IDS
|
|
259
|
+
|
|
260
|
+
Two branches could generate the same random ID. Both issues are then `<id>.md`, so the merge stops with an add/add conflict that has to be resolved by giving one issue a new ID. The collision merges silently only when one copy was already archived on its branch, so the paths differ; the ID is then ambiguous until `zban check` reports it. With 2^30 values per prefix, a thousand issues created on each of two branches collide with a probability of about 0.1%.
|
|
261
|
+
:::
|
|
262
|
+
|
|
263
|
+
:::mara risk RISK-SESSION-ABOVE-PROJECT
|
|
264
|
+
:mid: 01M772MFTG88ME51FKVXTNF540
|
|
265
|
+
:title: Agents started above a project miss the guide
|
|
266
|
+
:status: accepted
|
|
267
|
+
:likelihood: possible
|
|
268
|
+
:consequence: minor
|
|
269
|
+
:threatens: NEED-AGENT-ONBOARDING
|
|
270
|
+
|
|
271
|
+
zban decides whether to deliver the agent guide from the directory where a session starts. An agent started in a folder above the project, such as a folder of several repositories or the top of a monorepo with `.zban/` in a subfolder, gets nothing from `zban prime` and only a short note over MCP. It may then track work outside zban. Delivering the full guide everywhere would cost every unrelated session about 150 lines and give advice that does not apply there. The short MCP note still points to `zban prime -C`, and the user guide documents the limitation.
|
|
272
|
+
:::
|
|
273
|
+
|
|
274
|
+
:::mara risk RISK-MERGE-CONFLICTS
|
|
275
|
+
:mid: 01M764FJ3ZVFTZJKT1TXJQ3SM9
|
|
276
|
+
:title: Concurrent edits to one issue conflict on merge
|
|
277
|
+
:status: accepted
|
|
278
|
+
:likelihood: possible
|
|
279
|
+
:consequence: minor
|
|
280
|
+
:threatens: NEED-BRANCH-SAFE
|
|
281
|
+
|
|
282
|
+
Two branches that edit the same lines of the same issue conflict when merged, which interrupts an agent's flow. The file format keeps the conflicting surface small.
|
|
283
|
+
:::
|
|
284
|
+
|
|
285
|
+
:::mara risk RISK-SCOPE-CREEP
|
|
286
|
+
:mid: 01M764FJ3Z2R43ACV2SEMDKTXB
|
|
287
|
+
:title: zban grows beyond a small tool
|
|
288
|
+
:status: accepted
|
|
289
|
+
:likelihood: likely
|
|
290
|
+
:consequence: major
|
|
291
|
+
:threatens: GOAL-SMALL-TOOL
|
|
292
|
+
|
|
293
|
+
Each feature of comparable tools looks reasonable on its own, and agents readily propose more. Accumulated features would make zban hard to understand and maintain. [[ADR-SMALL-SCOPE]] and the repository's agent instructions require a recorded need and decision before scope grows.
|
|
294
|
+
:::
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# zban documentation
|
|
2
|
+
|
|
3
|
+
These pages serve as the user guide and as zban's engineering knowledge. Each
|
|
4
|
+
topic page opens with guidance for users, followed by the requirements and
|
|
5
|
+
design that govern that topic.
|
|
6
|
+
|
|
7
|
+
## For users
|
|
8
|
+
|
|
9
|
+
| Page | What it covers |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| [What zban is](product.mara.md) | Purpose, scope, what zban deliberately does not do, goals and vocabulary |
|
|
12
|
+
| [Issues](issues.mara.md) | The issue file, types, statuses, priorities, relations, ready work and the archive |
|
|
13
|
+
| [Command line](cli.mara.md) | Commands, options and JSON output |
|
|
14
|
+
| [MCP server](mcp.mara.md) | Connecting MCP clients and the available tools |
|
|
15
|
+
| [Using zban with agents](agents.mara.md) | Agent setup, the agent guide and a typical session |
|
|
16
|
+
|
|
17
|
+
## For contributors
|
|
18
|
+
|
|
19
|
+
| Page | What it covers |
|
|
20
|
+
| --- | --- |
|
|
21
|
+
| [Decisions and risks](decisions.mara.md) | Why zban is shaped the way it is, and the risks it accepts |
|
|
22
|
+
| [Verification](verification.mara.md) | How each requirement and goal is checked |
|
|
23
|
+
|
|
24
|
+
## How to read the specification
|
|
25
|
+
|
|
26
|
+
The `:::mara` blocks are [Mara](https://github.com/convesoft/mara) items: goals
|
|
27
|
+
(`GOAL-`), needs (`NEED-`), terms (`TERM-`), scenarios (`SCN-`), requirements
|
|
28
|
+
(`REQ-`), designs (`DES-`), decisions (`ADR-`), risks (`RISK-`), verifications
|
|
29
|
+
(`VER-`) and validations (`VAL-`). Lines such as `:satisfies: NEED-…` connect
|
|
30
|
+
items to each other. `[[ID]]` mentions another item.
|
|
31
|
+
|
|
32
|
+
`status: accepted` means the knowledge is agreed. It does not mean the feature
|
|
33
|
+
is implemented or tested. `draft` marks open proposals, and `retired` marks
|
|
34
|
+
history that no longer applies.
|
|
35
|
+
|
|
36
|
+
The work to build zban is tracked in [`.zban/`](../.zban/) using zban's own
|
|
37
|
+
issue format. Issues refer to these items by ID instead of repeating them.
|