tsuzuri

package module
v0.1.0-rc.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 29, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

README

Tsuzuri

Git-native, forge-independent task coordination for humans and coding agents working across machines and worktrees.

Tasks are readable Markdown files. Ownership is established through conditional writes to remote Git refs, so independent workers can coordinate through a shared repository. Uncertain writes are reconciled; recovery checks the original task revision and the worker's current assignment.

Use the tsuzuri CLI or embed the Go library. No coordination service or forge API is required. Try it locally with a disposable bare remote.

What it owns

  • Project and task records, dependencies, acceptance criteria and validation.
  • Ready-work discovery, ordering and a shared overview.
  • Remote claims, worker assignments and direct or open handoffs.
  • Sibling worktrees, interrupted setup recovery and unused-claim release.
  • Completion recorded on the canonical base branch.

Your tools own execution authority, agent processes, review, merging and deployment. Claims and assignments are ownership observations; they cannot stop an already running worker. A pull request alone does not complete a task.

Core workflow

From a configured repository:

tsuzuri validate
tsuzuri overview
tsuzuri next
tsuzuri show improve-search
tsuzuri claim improve-search --worker developer-laptop
tsuzuri status improve-search

claim establishes remote ownership before creating an implementation branch and sibling worktree. Work there, then integrate the changes and terminal task record into the configured base branch.

Use materialize to resume interrupted worktree setup, handoff and accept to transfer assignments, and release to relinquish an unused claim. Release preserves implementation commits and local changes.

For automation, use --json and discover supported operations with tsuzuri compatibility --json. Coordinators managing their own workspaces can claim and accept with --no-worktree. See integration and recovery.

Install

Download a matching binary and its checksums from Releases. The executable is tsuzuri. Supported targets are Linux and macOS on amd64 and arm64, with Git 2.40+. Binaries do not require Go or Nix. Windows is unsupported; prerelease binaries are unsigned and not notarized.

To build from source, use Go 1.26.10 or the optional nix develop shell:

git clone https://github.com/utsuri-foundry/tsuzuri.git
cd tsuzuri
make build
./bin/tsuzuri --version

Library

Import github.com/utsuri-foundry/tsuzuri (package tsuzuri):

client, err := tsuzuri.Open(repositoryPath)
if err != nil {
    return err
}
task, source, err := client.Show(ctx, taskID)

The CLI and library share one implementation. Calls accept a context and optional trusted policy; see library integration for ownership checks and error handling. The API is pre-1.0; pin a reviewed version.

Documentation

License

Apache-2.0. See NOTICE for attribution and third-party terms.

Documentation

Overview

Package tsuzuri coordinates Markdown tasks through Git claims and assignments. Claims do not grant execution permission or fence running workers.

Index

Examples

Constants

View Source 
const Version = "0.1.0-rc.6"

Variables

This section is empty.

Functions

func JSON 

func JSON(result Result) ([]byte, error)

JSON renders exactly one envelope. Native clients can use typed method results.

Types

type AcceptRequest 

type AcceptRequest struct {
	Task       TaskID
	Worker     WorkerID
	Worktree   string
	NoWorktree bool
}

AcceptRequest selects the incoming or recovering worker and workspace mode.

type AcceptanceResult 

type AcceptanceResult struct {
	CoordinationSource
	TaskID                        string              `json:"taskId"`
	ClaimID                       string              `json:"claimId"`
	Assignment                    *AssignmentMetadata `json:"assignment"`
	RemoteRef                     string              `json:"remoteRef"`
	CreatedLocalReceipt           bool                `json:"createdLocalReceipt"`
	UpdatedLocalAssignmentReceipt bool                `json:"updatedLocalAssignmentReceipt"`
	ClaimedTask                   *TaskRevision       `json:"claimedTask"`
	ClaimObjectID                 string              `json:"claimObjectId"`
	Materialization               *Materialization    `json:"materialization"`
}

AcceptanceResult records the reconciled assignment and local receipt effects.

type AreaOverlap 

type AreaOverlap struct {
	TaskID     string   `json:"taskId"`
	Owner      *string  `json:"owner"`
	Areas      []string `json:"areas"`
	Incomplete bool     `json:"incomplete"`
	Error      *string  `json:"error"`
}

AreaOverlap reports shared areas with other claimed tasks; it is advisory.

type AssignmentMetadata 

type AssignmentMetadata struct {
	Version          int     `json:"version"`
	RepositoryID     string  `json:"repositoryId"`
	TaskID           string  `json:"taskId"`
	ClaimID          string  `json:"claimId"`
	AssignmentID     string  `json:"assignmentId"`
	State            string  `json:"state"`
	Worker           *string `json:"worker"`
	PreviousObjectID string  `json:"previousObjectId"`
	UpdatedAt        string  `json:"updatedAt"`
	ObjectID         string  `json:"objectId"`
}

AssignmentMetadata identifies a worker generation and its previous assignment.

type AssignmentObservation 

type AssignmentObservation struct {
	TaskID   string              `json:"taskId"`
	RefName  string              `json:"refName"`
	ObjectID string              `json:"objectId"`
	Status   string              `json:"status"`
	Valid    bool                `json:"valid"`
	Metadata *AssignmentMetadata `json:"metadata"`
	Error    *string             `json:"error"`
}

type ClaimMetadata 

type ClaimMetadata struct {
	Version        int    `json:"version"`
	RepositoryID   string `json:"repositoryId"`
	TaskID         string `json:"taskId"`
	ClaimID        string `json:"claimId"`
	Owner          string `json:"owner"`
	BaseObjectID   string `json:"baseObjectId"`
	ClaimedAt      string `json:"claimedAt"`
	AnchorObjectID string `json:"anchorObjectId"`
}

ClaimMetadata binds a claim to its repository, task, owner and original base.

type ClaimObservation 

type ClaimObservation struct {
	TaskID      string                 `json:"taskId"`
	RefName     string                 `json:"refName"`
	ObjectID    string                 `json:"objectId"`
	Status      string                 `json:"status"`
	Valid       bool                   `json:"valid"`
	Metadata    *ClaimMetadata         `json:"metadata"`
	ClaimedTask *TaskRevision          `json:"claimedTask"`
	Assignment  *AssignmentObservation `json:"assignment"`
	Drift       []string               `json:"drift"`
	Error       *string                `json:"error"`
}

ClaimObservation is validated evidence about a claim, not execution authority.

type ClaimRequest 

type ClaimRequest struct {
	Task                            TaskID
	Worker                          WorkerID
	Owner, ExpectedDigest, Worktree string
	NoWorktree                      bool
}

ClaimRequest selects an original task revision and an explicit worker. NoWorktree leaves implementation workspace management to the caller.

type ClaimResult 

type ClaimResult struct {
	Metadata        ClaimMetadata       `json:"metadata"`
	RemoteRef       string              `json:"remoteRef"`
	SnapshotID      string              `json:"snapshotId"`
	Overlaps        []AreaOverlap       `json:"overlaps"`
	Assignment      *AssignmentMetadata `json:"assignment"`
	ClaimedTask     TaskRevision        `json:"claimedTask"`
	Materialization *Materialization    `json:"materialization"`
}

ClaimResult binds ownership, original task revision and optional workspace.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client selects a repository. Each operation obtains its own context and snapshot. Concurrent callers must still coordinate clone-local authoring/worktree operations.

func Open 

func Open(directory string) (*Client, error)

Open selects a clone path. Repository validation occurs when an operation runs.

func (*Client) Accept 

func (c *Client) Accept(ctx context.Context, request AcceptRequest, options ...OperationOptions) (AcceptanceResult, Source, error)

Accept reconciles the current assignment and recovers clone-local receipts. It is not an execution fence: callers must reverify ownership after return.

func (*Client) Author 

func (c *Client) Author(ctx context.Context, command, id, requestID string, input []byte, options ...OperationOptions) (Result, error)

Author applies JSON record changes. Receipts and transition locks are clone-local Git refs; canonical task completion still requires integration.

func (*Client) Claim 

func (c *Client) Claim(ctx context.Context, request ClaimRequest, options ...OperationOptions) (ClaimResult, Source, error)

Claim uses the same engine as the standalone CLI, including receipt recovery.

func (*Client) Coordinate 

func (c *Client) Coordinate(ctx context.Context, request Coordination, options ...OperationOptions) (Result, error)

Coordinate executes an explicit ownership command and returns its result envelope.

func (*Client) Next 

func (c *Client) Next(ctx context.Context, project string, options ...OperationOptions) ([]TaskView, Source, error)

Next discovers ready work on a fresh canonical snapshot. Readiness grants no execution permission. An empty project selects every project.

func (*Client) Query 

func (c *Client) Query(ctx context.Context, q Query, options ...OperationOptions) (Result, error)

Query returns a schema-1 envelope for the requested inspection.

Example 
package main

import (
	"context"
	"fmt"
	"time"

	tsuzuri "github.com/utsuri-foundry/tsuzuri"
)

func main() {
	client, err := tsuzuri.Open(".")
	if err != nil {
		panic(err)
	}
	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
	defer cancel()
	// Capability discovery works before a task store is configured.
	result, err := client.Query(ctx, tsuzuri.Query{Command: "compatibility"})
	if err != nil {
		panic(err)
	}
	fmt.Println(result.Command, result.Schema, result.OK)
}

Output:
compatibility 1 true

func (*Client) Show 

func (c *Client) Show(ctx context.Context, id string, options ...OperationOptions) (Inspection, Source, error)

Show inspects a task and its current ownership on a fresh canonical snapshot.

type Config 

type Config struct {
	Schema           int      `toml:"schema"`
	RepositoryID     string   `toml:"repository_id"`
	TaskRoot         string   `toml:"task_root"`
	BaseBranch       string   `toml:"base_branch"`
	ClaimNamespace   string   `toml:"claim_namespace"`
	WorktreeRoot     string   `toml:"worktree_root"`
	WorktreeTemplate string   `toml:"worktree_template"`
	Areas            []string `toml:"areas"`
	Risks            []string `toml:"risks"`
}

Config is the schema-1 repository configuration stored in .tsuzuri.toml.

type Coordination 

type Coordination struct {
	Command, ID, Owner, Worker, Worktree, ExpectedDigest, To, Checkpoint string
	NoWorktree                                                           bool
}

Coordination describes one explicit ownership operation. It never grants authority to execute work; callers must retain their own authorization checks.

type CoordinationSource 

type CoordinationSource struct {
	RepositoryID                string   `json:"repositoryId"`
	BaseObjectID                string   `json:"baseObjectId"`
	ConfigurationObjectID       *string  `json:"configurationObjectId"`
	SnapshotID                  string   `json:"snapshotId"`
	ObservedClaimObjectIDs      []string `json:"observedClaimObjectIds"`
	ObservedAssignmentObjectIDs []string `json:"observedAssignmentObjectIds"`
}

CoordinationSource identifies observed refs using the schema-1 wire format.

type CreateProjectInput 

type CreateProjectInput struct {
	ID         string         `json:"id"`
	Title      string         `json:"title"`
	State      string         `json:"state"`
	Goal       string         `json:"goal"`
	FinishLine string         `json:"finishLine"`
	Extensions map[string]any `json:"extensions"`
}

CreateProjectInput is the JSON body accepted by create-project.

type CreateTaskInput 

type CreateTaskInput struct {
	ID                 string            `json:"id"`
	Project            string            `json:"project"`
	Title              string            `json:"title"`
	Kind               string            `json:"kind"`
	State              string            `json:"state"`
	Priority           string            `json:"priority"`
	BlockedBy          []string          `json:"blockedBy"`
	Areas              []string          `json:"areas"`
	Risks              []string          `json:"risks"`
	Created            string            `json:"created"`
	BlockedReason      *string           `json:"blockedReason"`
	Outcome            *string           `json:"outcome"`
	Acceptance         *string           `json:"acceptance"`
	Resolution         *string           `json:"resolution"`
	AdditionalSections map[string]string `json:"additionalSections"`
	Extensions         map[string]any    `json:"extensions"`
}

CreateTaskInput is the JSON body accepted by create-task.

type Error 

type Error struct {
	Kind     string `json:"kind"`
	Code     string `json:"code"`
	Message  string `json:"message"`
	ExitCode int    `json:"exitCode"`
	Details  any    `json:"details"`
	// contains filtered or unexported fields
}

Error is a classified failure with recovery details and an optional cause.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type HandoffResult 

type HandoffResult struct {
	CoordinationSource
	TaskID                        string              `json:"taskId"`
	ClaimID                       string              `json:"claimId"`
	Assignment                    *AssignmentMetadata `json:"assignment"`
	RemoteRef                     string              `json:"remoteRef"`
	RemovedLocalReceipt           bool                `json:"removedLocalReceipt"`
	RemovedLocalAssignmentReceipt bool                `json:"removedLocalAssignmentReceipt"`
}

HandoffResult identifies the published assignment and removed local receipts.

type Inspection 

type Inspection struct {
	TaskView
	Markdown        string            `json:"markdown"`
	Claim           *ClaimObservation `json:"claim"`
	ClaimedMarkdown *string           `json:"claimedMarkdown"`
}

Inspection includes current task text and the original claimed revision.

type LocalClaimObservation 

type LocalClaimObservation struct {
	TaskID                    string   `json:"taskId"`
	ReceiptObjectID           *string  `json:"receiptObjectId"`
	AssignmentReceiptObjectID *string  `json:"assignmentReceiptObjectId"`
	BranchObjectID            *string  `json:"branchObjectId"`
	WorktreePath              *string  `json:"worktreePath"`
	WorktreeHead              *string  `json:"worktreeHead"`
	WorktreeClean             *bool    `json:"worktreeClean"`
	Issues                    []string `json:"issues"`
}

type Materialization 

type Materialization struct {
	TaskID         string `json:"taskId"`
	Branch         string `json:"branch"`
	WorktreePath   string `json:"worktreePath"`
	AnchorObjectID string `json:"anchorObjectId"`
	Resumed        bool   `json:"resumed"`
}

Materialization identifies a local implementation branch and worktree.

type OperationOptions 

type OperationOptions struct {
	GitExecutable          string
	Environment            []string
	ExpectedRemoteURL      string
	ExpectedRepositoryID   string
	ExpectedClaimNamespace string
}

OperationOptions supplies trusted policy for one call without changing process globals. Environment replaces the child environment; nil inherits the process environment. An explicit environment requires an absolute GitExecutable. Keep the slice unchanged until return. Pass credentials through Git config environment variables, never command arguments; see docs/integration.md for supervisor setup. Nonempty Expected fields must match: mismatches return *Error with Kind/Code "validation" and ExitCode 3; malformed options return "usage" (exit 2).

type OrphanAssignmentDetails 

type OrphanAssignmentDetails struct {
	Issue              string  `json:"issue"`
	RepositoryID       string  `json:"repositoryId"`
	TaskID             string  `json:"taskId"`
	BaseObjectID       string  `json:"baseObjectId"`
	SnapshotID         string  `json:"snapshotId"`
	ClaimRef           string  `json:"claimRef"`
	ClaimObjectID      *string `json:"claimObjectId"`
	AssignmentRef      string  `json:"assignmentRef"`
	AssignmentObjectID string  `json:"assignmentObjectId"`
	SafeAction         string  `json:"safeAction"`
}

OrphanAssignmentDetails describes observed evidence, not repair authority. A surviving assignment cannot establish the missing implementation tip.

type OverviewAssignment 

type OverviewAssignment struct {
	Status    string  `json:"status"`
	Worker    *string `json:"worker"`
	UpdatedAt *string `json:"updatedAt"`
	RefName   string  `json:"refName"`
	ObjectID  string  `json:"objectId"`
	Valid     bool    `json:"valid"`
	Error     *string `json:"error"`
}

type OverviewClaim 

type OverviewClaim struct {
	Status     string              `json:"status"`
	Owner      *string             `json:"owner"`
	ClaimedAt  *string             `json:"claimedAt"`
	Assignment *OverviewAssignment `json:"assignment"`
	RefName    string              `json:"refName"`
	ObjectID   string              `json:"objectId"`
	Drift      []string            `json:"drift"`
	Error      *string             `json:"error"`
}

type OverviewIssue 

type OverviewIssue struct {
	TaskID string `json:"taskId"`
	OverviewClaim
}

type OverviewTask 

type OverviewTask struct {
	ID                     string         `json:"id"`
	Title                  string         `json:"title"`
	Project                string         `json:"project"`
	Kind                   string         `json:"kind"`
	CanonicalState         string         `json:"canonicalState"`
	Priority               string         `json:"priority"`
	Created                string         `json:"created"`
	ProjectAvailability    string         `json:"projectAvailability"`
	DependencyStatus       string         `json:"dependencyStatus"`
	UnfinishedDependencies []string       `json:"unfinishedDependencies"`
	CancelledDependencies  []string       `json:"cancelledDependencies"`
	BlockedReason          *string        `json:"blockedReason"`
	Claim                  *OverviewClaim `json:"claim"`
}

type Project 

type Project struct {
	Schema     int            `json:"schema" toml:"schema"`
	ID         string         `json:"id" toml:"id"`
	Title      string         `json:"title" toml:"title"`
	State      string         `json:"state" toml:"state"`
	Goal       string         `json:"goal" toml:"-"`
	FinishLine string         `json:"finishLine" toml:"-"`
	Path       string         `json:"path" toml:"-"`
	Extensions map[string]any `json:"-" toml:"extensions"`
}

type Query 

type Query struct {
	Command, ID, Source, Project, Kind, State, ClaimStatus, Format, Color string
	Refresh                                                               bool
}

type ReleaseResult 

type ReleaseResult struct {
	TaskID                   string  `json:"taskId"`
	RemoteRef                string  `json:"remoteRef"`
	AnchorObjectID           string  `json:"anchorObjectId"`
	RemovedWorktree          *string `json:"removedWorktree"`
	RemovedLocalBranch       bool    `json:"removedLocalBranch"`
	RemovedReceipt           bool    `json:"removedReceipt"`
	RemovedAssignmentReceipt bool    `json:"removedAssignmentReceipt"`
	RemoteAlreadyAbsent      bool    `json:"remoteAlreadyAbsent"`
	RemovedRemoteAssignment  bool    `json:"removedRemoteAssignment"`
}

ReleaseResult records conditional release of an unused claim and local cleanup.

type Result 

type Result struct {
	Schema  int     `json:"schema"`
	OK      bool    `json:"ok"`
	Command string  `json:"command"`
	Source  *Source `json:"source"`
	Data    any     `json:"data"`
	Human   string  `json:"-"`
}

Result is the schema-1 automation envelope. Human output is a rendering only.

type Source 

type Source struct {
	Kind                        string   `json:"kind"`
	RepositoryID                string   `json:"repositoryId"`
	BaseObjectID                *string  `json:"baseObjectId"`
	ConfigurationObjectID       *string  `json:"configurationObjectId"`
	SnapshotID                  *string  `json:"snapshotId"`
	ObservedClaimObjectIDs      []string `json:"observedClaimObjectIds"`
	ObservedAssignmentObjectIDs []string `json:"observedAssignmentObjectIds"`
	RefreshResult               *string  `json:"refreshResult"`
}

Source identifies the repository revision and refs used for an observation.

type Task 

type Task struct {
	Schema        int            `json:"schema" toml:"schema"`
	ID            string         `json:"id" toml:"id"`
	Project       string         `json:"project" toml:"project"`
	Title         string         `json:"title" toml:"title"`
	Kind          string         `json:"kind" toml:"kind"`
	State         string         `json:"state" toml:"state"`
	Priority      string         `json:"priority" toml:"priority"`
	BlockedBy     []string       `json:"blockedBy" toml:"blocked_by"`
	Areas         []string       `json:"areas" toml:"areas"`
	Risks         []string       `json:"risks" toml:"risks"`
	Created       string         `json:"created" toml:"-"`
	CreatedDate   toml.LocalDate `json:"-" toml:"created"`
	BlockedReason *string        `json:"blockedReason" toml:"blocked_reason"`
	Path          string         `json:"path" toml:"-"`
	Extensions    map[string]any `json:"-" toml:"extensions"`
}

Task is a parsed task record; its state is canonical only on the base branch.

type TaskID 

type TaskID string

TaskID identifies a permanent task record within a repository.

type TaskRevision 

type TaskRevision struct {
	BaseObjectID string `json:"baseObjectId"`
	Path         string `json:"path"`
	RecordDigest string `json:"recordDigest"`
}

TaskRevision identifies the exact task blob at the claim's original base.

type TaskView 

type TaskView struct {
	Task
	ProjectAvailability  string  `json:"projectAvailability"`
	DependencyStatus     string  `json:"dependencyStatus"`
	ClaimStatus          string  `json:"claimStatus"`
	Owner                *string `json:"owner"`
	Worker               *string `json:"worker"`
	AssignmentStatus     string  `json:"assignmentStatus"`
	CanonicallyClaimable bool    `json:"canonicallyClaimable"`
	RecordDigest         string  `json:"recordDigest"`
}

type TransitionTaskInput 

type TransitionTaskInput struct {
	ExpectedState  string  `json:"expectedState"`
	ExpectedDigest string  `json:"expectedDigest"`
	State          string  `json:"state"`
	BlockedReason  *string `json:"blockedReason"`
	Resolution     *string `json:"resolution"`
}

TransitionTaskInput guards a task transition with its expected state and digest.

type WorkerID 

type WorkerID string

WorkerID identifies a worker across claim, handoff and recovery operations.

Source Files

View all Source files

Directories

Path Synopsis
cmd
check-architecture command
check-architecture validates this repository's explicit source ownership.
 check-architecture validates this repository's explicit source ownership.
tsuzuri command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.