{"_id":"@cordfuse/politik","_rev":"2-5d31defbb2b2f8a33ae9fb893e11b479","name":"@cordfuse/politik","dist-tags":{"latest":"0.3.1"},"versions":{"0.3.0":{"name":"@cordfuse/politik","version":"0.3.0","keywords":["ai","agents","governance","multi-agent","git","politik","cordfuse"],"license":"MIT","_id":"@cordfuse/politik@0.3.0","maintainers":[{"name":"cordfuse","email":"cordfuseinc@gmail.com"}],"homepage":"https://github.com/cordfuse/politik","bugs":{"url":"https://github.com/cordfuse/politik/issues"},"bin":{"politik":"bin/politik.js"},"dist":{"shasum":"caee440199c7547a3a952ad5234fb2e41979c44c","tarball":"https://registry.npmjs.org/@cordfuse/politik/-/politik-0.3.0.tgz","fileCount":69,"integrity":"sha512-WDIM/EbxQJYMq7g44Gvq/ze1Gq80zMkw30fBddctFq3obEt00K6adWBlfpCnSfbjrN6/kYVY69EbbKt++Zcouw==","signatures":[{"sig":"MEQCIAr7mIDve50ProNhPbWaVhUA4Dm/1QWafVeeXy0bYKj4AiBFz2ypBtEgwvglTMRvwJQ1XgQCL91J87UMWUw40P0zRQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":742343},"type":"module","engines":{"node":">=20"},"gitHead":"e3f71d539f718465bafa9c92b100c840bb8f2e95","scripts":{"lint":"tsc --noEmit","test":"node --import tsx --test tests/*.test.ts","build":"tsc --noEmit"},"_npmUser":{"name":"cordfuse","email":"cordfuseinc@gmail.com"},"repository":{"url":"git+https://github.com/cordfuse/politik.git","type":"git"},"_npmVersion":"10.9.8","description":"Politik — a governed multi-agent framework built on git. The SCM repository is the session: charter, record, state, and invite in one.","directories":{},"_nodeVersion":"22.23.1","dependencies":{"tsx":"^4.20.0","yaml":"^2.8.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/politik_0.3.0_1786400127883_0.8444202487804506","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"_id":"@cordfuse/politik@0.3.1","bin":{"politik":"bin/politik.js"},"bugs":{"url":"https://github.com/cordfuse/politik/issues"},"dist":{"shasum":"9b89a31ae36c716bef5ba31d5fb765104d278d0b","tarball":"https://registry.npmjs.org/@cordfuse/politik/-/politik-0.3.1.tgz","fileCount":69,"integrity":"sha512-t2rS2Dn5v+//pjFws5um4T8hCAAdPiR6TrxCNvqSNEjTm7b8pLufGhvDZlyOhShWggk0wcwG61XSU+7Em9ABzw==","signatures":[{"sig":"MEUCICBTfSMtXZ3S80t3v6EH691BfFL/+kj2ymV9ONq1rGG5AiEAt8+OBPKSMErLb+AoCpqMzdvhkezHd/32C58oOQRNO6Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH9SYRHX/zWZZfFucKlXv11iomnnhQLk+HNXqygt0U3cAiEAueGKpWJRiiMyBdOyNn+SjOy2jrSuSFqqWMcDLoMoGTI="}],"unpackedSize":743905},"name":"@cordfuse/politik","type":"module","engines":{"node":">=20"},"gitHead":"c1fa7312c75599d72b187bf20088f51f5dda2247","license":"MIT","scripts":{"lint":"tsc --noEmit","test":"node --import tsx --test tests/*.test.ts","build":"tsc --noEmit"},"version":"0.3.1","_npmUser":{"name":"cordfuse","email":"cordfuseinc@gmail.com"},"homepage":"https://github.com/cordfuse/politik","keywords":["ai","agents","governance","multi-agent","git","politik","cordfuse"],"repository":{"url":"git+https://github.com/cordfuse/politik.git","type":"git"},"_npmVersion":"10.9.8","description":"Politik — a governed multi-agent framework built on git. The SCM repository is the session: charter, record, state, and invite in one.","directories":{},"maintainers":[{"name":"cordfuse","email":"cordfuseinc@gmail.com"}],"_nodeVersion":"22.23.2","dependencies":{"tsx":"^4.20.0","yaml":"^2.8.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/politik_0.3.1_1790199233685_0.4397073809114642"}}},"time":{"created":"2026-08-10T22:15:27.702Z","modified":"2026-09-23T21:33:53.938Z","0.3.0":"2026-08-10T22:15:28.082Z","0.3.1":"2026-09-23T21:33:53.795Z"},"bugs":{"url":"https://github.com/cordfuse/politik/issues"},"license":"MIT","homepage":"https://github.com/cordfuse/politik","keywords":["ai","agents","governance","multi-agent","git","politik","cordfuse"],"repository":{"url":"git+https://github.com/cordfuse/politik.git","type":"git"},"description":"Politik — a governed multi-agent framework built on git. The SCM repository is the session: charter, record, state, and invite in one.","maintainers":[{"name":"cordfuse","email":"cordfuseinc@gmail.com"}],"readme":"# Politik\n\n[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.19490358-blue)](https://doi.org/10.5281/zenodo.19490358)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n**A governed multi-agent framework built on git.**\n\nPluggable governance protocols. Stateless agent workers. Git as the session substrate. Immutable Hansard. Append-only LEDGER. Human constitutional authority.\n\n---\n\n## The Problem\n\nMulti-agent AI coordination today is:\n\n- **Ungoverned** — agents act without rules, quorum, or accountability\n- **Unrecorded** — no immutable audit trail of who decided what and why\n- **Uncosted** — no per-decision attribution of time, tokens, or dollars\n- **Single-machine** — no framework for agents across machines, orgs, or human teams\n- **Human-absent** — humans monitor, not govern\n\nThe result: agents that produce outputs nobody can fully trust, audit, or reproduce.\n\n---\n\n## What Politik Solves\n\nPolitik is a **governed multi-agent operating system** where:\n\n- A **human** is the constitutional authority — present but not operational\n- **Agents** are stateless CLI workers that spawn, do work, and dispose\n- A **git repository IS the session** — charter, record, state, and invite in one\n- **Pluggable governance protocols** translate the framework to any industry vocabulary\n- **A governed tree, not a single machine** — sessions nest into an Org → Team → Ticket hierarchy in one repository; `politik registry` reports the state of everything, across machines and teams\n- **No new infrastructure required** — git already built it\n\nNobody connected these pieces this way before.\n\n---\n\n## Install\n\nPolitik runs on Node with **no build step** — the source is TypeScript, executed\ndirectly via `tsx`. Requires Node 20+ and git.\n\n```sh\nnpm install -g @cordfuse/politik\npolitik doctor                    # probe this host: can it run a session, with which agents?\n```\n\nOr run without installing:\n\n```sh\nnpx @cordfuse/politik doctor\n```\n\nFrom source, if you want to hack on it:\n\n```sh\ngit clone git@github.com:cordfuse/politik.git\ncd politik && npm install\nnode bin/politik.js doctor\n```\n\n## A first session\n\nEvery command below is a git commit. `git log` in the session directory is the\nHansard — the immutable record.\n\n```sh\npolitik scaffold --dir ./session --quorum 2                                  # write a Charter to edit\npolitik init     --dir ./session --charter ./session/CHARTER.md --speaker you\npolitik division call  --dir ./session --motion adopt-standard --actor you --role AUTHORITY\npolitik division vote  --dir ./session --motion adopt-standard --actor ada --role MEMBER --vote AYE\npolitik division vote  --dir ./session --motion adopt-standard --actor bo  --role MEMBER --vote AYE\npolitik division tally --dir ./session --motion adopt-standard               # → Motion CARRIED\npolitik assent         --dir ./session --motion adopt-standard --actor you --role AUTHORITY\n```\n\nSeat a real agent to do the work instead of a human vote:\n\n```sh\npolitik run --dir ./session --agent claude-code --actor ada --role OPERATOR \\\n  --task \"Draft and commit a Motion to adopt trunk-based development.\"\n```\n\nThe agent's turn is captured, its cost measured, and the result recorded — see\n`politik ledger --dir ./session`.\n\n---\n\n## Technical\n\n### CANON — The Primitive Layer\n\nThe engine speaks in canonical terms. Protocols translate them to domain vocabulary.\n\n**Roles:** `AUTHORITY` (human only) · `DELEGATE` · `OPERATOR` · `MEMBER` · `OBSERVER`\n\n**Primitives:** `SESSION` · `PROCEEDING` · `CHARTER` · `RECORD` · `MOTION` · `DIVISION` · `MATCH` · `ESCALATION` · `SUSPENSION` · `QUORUM` · `CONFLICT` · `DEADLOCK`\n\n**Verbs:** `READ` · `WRITE` · `VOTE` · `ASSENT` · `ESCALATE` · `PROMOTE` · `DEMOTE` · `HIRE` · `FIRE` · `SUSPEND` · `EXPEL` · `VETO` · `SPAWN` · `DISSOLVE` · `EXIT`\n\n**States:** `CONVENED` · `SUSPENDED` · `PROROGUED` · `STALE` · `INVALID`\n\n### The Session Repo\n\nThe git repository IS the Politik session. That much is always true — Charter,\nHansard, state and audit trail all live there.\n\nAn **SCM provider is optional**. Configure one and governance acts are\nadditionally projected onto the platform; without one a session runs complete\nand correct on git alone. *Run local, run free.*\n\n| GitHub feature (when hosted) | Politik primitive |\n|---|---|\n| Repository | Session |\n| CHARTER.md | Standing Orders |\n| Pull Request | Motion |\n| PR Review | Division (vote) |\n| Issue | Escalation |\n| GitHub Actions | Clerk automation |\n| Repo access | Taking a Seat |\n| git history | Hansard (immutable record) |\n\n### The Politik Tree\n\nA session is either a standalone repository or a **node in a tree** — an\norganisation's Org → Team → Sprint → Ticket hierarchy as nested directories in\none repository, each node inheriting its parent's Charter. Federation is **local\ntraversal over that one working tree**, not cross-repository orchestration: no new\nservice, no registry server. `politik registry` walks the tree and reports every\nsession's state and cost with a roll-up; `politik cascade` flags a fault repeating\nacross sibling sessions. `politik init --standalone` opts a node out into its own\nrepository when it needs per-session pull requests or a hard permission boundary.\n\n### Agent Model\n\nAgents are stateless. No persistent processes. State lives in git.\n\n```\nBroadcast received → Agent spawned → Prompt executed → Result committed to Hansard → Agent disposed\n```\n\n### The Human Role\n\nThe Speaker (human) is constitutionally present, not operationally present. Drops the Writ, defines Standing Orders, rules on escalations. The session governs itself.\n\n### Governance Protocols\n\n**Eleven reference protocols ship** — Parliamentary, Republic, Monarchy, Socialism (political archetypes), Jury Deliberation, Elimination Tournament, Emergency Response (ICS), Corporate, Peer Review, Adversarial Collaboration, and Solo (single-lead) — spanning constitutional, authoritarian and darwinist modes. Each is a vocabulary translation **plus** a composition of behavioral mechanics — how a decision resolves (majority · supermajority · unanimity), how an actor exits (voted out · elimination · none), and when a session ends (objective · last-standing · verdict) — on top of CANON. You compose your own for anything else; the framework is the product, these are exemplars. Parliamentary is protocol #1, not a privileged mode. Each protocol's vocabulary and mechanics are documented in [PROTOCOLS.md](PROTOCOLS.md).\n\nCompetitive protocols run on the `MATCH` primitive — a real 1v1 contest that a Motion-and-vote Division cannot model. `politik pair` generates a round (Swiss, round-robin, or single-elimination), `politik match report` settles a result, and `politik standings` scores the field from the record.\n\n### Hansard and LEDGER\n\n**Hansard** — append-only session record. Every motion, vote, escalation, and commit. Attributed, timestamped, immutable. Cannot be edited. Cannot be gamed.\n\nBecause the record is the defence against bad faith, `politik integrity` reads the Hansard for the signatures of coercion — a coerced exit, a serial \"voluntold\" — and surfaces them to the Speaker. Detect and report; it never auto-punishes. The record catches what a naive log would hide.\n\n**LEDGER** — cost accounting per act: elapsed time, token count, dollar cost, model. Every governance act writes a row; agent turns carry measured spend, and the human-driven acts (division, assent, escalation, ruling) carry `unmeasured` cost, so the ledger is a complete account of a session. No story points.\n\nMeasured, never estimated — and the distinction is enforced. An agent that reports usage produces exact figures; one that does not is recorded as `unmeasured`, never as `$0.00`, and totals report unmeasured rows separately rather than folding them in. Five CLI agents report usage today — Claude Code, Codex, Gemini, OpenCode and Qwen; the rest record elapsed time and mark cost `unmeasured`.\n\n---\n\n## Game Theory\n\nGame theory is not a protocol in Politik. It is the analytical layer that **observes and describes** what emerges from sessions that are already running.\n\n> Game theory is to Politik what physics is to the universe. Physics doesn't run the universe — it describes it. Game theory doesn't run Politik sessions — it describes the equilibria that emerge from them.\n\nEvery protocol in Politik instantiates a formal game structure:\n\n| Protocol | Game Structure | Nash Equilibrium Prediction |\n|---|---|---|\n| Parliamentary | Cooperative with veto players | Stable coalition at quorum threshold |\n| Emergency Response (ICS) | Stackelberg leader-follower | Full compliance, zero deviation |\n| Jury Deliberation | Unanimity / holdout game | Convergence to consensus, or a hung result |\n| Elimination Tournament | All-pay elimination | Aggressive early, conservative late |\n| Adversarial Collaboration | Two-player, pre-committed | Maximum honest disclosure |\n\n**The research question** (not yet a built feature — see [RESEARCH.md](RESEARCH.md)): do AI agents converge on Nash Equilibrium predictions when governed by protocols that formally instantiate known game structures? If yes — protocol selection becomes a mechanism design problem. If no — why do agents deviate? Either result is publishable.\n\n---\n\n## Business Disruption\n\n### Jira is a database humans are required to keep updated. Hansard is a database that is impossible to not keep updated.\n\nThat is not a feature comparison. It is a category difference.\n\n| Jira | Politik |\n|---|---|\n| Developer types ticket title | Motion title in Hansard |\n| Developer estimates story points | LEDGER — exact elapsed, tokens, dollars |\n| Someone manually assigns reviewer | Division record — attributed votes |\n| Developer links commits manually | Every governance act is its own commit — the git history is the audit trail |\n| Developer manually closes ticket | Prorogation — one command, with the terminating trigger recorded |\n| Cost tracking is finance's estimate | LEDGER — actual cost per decision |\n\nPolitik produces a superior project record as a **zero-overhead side effect** of running governed sessions. Nobody updates it. Nobody logs time. It is all there because it cannot be otherwise.\n\n### GitHub Alignment\n\nA session is a git repository, so Politik runs anywhere git does. Point it at a GitHub repo and governance acts additionally project onto the platform — a Motion becomes a pull request, a Division a review request, an Escalation an issue, Assent a merge — and a shipped Actions workflow emails the Speaker when an escalation is filed. Agents run in GitHub Actions like any other CLI. The projection is optional; without it a session is complete and correct on git alone.\n\n### Open Source\n\nMIT licensed. The entire framework — CANON, protocol library, session engine, Hansard substrate, CLI tooling, reference implementation — is open source.\n\n---\n\n**Attribution:** Steve Krisjanovs, Cordfuse  \n**Architecture:** [POLITIK-ARCHITECTURE.md](POLITIK-ARCHITECTURE.md) · [PROTOCOLS.md](PROTOCOLS.md) · [RUNTIME.md](RUNTIME.md) · [RESEARCH.md](RESEARCH.md) · [EXECUTION.md](EXECUTION.md)  \n**DOI:** [10.5281/zenodo.19490358](https://doi.org/10.5281/zenodo.19490358) (concept DOI — always resolves to the latest version)  \n**License:** MIT\n","readmeFilename":"README.md"}