site/content/docs/archive/cli-sketch/index.md

 ---

 layout: docs

 title: "CLI sketch"

 description: "The original design sketch of the zz command line, written before the CLI existed."

 ---

 # 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](/docs/archive/) index for context, or the [Overview](/docs/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

 ```