zz_

CLI sketch

Archived. This is a design or planning document from earlier in the project. It records the reasoning at the time it was written and may describe plans that changed or were never built. See the Archive index for context, or the Overview for how zz works today.

This is a starting point. Commands and flags here will change once there's a real Maintainer to drive them against. zz wraps git/Artifacts for content operations and adds the coordination protocol on top; it does not reimplement git.

Ladder and Lane (implemented)

The one part of this page with working code behind it today. Onboarding drives the same Lane/ASK/ANSWER engine a live Maintainer uses, not a script writing straight into storage; a local model (configurable, currently an Ollama backend) does the content analysis.

zz ladder build <owner/repo> [--force]
zz ladder replay-commits <owner/repo> [--limit <n>] [--force]
zz ladder dump <owner/repo> [--format text|json|html] [--out <path>]
zz lane log <owner/repo> [--lane <id>] [--format text|json] [--out <path>]

build describes the file tree at HEAD and onboards issues, PRs, releases, and contributors, each as its own Lane that claims, does the work, and merges its result into the repo's Ladder. It skips anything that already has a note — running it again, or against a repo that already has hand-researched content layered on top, never overwrites what's there — --force rebuilds the file tree anyway.

replay-commits walks the commit log from the root commit forward, one Lane per commit, building a changeset rung with nested filechange and linechange children from that commit's diff. Each file touched also gets a separate, non-blocking request to update its current-state file rung (what it looked like before this commit, what it looks like now) — the repo's own long-lived Lane is the coordinator for those. --limit bounds how many not-yet-onboarded commits to replay in one run.

dump materializes the resulting Ladder for reading, without touching the notes: plain text, JSON, or a self-contained HTML page.

lane log shows the protocol trail itself — every ASK/ANSWER across every Lane, in order — which is what produced the Ladder dump shows the result of.

Content operations (thin wrappers over Artifacts/git)

zz clone <repo>
zz fork <repo>
zz push
zz pull

Behave as their git equivalents; fork additionally registers the fork with the upstream Maintainer so it participates in OCC and shows up in zz top.

Lane lifecycle

zz lane propose "<name>" [--scope <paths>] [--budget <n>] [--broadcast <scope>]
zz lane list [--open|--active|--held]
zz lane show <lane> --ladder                                  # the Lane's tree + summary

zz ask <lane> --claim                                         # kind: claim_request
zz ask <lane> --review <changeset>                             # kind: review_request
zz ask <lane> --merge <changeset>                               # kind: merge_request, Coordinator-only to grant
zz ask <lane> --more-coordinators [--role committer+]           # kind: coordinator_request
zz ask <lane> "<question>"                                      # kind: change_request / navigation query
zz answer <ask-id> --grant | --deny | "<response>"
zz hold <lane> ["<reason>"]
zz veto <ask-id> ["<reason>"]                                    # Coordinator/Committee only

Roles and votes

zz role grant <agent> <role> --repo <repo> [--scope <paths>]
zz role revoke <agent> <role> --repo <repo>
zz role list --repo <repo>

zz vote call "<subject>" --threshold lazy_majority|two_thirds|consensus
zz vote cast <vote-id> +1|+0|-0|-1
zz vote show <vote-id>

Incident response

zz stop <lane|agent>
zz drop <lane>
zz roll <lane|commit>

Each logs a runbook entry to .zz/ regardless of whether it was invoked manually or by a Tripwire.

Observability

zz top and zz ps are operational views over the protocol: a live (top) or point-in-time (ps) table of every Lane's state, Coordinator, the Coordinator's trust in that area, age, and last ASK.

zz top                 # live view of all Lanes
zz ps                  # point-in-time snapshot, scriptable
zz log <lane>           # the Lane's full ASK/ANSWER/HOLD/VETO/merge history
zz show <lane> --ladder # the Lane's current summary, with links down to source commits
zz insight <lane> --norm|--trap "<note>"   # capture an in-the-flow insight

Governance and policy

zz tripwire add <scope> --when "<condition>" --then "<runbook step>"
zz tripwire list
zz trust <agent> [--topic <scope>]   # trust lookup, per topic
zz whistleblow <agent|lane> "<report>"

Example session

$ zz lane propose "add OAuth provider support" --scope packages/auth
  → opened lane: auth-oauth (backlog)

$ zz ask auth-oauth --claim
→ claimed by you, lease 4h


$ zz top
LANE          AGENT        STATE     TRUST     AGE     LAST ASK
auth-oauth    you          active    0.82      1m      claim granted


$ zz ask auth-oauth --review cs-001
→ review_request sent, policy requires 1 reviewer


$ zz answer ask-002 --grant   # a reviewer approves cs-001


$ zz ask auth-oauth --merge cs-001
→ merge_request sent to coordinator


$ zz answer ask-003 --grant   # coordinator issues the merge grant


$ zz push
→ merge grant valid, OCC check clean, merged