WeftMark is the proposed RAGBAZ control plane for multi-agent software work: a vendor-neutral ledger for scope, Git lineage, evidence, handoff, review, and merge/release readiness.
It grows out of the operational lessons encoded in RAGBAZ Frog without trying to become another coding agent, issue tracker, or build system. Frog has already proven useful primitives around agent identity, task claiming, locks, dependency-aware scheduling, affected builds, workspace federation, MCP, event history, and causality. WeftMark narrows the next product boundary around the question that becomes scarce when many agents can write code at once:
Can we explain why a worker was allowed to change something, what actually changed, what evidence says it works, who reviewed it, and whether it is genuinely ready to merge or release?
This repository now contains a prototype WeftMark runtime as well as its executable design and implementation record. Local Change Sets, semantic claims, Git lineage, evidence, review, handoff, CLI/status surfaces, and the read-only Kanban/mobile projection and tablet/phone review surface are implemented; this is still prototype software, not a production or released control plane.
src/weftmark/contains the local runtime and application/domain layers.src/weftmark/adapters/contains read-only observation adapters for six code forges (GitHub, GitLab, Gitea, Forgejo, Bitbucket, Azure DevOps), the ACP runtime adapter, and the local Git and ledger adapters; the forge adapters never mutate forge state.tests/contains executable runtime and contract evidence used by CI.web/review/contains the dependency-free read-only tablet/phone review client.docs/weftmark.mdxremains the editable source of truth for the product and architecture paper.docs/artifacts/weftmark_rev0.htmlandweftmark_rev0.pdfpreserve the immutable revision-0 design report.tasks/*.weft.ymlcontain the dependency-aware implementation plan and task evidence requirements.assurance/facts.jsonrecords machine-readable capability state used to keep public claims from silently outrunning implementation and verification.THIRD_PARTY_NOTICES.mdrecords the policy and inventory point for upstream license and attribution obligations.AGENTS.mdspecifies the small YAML-compatible task dialect used by the task plan.assets/weftmark.svgis the canonical white-background vector mark;assets/weftmark-on-black.svgis the dark-background variant.ragbaz.component.jsonfollows the RAGBAZ component-manifest convention while continuing to mark WeftMark as a prototype, not production software.
This table is generated from assurance/facts.json; implemented is not
treated as verified, and nothing is marked releasable without explicit
release evidence.
| Capability | Implemented | Verified | Reviewed | Releasable |
|---|---|---|---|---|
| Change Set lifecycle and Git lineage | yes | yes | — | — |
| Semantic scopes and local claims | yes | yes | — | — |
| Evidence, review, and handoff workflow | yes | yes | yes | — |
| Kanban/mobile read projection | yes | yes | yes | — |
| Loopback-only HTTP read surface | yes | yes | yes | — |
| Semantic scope blockers in board status | yes | yes | yes | — |
| Tablet/phone read-only review surface | yes | yes | yes | — |
WeftMark is not yet published to PyPI; install it from a local clone.
See docs/INSTALL.md for the full guide (supported
Python versions, optional extras, and a verification walkthrough). The
short version:
git clone https://github.com/tabenius/WeftMark.git
cd WeftMark
pip install .New here? Follow the five-minute Quickstart for one complete local loop: declare a Change Set, claim a scope, commit, record evidence, review, and hand off. It only writes to a local ledger; nothing is committed, pushed or published by WeftMark.
The committed uv.lock records runtime dependencies and all optional extras.
For the same test and documentation environment as CI (uv 0.12.19):
uv sync --locked --extra test --group docs
uv run --locked --extra test --group docs python -m pytest
uv lock --checkUpdate intentionally with uv lock --upgrade, review the lockfile diff, and
commit it together with any manifest changes. Keep the docs dependency group
compatible with requirements-docs.txt, which remains available to pip users.
Ordinary pip install . does not consume this lockfile.
uv sync --locked --extra sqlite installs the SQLite LedgerPort adapter and
Nostoi >=0.1.1,<0.2. On Linux amd64 CPython with glibc >=2.34, uv selects the
hash-locked release wheel: no Rust toolchain is needed. Other platforms use the
pinned release source and require Rust/Maturin; Linux musl or older glibc needs
an explicit source override. It preserves supported existing ledger digests and adds atomic CAS,
idempotent receipts, workspace isolation and verified backups. The CLI still
defaults to JSONL; migration is explicit. See
docs/SQLITE-LEDGER.md for use, SQL/API schemas, the
portable D1/libSQL batch seam, Litestream boundaries and remaining review gates.
weftmark --help opens with a woven-W wordmark derived from the logo;
weftmark --version lists the capabilities actually installed (core ledger,
forge adapters, completions, and whether the optional tui/sqlite extras are
present). Both work outside a Git repository.
weftmark completion <shell> prints a completion script generated from the live
argparse tree: top-level and nested subcommands, their options, and enumerated
values such as --priority p0..p3. Set it up once:
# bash — add to ~/.bashrc:
eval "$(weftmark completion bash)"
# …or install system-wide:
weftmark completion bash | sudo tee /etc/bash_completion.d/weftmark
# fish:
weftmark completion fish > ~/.config/fish/completions/weftmark.fishHuman-readable output is colored only on a real terminal. NO_COLOR, TERM=dumb
and WEFTMARK_COLOR=never disable it; FORCE_COLOR, CLICOLOR_FORCE and
WEFTMARK_COLOR=always enable it. --json always emits one clean JSON document
suitable for jq, even when color is forced. Help uses $WEFTMARK_PAGER/$PAGER
on a terminal (--no-pager disables it); task create --edit opens
$WEFTMARK_EDITOR/$VISUAL/$EDITOR. See docs/CLI.md for the
full reference, including exit codes and scripting examples.
Frog remains a useful reference implementation and a source of hard-earned workflow lessons. The intended transition is conceptual rather than a blind rewrite or schema fork.
| Frog has demonstrated | WeftMark makes first-class |
|---|---|
| tasks, deps, claims | Change Sets around transient worker sessions |
| file/repo locks | file and semantic/contract scopes |
| agents and sessions | actor/session provenance bound to changes |
| event log and causality | evidence ledger with immutable lineage |
| build/test orchestration | typed proof: passed, failed, unavailable, stale |
| workspace hand coordination | explicit, portable handoff records |
| board/status views | reviewer-facing readiness decisions |
| MCP and remote workspaces | adapters around one vendor-neutral application model |
The implementation plan therefore starts with domain concepts and evidence semantics, then adds Git/forge adapters and surfaces. It does not begin by building a web dashboard or another agent loop.
The documentation source uses a conservative MDX-compatible subset: YAML front matter, Markdown, and raw HTML blocks. It deliberately avoids executable JSX components, so the build stays deterministic and does not require a Node runtime. Pandoc renders the source to a single self-contained HTML file, and WeasyPrint produces the A5 PDF from that same HTML/CSS.
Requirements:
- Python 3.11+
- Pandoc
- WeasyPrint's native libraries (Pango and its dependencies); see the WeasyPrint installation guide for the packages your platform needs
- packages in
requirements-docs.txt
python -m venv .venv
. .venv/bin/activate
pip install -r requirements-docs.txt
make html # build/weftmark.html, self-contained
make pdf # build/weftmark_A5.pdf via WeasyPrint
make logo # PNG + lossless WebP derivatives at 512 px
make tasks # validate tasks/*.weft.yml
make allSee docs/BUILD.md for the source/artifact policy.
The SVGs are the editing sources. Raster formats are reproducible derivatives:
python scripts/build_logo.py --size 512This writes:
assets/generated/weftmark-512.png
assets/generated/weftmark-512.webp
assets/generated/weftmark-on-black-512.png
assets/generated/weftmark-on-black-512.webp
The vector mark is a cleaned, flat-vector interpretation of the selected rev0 concept. The SVGs are canonical; PNG and WebP files are reproducible derivatives.
Humans and agents should start with AGENTS.md and tasks/00-bootstrap.weft.yml.
The initial graph currently covers:
- reproducible repository/docs/assets foundations;
- Change Set, evidence, handoff, and review domain models;
- semantic/contract scopes and locks;
- local Git lineage and optional code-forge adapters;
- evidence policies and reviewer-facing readiness summaries;
- CLI, MCP, terminal, and tablet/mobile read surfaces;
- a deliberate transition/dogfood path from Frog; and
- security, packaging, licensing, and release evidence for an open-source alpha.
Validate the graph with:
python scripts/validate_tasks.py
python scripts/check_assurance_docs.py- Workers are replaceable. Claude Code, Codex, OpenCode, local Ollama/Mistral-backed workers, and humans are actors/adapters - not the product ontology.
- Git is lineage, not the whole workflow. Commits and branches are durable facts, but evidence and review state need their own model.
- Done is not evidence. Implemented, locally tested, CI-verified, reviewed, merge-ready, and release-proven are separate states.
- Unavailable is not failed. A CI job that never ran is not a failing test.
- Semantic collisions matter. Two agents can edit different files and still change the same protocol, schema, or security boundary.
- Handoffs are data. Continuation should not depend on recovering a chat transcript.
- Open interfaces first. The core should function locally and remain useful when model vendors, IDEs, agent harnesses, and forge providers change.
WeftMark is licensed under the Apache License, Version 2.0. See LICENSE.
The license permits use, modification, redistribution, and commercial use subject
to its terms, and includes an express patent license from contributors for patent
claims necessarily infringed by their contributions.
For inbound contributions, WeftMark currently follows Apache-2.0 section 5: unless a contributor explicitly states otherwise, a contribution intentionally submitted for inclusion in WeftMark is submitted under Apache-2.0 without additional terms. This repository does not currently impose a separate Contributor License Agreement. A contribution may be explicitly designated "Not a Contribution" as described by the license, and a future separate written agreement may supersede this default for parties that enter one.
Redistributors and downstream adaptations must preserve the license and
applicable notices, retain relevant attribution, and mark modified files where
the license requires it. Third-party code and assets retain their own license
obligations; see THIRD_PARTY_NOTICES.md for the repository policy. This is
particularly relevant to planned integration with Apache-2.0 projects such as
Cline Kanban: upstream license and NOTICE obligations remain applicable even
when the licenses are compatible.
Apache-2.0 does not grant trademark rights except for the limited descriptive uses stated in the license.