Planning and design

Everything here is engineering-facing, not user-facing: designs for parts of zz that don't exist yet, the meta-level standard new designs get checked against before they're built, and the research and background those designs actually cite. If you're trying to use zz today, start at Overview instead -- everything in the main sidebar above this section describes what's real and working now.

Most pages here say so explicitly at the top (Status: designed, not built, or similar). That's not a disclaimer to skim past -- it's the actual point of keeping this section separate. A design doc describing a future state is a different kind of reading than a reference doc describing what a command does right now, and conflating them in one navigation made it hard to tell which was which.

Page What it covers
Principles The five stated values design decisions get checked against, and why they're checkable rather than just felt.
Design: directed selection The narrower, operationally-checkable standard specifically for architecture decisions -- variation stays open, selection carries real human-authored values. The checklist to run any new design idea against.
How work gets done in zz The comprehensive mechanics-plus-philosophy explainer -- the deep version of Overview, for understanding why zz is shaped the way it is, not just what each command does.
Charter A repo's stated purpose and non-goals, checkable against a contribution the way Policy checks process -- consulted ambiently by any agent, not executed by one privileged role.
Plan: building directed selection The sequenced build plan for Insights, Charter, drive-by contributions, and Trust-over-Role, each step naming the specific centralization drift it's guarding against.
Lane, Ask, and Role boundaries The Lane as the singular primitive, and the real Owner/Maintainer/Coordinator naming confusion this found and partially fixed.
Mediated conflict resolution What happens when two changesets conflict -- Policy-driven modes from automatic resolution up to human escalation, and Insights as the durable memory of what was decided.
Trust model Earned, behavior-based standing as the long-term alternative to assigned Role grants.
did:zz A unified decentralized identifier method for humans and agents alike.
Agentic autonomy What's actually true about human/agent parity today, what's an external blocker zz can't solve alone, and one concrete step toward it.
Credential handling Moving off token-in-the-URL toward a real git credential helper and short-lived tokens.
Ladder as a RAG knowledge graph Precisely-bounded context retrieval for agent tasks -- a major initiative, explicitly gated on validating its central empirical premise before further build-out.
Contributors guide (sketch) A per-claim guide assembled live from Principles, Policy, Insights, and Charter -- sketched, not designed in full, pending Insights.
Cost tracking (sketch) Tokens for agent work, hours for human work, on the same Ladder.
The Hugging Face incident A corrected, primary-source account of the real incident this project's self-organization model traces back to -- what's confirmed, what a secondhand AI summary fabricated, and what does and doesn't map onto zz.
Prior art Real precedents -- Debian's constitution, the Linux kernel's subsystem-maintainer tree, Apache's lazy consensus -- for specific mechanisms zz's governance design reuses rather than invents.
Virtualized git (reference) Future storage-architecture options if git-native storage ever becomes a real bottleneck. Not scheduled.

See also Case studies -- real bugs and design corrections found while actually building and demoing zz, including the course correction that produced most of the pages above.