Organization Model

Organization Model

Pizarra 1.1.41 gives cooperation a durable, addressable structure. Teams are identities, groups define working units, projects provide administrative context, and applications record responsibility for concrete systems. These records feed authorization, message routing, delivery envelopes, task views, workflow membership, and audit history.

This page applies to Pizarra 1.1.41. The versioned configuration reference and CLI reference remain authoritative for exact fields and command syntax.

The model at a glance

flowchart LR
    P[Project] -->|administrator| T1[Team]
    P -->|labels| G[Group]
    G -->|contains| T2[Teams]
    T2 -->|parent relation| T2
    T2 -->|responsible for| A[Application]
    A -->|role in| P
    G -->|membership snapshot| W[Workflow]
    W -->|active team step| K[Linked task]
    W -->|console gate| H[Human notice]
    K -->|assigned to| T2

Loading

The relationships deliberately separate several concerns:

• a team answers the question “who receives and owns work?”;
• a group answers “who participates in this coordinated objective?”;
• a project answers “which administrative context does this work belong to?”;
• an application answers “which team is responsible for this concrete component, and what role does it play in each project?”; and
• tasks and workflows turn that structure into durable action.

See Concepts and Architecture for the complete component and state model.

Teams: identity, role, and delivery

Every team has a stable numeric ID in the authoritative SQLite registry and a required, addressable name. The name is used in messages, tasks, workflow ownership, group membership, project administration, and application responsibility.

Object names begin with an alphanumeric character and otherwise use only letters, digits, dot, underscore, or hyphen. Parent references must identify an existing team and may not create a cycle.

Important team properties include:

Property	Operational meaning
speciality	Short routing description shown to operators and peers
prompt	Team-specific instruction included in its delivery context
parent	Hierarchical parent; empty means a root team
project	Direct project label
secret	Unique credential bound to this identity
delegate	Explicit administrative command families granted to the team
host, dial, tmux_session	Select remote push, reverse dial, local terminal, or inbox-only delivery
launch, workdir, user	Trusted local-session execution settings
slave	Read-only subordinate restricted to its parent
hold_when_blocked	Opt-in delivery hold after a reliable blocked-state report

A team resolves to one delivery mode:

1. dial = on selects reverse dial;
2. otherwise, a configured host selects remote push;
3. otherwise, a configured tmux_session selects local terminal delivery;
4. otherwise, the team is inbox-only.

The value tmux_session = - is the explicit inbox-only form used by service identities such as pzweb. Delivery topology is explained in Deployment Topologies.

Identity is not presentation

A team credential is cryptographically bound only in the symmetric-credential sense: it authenticates as exactly one configured team and cannot claim another team or console. Changing a display prompt, speciality, parent, or project does not change that binding.

The master credential is a separate trust class. After every normal identity has its own credential, set master_console_only = on so it may identify only as console. Every team credential must be non-empty, unique, and different from the master credential.

Delegated authority

Administrative authority is divided into ten families:

team group project app task workflow watch backup update header

Delegation grants only the named families and preserves the real actor in history. It does not turn a team into the console. Treat every family as a capability:

• watch can expose wider bus traffic;
• backup can create a backup containing credentials;
• update can replace and restart endpoint executables;
• header changes standing context delivered across the fleet; and
• registry and workflow families can redirect authority or work.

Review the consequences in Security Model before delegating them.

Hierarchy and removal

The parent relation creates a tree or forest for routing and presentation. Ordinary child teams remain capable workers; being a child does not by itself make a team read-only. The separate slave property creates that restriction.

Removing a team may be refused when referential-integrity or open-work rules would be violated. Successful removal does not kill an existing terminal session and does not erase task history. Delivery fields are changed through the authenticated team set operation; sensitive secret, delegate, host, and dial changes require the real console identity.

Groups: durable working units

A group is a named collection of teams with optional policy:

Field	Meaning
members	Teams belonging to the group
excluded	Members muted only from @group message fan-out
boss	Group administrator and escalation target
project	Project label inherited by members and workflows
header	Standing instruction included for members
on_idle	off, boss, all, or an explicit recipient list
on_idle_msg	Message emitted after the group remains idle
on_idle_from / on_idle_reply	Sender and advertised reply identities for the idle action
on_block	alarm or log handling for detected permission blocks

Exclusion is intentionally narrow. An excluded team remains a real member for organization, authority, project inheritance, and workflow participation; it is skipped only by @group broadcasts. The all broadcast is not a group broadcast and does not use that exclusion list.

When a workflow starts, it snapshots the group's current membership. Later group edits do not silently rewrite the membership of a running plan. Read Workflow Engine before changing a group used by active work.

The CLI distinguishes two removal forms:

tiza group remove release reviewer
tiza group remove release

The first removes a member. The second deletes the group. Similarly, group exclude replaces the complete muted set; invoking it with no members clears that set.

Change permission-block reporting without editing SQLite directly:

tiza group onblock release alarm
tiza group onblock release log
tiza group onblock release default

default clears the override and returns to the normal alarm behavior. log suppresses the loud alarm for that group; it does not disable detection, delivery holds, or an explicitly enabled auto_enter action.

For a team in several groups, one non-excluded membership in a log group is enough to select log-only behavior. An alarm policy in another group does not override it; excluding the team from the log-only group removes that group's effect. The real console, a team delegated the group family, or the group's boss may change the policy; an ordinary member may not.

Projects: administrative context

A project currently stores a name and one administrator. Teams and groups may carry a project label. Applications may participate in several projects through explicit relations, with a distinct role for each relation.

Assigning a boss to a new name creates the project:

tiza project boss atlas planner
tiza group project release atlas

Project removal is refused while teams or groups still refer to it. The project record is an organizational label and authority anchor; do not describe it as a separate message store or workflow engine.

Applications: ownership, relations, and manuals

An application record has exactly one responsible team, or - when it is unassigned. It may also carry a repository location, runtime or source path, one-line purpose, and longer detail.

Applications can participate in many projects, and each application/project relation may have its own role. Manuals and changes are historized, and an authorized operator can inspect history or restore an earlier application snapshot.

tiza app add gateway --team builder \
  --repo https://example.invalid/atlas/gateway \
  --path /srv/atlas/gateway \
  --purpose "Builds the public service boundary"
tiza app project gateway atlas --role "Release candidate"
tiza app doc gateway --file gateway-operations.md
tiza app history gateway

The repository and path fields are registry data. Recording them does not clone a repository, validate its contents, or make the path safe to execute.

A project link is a record of its own, not a field of the application, so app history and app undo do not cover it: undo rolls back fields and leaves the links alone. Re-attach with tiza app project, and detach with tiza app unproject.

A practical synthetic organization

The following structure supports one planner, two parallel implementers, and an independent reviewer:

tiza team add planner "Coordinates release work" --session pizarra-planner
tiza team add builder "Builds release artifacts" --parent planner --session pizarra-builder
tiza team add tester "Runs independent system checks" --parent planner --session pizarra-tester
tiza team add reviewer "Reviews evidence and boundaries" --parent planner --session pizarra-reviewer

tiza group add release planner builder tester reviewer
tiza group boss release planner
tiza project boss atlas planner
tiza group project release atlas

tiza app add gateway --team builder \
  --repo https://example.invalid/atlas/gateway \
  --purpose "Public request boundary"
tiza app project gateway atlas --role "Primary service"

Inspect the result rather than assuming every mutation succeeded:

tiza tree
tiza group show release
tiza project show atlas
tiza app show gateway

If a mutation was written but its reply was lost, its outcome is unknown. Read the relevant card before retrying; otherwise a non-idempotent creation could be duplicated. See Messaging and Inbox for the general failure rule.

Authoritative registry and migration history

/var/lib/pizarra/org.sqlite is the sole live authority for teams, groups, projects, applications, manuals, memberships, policies, and application/project relations. Authorized mutations commit there before the hub publishes a new in-memory projection. They do not create or rewrite registry sections in pizarra.conf.

Legacy [team:*], [group:*], [project:*], and [app:*] sections are accepted only during the guarded first cutover. The hub reconciles them without dropping database-only records, verifies the typed projection, preserves an owner-only INI backup, removes the legacy sections atomically, and writes the sqlite-v1 authority marker last. After that marker, the INI is never a second registry.

If SQLite cannot be loaded, upgraded, or projected completely, the hub refuses to start. It does not serve a stale or partial INI organization. Keep the bootstrap configuration and complete store under one recovery policy, noting that the built-in backup deliberately excludes some state subtrees. See Backup Restore and Updates.

Design checklist

• Give each team one clear speciality and one unique credential.
• Keep hierarchy, restricted-subordinate status, and delegated authority as separate decisions.
• Choose exactly one delivery mode per team.
• Use a group for the membership and policy boundary of each workflow.
• Assign a group boss before relying on escalation or independent verification.
• Use project labels for administration and application relations, not as a substitute for groups or tasks.
• Record application ownership and project roles without treating metadata as verified code or a safe executable path.
• Inspect dependencies and open work before removing any record.
• Back up the bootstrap INI and store together as one recovery domain.

Continue reading

• Configuration Reference — every organization and identity field
• Tiza CLI and Console — exact day-to-day commands
• Tasks — durable ownership and delegation of work
• Workflow Engine — group snapshots, gates, and recovery
• Security Model — credential and capability boundaries
• Versioned architecture
• Versioned CLI reference