polyctl 0.7.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- polyctl-0.7.0/.gitignore +29 -0
- polyctl-0.7.0/LICENSE +21 -0
- polyctl-0.7.0/PKG-INFO +235 -0
- polyctl-0.7.0/README.md +190 -0
- polyctl-0.7.0/README.tr.md +189 -0
- polyctl-0.7.0/docs/adapters.md +1260 -0
- polyctl-0.7.0/docs/adr/0001-durable-jsonl-storage.md +78 -0
- polyctl-0.7.0/docs/adr/0002-immutable-index-candidate-authority.md +78 -0
- polyctl-0.7.0/docs/adr/0003-declarative-capability-routing.md +84 -0
- polyctl-0.7.0/docs/adr/README.md +26 -0
- polyctl-0.7.0/docs/alarms.md +317 -0
- polyctl-0.7.0/docs/audit/2026-09-08-adversarial.md +1337 -0
- polyctl-0.7.0/docs/audit/2026-09-08-closure.md +105 -0
- polyctl-0.7.0/docs/audit/2026-10-15-warp-store.md +188 -0
- polyctl-0.7.0/docs/audit/2026-10-16-harness-measure.md +156 -0
- polyctl-0.7.0/docs/audit/2026-10-16-review-collect.md +131 -0
- polyctl-0.7.0/docs/audit/2026-10-18-agy-1-4-reviewer.md +64 -0
- polyctl-0.7.0/docs/backlog.md +221 -0
- polyctl-0.7.0/docs/capability-matrix.md +158 -0
- polyctl-0.7.0/docs/cloud.md +119 -0
- polyctl-0.7.0/docs/commands.md +114 -0
- polyctl-0.7.0/docs/commands.tr.md +108 -0
- polyctl-0.7.0/docs/configuration.md +239 -0
- polyctl-0.7.0/docs/demo.md +205 -0
- polyctl-0.7.0/docs/donor.md +47 -0
- polyctl-0.7.0/docs/evidence.md +139 -0
- polyctl-0.7.0/docs/fanout.md +64 -0
- polyctl-0.7.0/docs/features.md +235 -0
- polyctl-0.7.0/docs/gates.md +413 -0
- polyctl-0.7.0/docs/getting-started.md +308 -0
- polyctl-0.7.0/docs/github-action.md +140 -0
- polyctl-0.7.0/docs/ide-extensions.md +64 -0
- polyctl-0.7.0/docs/keyflip.md +162 -0
- polyctl-0.7.0/docs/ledger.md +278 -0
- polyctl-0.7.0/docs/lessons.md +510 -0
- polyctl-0.7.0/docs/mcp.md +432 -0
- polyctl-0.7.0/docs/messaging.md +281 -0
- polyctl-0.7.0/docs/models.md +78 -0
- polyctl-0.7.0/docs/parallel.md +273 -0
- polyctl-0.7.0/docs/pipeline.md +345 -0
- polyctl-0.7.0/docs/pr.md +93 -0
- polyctl-0.7.0/docs/privacy.md +164 -0
- polyctl-0.7.0/docs/profiles.md +107 -0
- polyctl-0.7.0/docs/protocol.md +396 -0
- polyctl-0.7.0/docs/recovery.md +173 -0
- polyctl-0.7.0/docs/release.md +132 -0
- polyctl-0.7.0/docs/roles.md +458 -0
- polyctl-0.7.0/docs/safety.md +1037 -0
- polyctl-0.7.0/docs/slices/SECRETS-2.md +53 -0
- polyctl-0.7.0/docs/slices/TRIAGE-3-MEDIUM.md +57 -0
- polyctl-0.7.0/docs/slices.md +397 -0
- polyctl-0.7.0/docs/sources.md +128 -0
- polyctl-0.7.0/docs/standin.md +153 -0
- polyctl-0.7.0/docs/surfaces.md +319 -0
- polyctl-0.7.0/docs/telegram.md +153 -0
- polyctl-0.7.0/docs/telemetry.md +395 -0
- polyctl-0.7.0/docs/threat-model.md +96 -0
- polyctl-0.7.0/docs/upstream.md +184 -0
- polyctl-0.7.0/docs/watchdog.md +503 -0
- polyctl-0.7.0/docs/windows.md +426 -0
- polyctl-0.7.0/pyproject.toml +67 -0
- polyctl-0.7.0/scripts/README.md +96 -0
- polyctl-0.7.0/src/polyctl/__init__.py +7 -0
- polyctl-0.7.0/src/polyctl/__main__.py +5 -0
- polyctl-0.7.0/src/polyctl/a2a.py +226 -0
- polyctl-0.7.0/src/polyctl/a2a_mcp.py +546 -0
- polyctl-0.7.0/src/polyctl/acp.py +417 -0
- polyctl-0.7.0/src/polyctl/adapters/README.md +101 -0
- polyctl-0.7.0/src/polyctl/adapters/aider.json +32 -0
- polyctl-0.7.0/src/polyctl/adapters/amazon-q.json +15 -0
- polyctl-0.7.0/src/polyctl/adapters/amp.json +16 -0
- polyctl-0.7.0/src/polyctl/adapters/antigravity.json +120 -0
- polyctl-0.7.0/src/polyctl/adapters/claude-code.json +229 -0
- polyctl-0.7.0/src/polyctl/adapters/cloud-generic.json +57 -0
- polyctl-0.7.0/src/polyctl/adapters/codex.json +47 -0
- polyctl-0.7.0/src/polyctl/adapters/command-code.json +45 -0
- polyctl-0.7.0/src/polyctl/adapters/copilot.json +17 -0
- polyctl-0.7.0/src/polyctl/adapters/cursor-agent.json +29 -0
- polyctl-0.7.0/src/polyctl/adapters/deepseek.json +13 -0
- polyctl-0.7.0/src/polyctl/adapters/droid.json +34 -0
- polyctl-0.7.0/src/polyctl/adapters/gemini.json +30 -0
- polyctl-0.7.0/src/polyctl/adapters/grok.json +22 -0
- polyctl-0.7.0/src/polyctl/adapters/hermes.json +34 -0
- polyctl-0.7.0/src/polyctl/adapters/kilocode.json +30 -0
- polyctl-0.7.0/src/polyctl/adapters/kimi.json +23 -0
- polyctl-0.7.0/src/polyctl/adapters/kiro.json +332 -0
- polyctl-0.7.0/src/polyctl/adapters/ollama.json +29 -0
- polyctl-0.7.0/src/polyctl/adapters/omp.json +34 -0
- polyctl-0.7.0/src/polyctl/adapters/openai-api.json +68 -0
- polyctl-0.7.0/src/polyctl/adapters/opencode.json +162 -0
- polyctl-0.7.0/src/polyctl/adapters/pi.json +24 -0
- polyctl-0.7.0/src/polyctl/adapters/pr-agent.json +54 -0
- polyctl-0.7.0/src/polyctl/adapters/profiles.json +9 -0
- polyctl-0.7.0/src/polyctl/adapters/qoder.json +163 -0
- polyctl-0.7.0/src/polyctl/adapters/qwen.json +27 -0
- polyctl-0.7.0/src/polyctl/adapters/reasonix.json +25 -0
- polyctl-0.7.0/src/polyctl/adapters/rewriters/rtk.json +24 -0
- polyctl-0.7.0/src/polyctl/adapters/trae.json +31 -0
- polyctl-0.7.0/src/polyctl/adapters/vendors.json +42 -0
- polyctl-0.7.0/src/polyctl/adapters/warp.json +88 -0
- polyctl-0.7.0/src/polyctl/allowlist.py +1756 -0
- polyctl-0.7.0/src/polyctl/api_review.py +920 -0
- polyctl-0.7.0/src/polyctl/cli.py +835 -0
- polyctl-0.7.0/src/polyctl/conformance_harness.py +9 -0
- polyctl-0.7.0/src/polyctl/demo.py +503 -0
- polyctl-0.7.0/src/polyctl/drivers.py +146 -0
- polyctl-0.7.0/src/polyctl/email.py +160 -0
- polyctl-0.7.0/src/polyctl/features.py +98 -0
- polyctl-0.7.0/src/polyctl/journal.py +144 -0
- polyctl-0.7.0/src/polyctl/language.py +945 -0
- polyctl-0.7.0/src/polyctl/lib.py +1296 -0
- polyctl-0.7.0/src/polyctl/matrix.py +660 -0
- polyctl-0.7.0/src/polyctl/mcp.py +1362 -0
- polyctl-0.7.0/src/polyctl/ntfy.py +169 -0
- polyctl-0.7.0/src/polyctl/outbound.py +39 -0
- polyctl-0.7.0/src/polyctl/parts/__init__.py +5 -0
- polyctl-0.7.0/src/polyctl/parts/cli_authority.py +2615 -0
- polyctl-0.7.0/src/polyctl/parts/cli_channels.py +1325 -0
- polyctl-0.7.0/src/polyctl/parts/cli_checks.py +2293 -0
- polyctl-0.7.0/src/polyctl/parts/cli_completion.py +686 -0
- polyctl-0.7.0/src/polyctl/parts/cli_evidence.py +141 -0
- polyctl-0.7.0/src/polyctl/parts/cli_gain.py +375 -0
- polyctl-0.7.0/src/polyctl/parts/cli_harness.py +392 -0
- polyctl-0.7.0/src/polyctl/parts/cli_hooks.py +1816 -0
- polyctl-0.7.0/src/polyctl/parts/cli_install.py +638 -0
- polyctl-0.7.0/src/polyctl/parts/cli_lanes.py +106 -0
- polyctl-0.7.0/src/polyctl/parts/cli_maintenance.py +2536 -0
- polyctl-0.7.0/src/polyctl/parts/cli_next.py +248 -0
- polyctl-0.7.0/src/polyctl/parts/cli_pr.py +53 -0
- polyctl-0.7.0/src/polyctl/parts/cli_project.py +2857 -0
- polyctl-0.7.0/src/polyctl/parts/cli_review.py +5158 -0
- polyctl-0.7.0/src/polyctl/parts/cli_status.py +898 -0
- polyctl-0.7.0/src/polyctl/parts/lib_adapters.py +2933 -0
- polyctl-0.7.0/src/polyctl/parts/lib_alarms.py +2106 -0
- polyctl-0.7.0/src/polyctl/parts/lib_events.py +224 -0
- polyctl-0.7.0/src/polyctl/parts/lib_evidence.py +412 -0
- polyctl-0.7.0/src/polyctl/parts/lib_gates.py +2099 -0
- polyctl-0.7.0/src/polyctl/parts/lib_lanes.py +829 -0
- polyctl-0.7.0/src/polyctl/parts/lib_mail.py +1541 -0
- polyctl-0.7.0/src/polyctl/parts/lib_next.py +652 -0
- polyctl-0.7.0/src/polyctl/parts/lib_pr.py +331 -0
- polyctl-0.7.0/src/polyctl/parts/lib_slices.py +3337 -0
- polyctl-0.7.0/src/polyctl/parts/lib_state.py +2415 -0
- polyctl-0.7.0/src/polyctl/parts/lib_transcript.py +4118 -0
- polyctl-0.7.0/src/polyctl/pressure.py +325 -0
- polyctl-0.7.0/src/polyctl/prices.json +47 -0
- polyctl-0.7.0/src/polyctl/procs.py +1194 -0
- polyctl-0.7.0/src/polyctl/settings.py +505 -0
- polyctl-0.7.0/src/polyctl/skill/SKILL.md +365 -0
- polyctl-0.7.0/src/polyctl/skillkit.py +503 -0
- polyctl-0.7.0/src/polyctl/storage.py +2055 -0
- polyctl-0.7.0/src/polyctl/telegram.py +327 -0
- polyctl-0.7.0/src/polyctl/tiers.py +123 -0
- polyctl-0.7.0/src/polyctl/verdicts.py +41 -0
- polyctl-0.7.0/src/polyctl/watchdog.py +3887 -0
- polyctl-0.7.0/src/polyctl/web.py +337 -0
polyctl-0.7.0/.gitignore
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
agent-mail/
|
|
2
|
+
node_modules/
|
|
3
|
+
*.log
|
|
4
|
+
.DS_Store
|
|
5
|
+
|
|
6
|
+
# Python bytecode is never source
|
|
7
|
+
__pycache__/
|
|
8
|
+
*.pyc
|
|
9
|
+
# ledger lock sidecars (polyctl storage)
|
|
10
|
+
.polyctl/ledger/*.lock
|
|
11
|
+
|
|
12
|
+
# mail is transient; the ledger and reviews are not
|
|
13
|
+
agent-mail/*.md
|
|
14
|
+
!agent-mail/README.md
|
|
15
|
+
.polyctl/inbox/
|
|
16
|
+
.polyctl/hold
|
|
17
|
+
.polyctl/sessions.json
|
|
18
|
+
.polyctl/lanes/
|
|
19
|
+
|
|
20
|
+
# This repository is public, and its own .polyctl/ state is per-checkout development
|
|
21
|
+
# state: .polyctl/config.json carries absolute home paths, a session id and reviewer
|
|
22
|
+
# argv. .polyctl-project stays tracked; the state it points at stays on the machine.
|
|
23
|
+
# (Product repositories are different: their ledgers and reviews are evidence.)
|
|
24
|
+
.polyctl/
|
|
25
|
+
.claude/
|
|
26
|
+
.kiro/
|
|
27
|
+
.codex/
|
|
28
|
+
.mcp.json
|
|
29
|
+
semantic-review/
|
polyctl-0.7.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hakki Sagdic
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
polyctl-0.7.0/PKG-INFO
ADDED
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: polyctl
|
|
3
|
+
Version: 0.7.0
|
|
4
|
+
Summary: Your agents commit, every change is granted first or flagged: polyctl gates the change an agent staged, has a model of another family review it, refuses any other git commit in its hook, and flags a commit made around it.
|
|
5
|
+
Project-URL: Homepage, https://hakkisagdic.github.io/polyctl/
|
|
6
|
+
Project-URL: Source, https://github.com/hakkisagdic/polyctl
|
|
7
|
+
Project-URL: Documentation, https://github.com/hakkisagdic/polyctl/blob/main/docs/protocol.md
|
|
8
|
+
Author: Hakki Sagdic
|
|
9
|
+
License: MIT License
|
|
10
|
+
|
|
11
|
+
Copyright (c) 2026 Hakki Sagdic
|
|
12
|
+
|
|
13
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
14
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
15
|
+
in the Software without restriction, including without limitation the rights
|
|
16
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
17
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
18
|
+
furnished to do so, subject to the following conditions:
|
|
19
|
+
|
|
20
|
+
The above copyright notice and this permission notice shall be included in all
|
|
21
|
+
copies or substantial portions of the Software.
|
|
22
|
+
|
|
23
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
24
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
25
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
26
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
27
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
28
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
29
|
+
SOFTWARE.
|
|
30
|
+
License-File: LICENSE
|
|
31
|
+
Keywords: a2a,agents,ai,claude,codex,kiro,mcp,orchestration
|
|
32
|
+
Classifier: Development Status :: 4 - Beta
|
|
33
|
+
Classifier: Environment :: Console
|
|
34
|
+
Classifier: Intended Audience :: Developers
|
|
35
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
36
|
+
Classifier: Programming Language :: Python :: 3
|
|
37
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
38
|
+
Requires-Python: >=3.9
|
|
39
|
+
Provides-Extra: dev
|
|
40
|
+
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
|
|
41
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
42
|
+
Provides-Extra: pr-agent
|
|
43
|
+
Requires-Dist: pr-agent<0.46,>=0.45.0; (python_version >= '3.12') and extra == 'pr-agent'
|
|
44
|
+
Description-Content-Type: text/markdown
|
|
45
|
+
|
|
46
|
+
**English** | [Türkçe](README.tr.md)
|
|
47
|
+
|
|
48
|
+
# polyctl
|
|
49
|
+
|
|
50
|
+
**The code your AI agents commit is reviewed first, waived by a person, or flagged by polyctl.** By
|
|
51
|
+
default a model of another family reviews the exact change an agent staged, and a git hook refuses
|
|
52
|
+
anything else at `git commit`. A ledger records every decision; polyctl reviews a waived change after it
|
|
53
|
+
lands, and `polyctl doctor` and the watchdog flag a commit whose content no review or waiver granted.
|
|
54
|
+
A person can turn review off for a project, on the record, `polyctl features off review --by <name>`;
|
|
55
|
+
its commits then land on verification alone.
|
|
56
|
+
|
|
57
|
+
Keep the coding agents you already use: Claude Code, Codex, Kiro, Qoder, OpenCode and the others
|
|
58
|
+
in the table below. `polyctl` sits above them. It runs your gates on the exact change an agent staged,
|
|
59
|
+
has a model of another family review that change, and lets only that change commit. The hook
|
|
60
|
+
refuses everything else at `git commit`, and every decision goes into a ledger that shows
|
|
61
|
+
tampering.
|
|
62
|
+
|
|
63
|
+
polyctl 0.7.0 is built and supported on macOS; Linux runs the test suite in CI but is not a supported platform yet; on Windows 29 tests fail (WINDOWS-LANE-0.7, docs/backlog.md) and Windows waits for a later release.
|
|
64
|
+
|
|
65
|
+
## Why
|
|
66
|
+
|
|
67
|
+
- **Agents commit faster than anyone reads.** A test that passed on one tree says nothing about
|
|
68
|
+
the tree that gets committed. `polyctl` grants commit authority to one exact staged tree, and its
|
|
69
|
+
hook refuses any other.
|
|
70
|
+
- **A model reviewing its own family's work shares its blind spots.** The reviewer is of another
|
|
71
|
+
model family by default, or a person you name, and it runs with tools that only read.
|
|
72
|
+
- **You keep your tools.** `polyctl` reads each agent's own session store and drives its command line.
|
|
73
|
+
Adopting it does not mean restarting your work inside something new.
|
|
74
|
+
|
|
75
|
+
## Five minutes to the first reviewed commit
|
|
76
|
+
|
|
77
|
+
To see it first, `polyctl demo` plays one change through polyctl on a scratch project ([demo](docs/demo.md)).
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pip install polyctl # or: uv tool install polyctl
|
|
81
|
+
cd your-repository
|
|
82
|
+
polyctl init --profile agy-codex # agy (Gemini 4 Argon) implements, Codex (gpt-6-luna) reviews; or codex-agy, claude-codex
|
|
83
|
+
git add .polyctl-project .gitignore && git commit -m "adopt polyctl"
|
|
84
|
+
polyctl hooks install # from here on, only a granted candidate commits
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Then, for every change your agent stages:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
polyctl status # what your agents are doing, and what waits for you
|
|
91
|
+
polyctl verify # your gates, run on the staged candidate
|
|
92
|
+
polyctl review # a model of another family reviews exactly that candidate
|
|
93
|
+
polyctl commit-ok # may it land? decided from the evidence, refusals named
|
|
94
|
+
polyctl commit -m "feat: what changed" # commit it, bound to that evidence by its trailers
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
[Getting started](docs/getting-started.md) goes through it step by step, and `polyctl prove` runs the
|
|
98
|
+
guarantees on a throwaway candidate instead of describing them. [Profiles](docs/profiles.md)
|
|
99
|
+
offers three cross-family presets — `agy-codex` (`antigravity` `verified: full`, Gemini 4 Argon
|
|
100
|
+
implementer with `codex` `verified: partial`, `gpt-6-luna` reviewer), `codex-agy` (`codex`
|
|
101
|
+
`verified: partial`, `gpt-6-astra` implementer with `antigravity` `verified: full` read-only
|
|
102
|
+
reviewer agent on Gemini 4 Argon) and `claude-codex` (`claude-code` `verified: full` implementer
|
|
103
|
+
with `codex` `verified: partial`, `gpt-6-luna` reviewer), each with a `claude-code` (`verified:
|
|
104
|
+
full`) architect. With one harness for every role (`--implementer claude-code`), `polyctl init` asks
|
|
105
|
+
for a [review tier](docs/roles.md#review-tiers): another model of the same family, labelled as
|
|
106
|
+
weaker independence, or a person.
|
|
107
|
+
|
|
108
|
+
`polyctl status` names the most recently active secondary project while the primary session
|
|
109
|
+
is slowing, stopped or idle. `polyctl doctor` reports a script selected by `POLYCTL_GIT` and
|
|
110
|
+
unrecognised shell hooks as possible filters; see [gates](docs/gates.md).
|
|
111
|
+
|
|
112
|
+
## How a change lands
|
|
113
|
+
|
|
114
|
+
```text
|
|
115
|
+
the agent edits and stages
|
|
116
|
+
-> polyctl verify your gates, run again by something with no stake in the result
|
|
117
|
+
-> polyctl review another model family reads that candidate and the code around it
|
|
118
|
+
-> polyctl commit-ok commit authority for that exact tree, granted from the evidence
|
|
119
|
+
-> polyctl commit the commit carries trailers that bind it to the grant
|
|
120
|
+
the pre-commit hook refuses every other commit; push is never granted
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## What else it does
|
|
124
|
+
|
|
125
|
+
- **Watches.** `polyctl watch` is a live panel: what each agent is doing, context and cost, open
|
|
126
|
+
reviews, the board, and whether an agent is *busy but producing nothing*.
|
|
127
|
+
- **Restarts.** A watchdog notices a turn that stopped mid-work and nudges it - never into a
|
|
128
|
+
provider outage, past the round budget, or into a tree a person has taken, nor while hooks or
|
|
129
|
+
instructions an agent wrote there wait for a person to read them (`polyctl harness seen`).
|
|
130
|
+
- **Keeps going.** A board of pre-authorised work: a slice waiting on you is parked with its
|
|
131
|
+
reason, and when the queue runs dry the architect is woken to refill it.
|
|
132
|
+
- **Catches up.** A review you waive is recorded, and `polyctl catchup` has a reviewer of another
|
|
133
|
+
family review the landed range later.
|
|
134
|
+
- **Reviews safely.** A reviewer runs with tools that only read, and polyctl measures that per
|
|
135
|
+
harness: kiro-cli ran untrusted tools all the same with no person to ask, so a Kiro reviewer
|
|
136
|
+
runs as a read-only agent polyctl writes for it.
|
|
137
|
+
|
|
138
|
+
Every command is in [docs/commands.md](docs/commands.md).
|
|
139
|
+
|
|
140
|
+
## Install
|
|
141
|
+
|
|
142
|
+
`pip install polyctl`, `uv tool install polyctl`, or
|
|
143
|
+
`brew install hakkisagdic/tap/polyctl`. No dependencies, by choice: polyctl watches agents on
|
|
144
|
+
machines it does not control, and a dependency is a thing that can be missing exactly there. With
|
|
145
|
+
nothing installed, the Python macOS and most Linux distributions ship runs it from a clone:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
git clone https://github.com/hakkisagdic/polyctl ~/polyctl
|
|
149
|
+
mkdir -p ~/.local/bin && ln -s ~/polyctl/bin/polyctl ~/.local/bin/polyctl # ~/.local/bin must be on PATH
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
A symlink, not a shell alias: neither `/bin/sh`, which runs polyctl's commit hook, nor an agent the
|
|
153
|
+
watchdog starts without your shell can see an alias. On **Windows**, `bin/polyctl.ps1` (`bin/pctl.ps1`) covers `status`,
|
|
154
|
+
`board` and `doctor` with nothing installed; for the rest,
|
|
155
|
+
`winget install Python.Python.3.12 && pip install polyctl` ([windows](docs/windows.md)).
|
|
156
|
+
|
|
157
|
+
Install polyctl outside the projects it governs, never into a `.venv` inside one: an agent can write there,
|
|
158
|
+
and Python runs a `.pth` file it leaves before polyctl starts. polyctl names such a file and `polyctl doctor` names
|
|
159
|
+
an installation inside the tree ([safety](docs/safety.md#what-python-runs-as-it-starts-from-inside-the-tree)).
|
|
160
|
+
|
|
161
|
+
Until 0.7.0 polyctl was called ao, on PyPI ao-orchestrator, at github.com/hakkisagdic/agent-orchestrator (which GitHub now redirects); nothing of the old name is read any more - no command, variable, folder or format - and a project an older ao set up starts over with `polyctl init`.
|
|
162
|
+
|
|
163
|
+
> **Where this came from.** Extracted from a 30-epic durable-workflow product built
|
|
164
|
+
> over weeks by exactly this loop. Every guard in here exists because something went
|
|
165
|
+
> wrong first: a watchdog that started a second turn on one session and left a rename
|
|
166
|
+
> half-applied; fifteen agent processes accumulated in one repository; a timestamp bug
|
|
167
|
+
> that made live evidence look three hours stale. [`docs/lessons.md`](docs/lessons.md)
|
|
168
|
+
> is the list. None of it was designed in advance.
|
|
169
|
+
|
|
170
|
+
## The rules it enforces
|
|
171
|
+
|
|
172
|
+
These are not style preferences. Each one is a failure that cost real hours.
|
|
173
|
+
|
|
174
|
+
- **Whoever writes the code does not verify it, and does not decide it may land.**
|
|
175
|
+
- **A plan is read, never edited** — when the document a slice is judged against can be
|
|
176
|
+
edited by the thing being judged, every later check is circular.
|
|
177
|
+
- **Pulling work is not authorising it.** A tracker item is something a person wrote,
|
|
178
|
+
not a specification anyone verified. It enters the queue with a written acceptance
|
|
179
|
+
boundary or it does not enter.
|
|
180
|
+
- **Heavy operations belong to one actor.** Gates are serialised machine-wide; N
|
|
181
|
+
projects running N test suites is not N times the throughput, it is one suite that
|
|
182
|
+
no longer finishes.
|
|
183
|
+
- **Authority lives in always-included context, never in a mailbox.** A stuck agent is
|
|
184
|
+
exactly the agent not reading its mail.
|
|
185
|
+
- **`push` is never granted by this tool.** Nor PRs, force-pushes, or hook bypasses.
|
|
186
|
+
|
|
187
|
+
## Agent support
|
|
188
|
+
|
|
189
|
+
`polyctl` reads each agent's own session store; the adapter says where and in what shape.
|
|
190
|
+
|
|
191
|
+
| verified | adapters |
|
|
192
|
+
|---|---|
|
|
193
|
+
| **full** — every capability exercised in a production run | kiro, claude-code, antigravity |
|
|
194
|
+
| **partial** — reads state, some capabilities unexercised | opencode, command-code, codex, qoder, openai-api, warp |
|
|
195
|
+
| **documented** — written from published docs, not yet run | cursor-agent |
|
|
196
|
+
| **untested** — schema present, needs a first run | gemini, aider, amp, copilot, amazon-q, deepseek, ollama, droid, grok, hermes, kilocode, kimi, omp, pi, pr-agent, qwen, reasonix, trae |
|
|
197
|
+
|
|
198
|
+
Warp uses `oz`; polyctl finds it in the Warp app bundle under `/Applications` or
|
|
199
|
+
`~/Applications` even when it is off PATH. `polyctl init --agent warp` uses the
|
|
200
|
+
files-only setup: no Warp MCP registration. Replies and sessions remain
|
|
201
|
+
unmeasured, and Warp is ineligible as a reviewer. See the [measurement](docs/audit/2026-10-15-warp-store.md).
|
|
202
|
+
|
|
203
|
+
`polyctl adapters` shows this table against what is actually installed on your machine, and
|
|
204
|
+
— with [keyflip](https://github.com/hakkisagdic/keyflip) — whether an account exists
|
|
205
|
+
even when the CLI does not. Adding one is a JSON file; see
|
|
206
|
+
[`docs/adapters.md`](docs/adapters.md).
|
|
207
|
+
|
|
208
|
+
The suite runs on Linux, macOS and Windows with Python 3.9 and 3.12, on hosted runners and
|
|
209
|
+
locally before every push ([commands](docs/commands.md#tests)).
|
|
210
|
+
|
|
211
|
+
## Documentation
|
|
212
|
+
|
|
213
|
+
**[getting started](docs/getting-started.md)** · **[commands](docs/commands.md)** ·
|
|
214
|
+
[protocol](docs/protocol.md) · [safety](docs/safety.md) · [threat model](docs/threat-model.md) · [roles](docs/roles.md) ·
|
|
215
|
+
[privacy](docs/privacy.md) · [security policy](SECURITY.md) ·
|
|
216
|
+
[capability matrix](docs/capability-matrix.md) ·
|
|
217
|
+
[architecture decisions](docs/adr/README.md) ·
|
|
218
|
+
[slices](docs/slices.md) · [gates](docs/gates.md) · [sources](docs/sources.md) ·
|
|
219
|
+
[adapters](docs/adapters.md) · [parallel](docs/parallel.md) · [cloud](docs/cloud.md) ·
|
|
220
|
+
[models](docs/models.md) · [telegram](docs/telegram.md) · [mcp](docs/mcp.md) · [telemetry](docs/telemetry.md) ·
|
|
221
|
+
[surfaces](docs/surfaces.md) · [ledger](docs/ledger.md) · [recovery](docs/recovery.md) ·
|
|
222
|
+
[keyflip](docs/keyflip.md) · [ide-extensions](docs/ide-extensions.md) ·
|
|
223
|
+
**[lessons](docs/lessons.md)**
|
|
224
|
+
|
|
225
|
+
## Status
|
|
226
|
+
|
|
227
|
+
Working today: every command in [the command list](docs/commands.md), exercised daily against a real
|
|
228
|
+
project. Still specification: every passage the documents mark as not built yet, read lanes,
|
|
229
|
+
a lane's role and the merge queue among them, and cross-project parallel *execution* (the
|
|
230
|
+
view exists; running several implementers at once is governed by the machine gate lock but
|
|
231
|
+
has not been run in anger).
|
|
232
|
+
|
|
233
|
+
What polyctl's own ledgers show about the guarantee on this repository, measured: [evidence](docs/evidence.md).
|
|
234
|
+
|
|
235
|
+
MIT.
|
polyctl-0.7.0/README.md
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
**English** | [Türkçe](README.tr.md)
|
|
2
|
+
|
|
3
|
+
# polyctl
|
|
4
|
+
|
|
5
|
+
**The code your AI agents commit is reviewed first, waived by a person, or flagged by polyctl.** By
|
|
6
|
+
default a model of another family reviews the exact change an agent staged, and a git hook refuses
|
|
7
|
+
anything else at `git commit`. A ledger records every decision; polyctl reviews a waived change after it
|
|
8
|
+
lands, and `polyctl doctor` and the watchdog flag a commit whose content no review or waiver granted.
|
|
9
|
+
A person can turn review off for a project, on the record, `polyctl features off review --by <name>`;
|
|
10
|
+
its commits then land on verification alone.
|
|
11
|
+
|
|
12
|
+
Keep the coding agents you already use: Claude Code, Codex, Kiro, Qoder, OpenCode and the others
|
|
13
|
+
in the table below. `polyctl` sits above them. It runs your gates on the exact change an agent staged,
|
|
14
|
+
has a model of another family review that change, and lets only that change commit. The hook
|
|
15
|
+
refuses everything else at `git commit`, and every decision goes into a ledger that shows
|
|
16
|
+
tampering.
|
|
17
|
+
|
|
18
|
+
polyctl 0.7.0 is built and supported on macOS; Linux runs the test suite in CI but is not a supported platform yet; on Windows 29 tests fail (WINDOWS-LANE-0.7, docs/backlog.md) and Windows waits for a later release.
|
|
19
|
+
|
|
20
|
+
## Why
|
|
21
|
+
|
|
22
|
+
- **Agents commit faster than anyone reads.** A test that passed on one tree says nothing about
|
|
23
|
+
the tree that gets committed. `polyctl` grants commit authority to one exact staged tree, and its
|
|
24
|
+
hook refuses any other.
|
|
25
|
+
- **A model reviewing its own family's work shares its blind spots.** The reviewer is of another
|
|
26
|
+
model family by default, or a person you name, and it runs with tools that only read.
|
|
27
|
+
- **You keep your tools.** `polyctl` reads each agent's own session store and drives its command line.
|
|
28
|
+
Adopting it does not mean restarting your work inside something new.
|
|
29
|
+
|
|
30
|
+
## Five minutes to the first reviewed commit
|
|
31
|
+
|
|
32
|
+
To see it first, `polyctl demo` plays one change through polyctl on a scratch project ([demo](docs/demo.md)).
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install polyctl # or: uv tool install polyctl
|
|
36
|
+
cd your-repository
|
|
37
|
+
polyctl init --profile agy-codex # agy (Gemini 4 Argon) implements, Codex (gpt-6-luna) reviews; or codex-agy, claude-codex
|
|
38
|
+
git add .polyctl-project .gitignore && git commit -m "adopt polyctl"
|
|
39
|
+
polyctl hooks install # from here on, only a granted candidate commits
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Then, for every change your agent stages:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
polyctl status # what your agents are doing, and what waits for you
|
|
46
|
+
polyctl verify # your gates, run on the staged candidate
|
|
47
|
+
polyctl review # a model of another family reviews exactly that candidate
|
|
48
|
+
polyctl commit-ok # may it land? decided from the evidence, refusals named
|
|
49
|
+
polyctl commit -m "feat: what changed" # commit it, bound to that evidence by its trailers
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
[Getting started](docs/getting-started.md) goes through it step by step, and `polyctl prove` runs the
|
|
53
|
+
guarantees on a throwaway candidate instead of describing them. [Profiles](docs/profiles.md)
|
|
54
|
+
offers three cross-family presets — `agy-codex` (`antigravity` `verified: full`, Gemini 4 Argon
|
|
55
|
+
implementer with `codex` `verified: partial`, `gpt-6-luna` reviewer), `codex-agy` (`codex`
|
|
56
|
+
`verified: partial`, `gpt-6-astra` implementer with `antigravity` `verified: full` read-only
|
|
57
|
+
reviewer agent on Gemini 4 Argon) and `claude-codex` (`claude-code` `verified: full` implementer
|
|
58
|
+
with `codex` `verified: partial`, `gpt-6-luna` reviewer), each with a `claude-code` (`verified:
|
|
59
|
+
full`) architect. With one harness for every role (`--implementer claude-code`), `polyctl init` asks
|
|
60
|
+
for a [review tier](docs/roles.md#review-tiers): another model of the same family, labelled as
|
|
61
|
+
weaker independence, or a person.
|
|
62
|
+
|
|
63
|
+
`polyctl status` names the most recently active secondary project while the primary session
|
|
64
|
+
is slowing, stopped or idle. `polyctl doctor` reports a script selected by `POLYCTL_GIT` and
|
|
65
|
+
unrecognised shell hooks as possible filters; see [gates](docs/gates.md).
|
|
66
|
+
|
|
67
|
+
## How a change lands
|
|
68
|
+
|
|
69
|
+
```text
|
|
70
|
+
the agent edits and stages
|
|
71
|
+
-> polyctl verify your gates, run again by something with no stake in the result
|
|
72
|
+
-> polyctl review another model family reads that candidate and the code around it
|
|
73
|
+
-> polyctl commit-ok commit authority for that exact tree, granted from the evidence
|
|
74
|
+
-> polyctl commit the commit carries trailers that bind it to the grant
|
|
75
|
+
the pre-commit hook refuses every other commit; push is never granted
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
## What else it does
|
|
79
|
+
|
|
80
|
+
- **Watches.** `polyctl watch` is a live panel: what each agent is doing, context and cost, open
|
|
81
|
+
reviews, the board, and whether an agent is *busy but producing nothing*.
|
|
82
|
+
- **Restarts.** A watchdog notices a turn that stopped mid-work and nudges it - never into a
|
|
83
|
+
provider outage, past the round budget, or into a tree a person has taken, nor while hooks or
|
|
84
|
+
instructions an agent wrote there wait for a person to read them (`polyctl harness seen`).
|
|
85
|
+
- **Keeps going.** A board of pre-authorised work: a slice waiting on you is parked with its
|
|
86
|
+
reason, and when the queue runs dry the architect is woken to refill it.
|
|
87
|
+
- **Catches up.** A review you waive is recorded, and `polyctl catchup` has a reviewer of another
|
|
88
|
+
family review the landed range later.
|
|
89
|
+
- **Reviews safely.** A reviewer runs with tools that only read, and polyctl measures that per
|
|
90
|
+
harness: kiro-cli ran untrusted tools all the same with no person to ask, so a Kiro reviewer
|
|
91
|
+
runs as a read-only agent polyctl writes for it.
|
|
92
|
+
|
|
93
|
+
Every command is in [docs/commands.md](docs/commands.md).
|
|
94
|
+
|
|
95
|
+
## Install
|
|
96
|
+
|
|
97
|
+
`pip install polyctl`, `uv tool install polyctl`, or
|
|
98
|
+
`brew install hakkisagdic/tap/polyctl`. No dependencies, by choice: polyctl watches agents on
|
|
99
|
+
machines it does not control, and a dependency is a thing that can be missing exactly there. With
|
|
100
|
+
nothing installed, the Python macOS and most Linux distributions ship runs it from a clone:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
git clone https://github.com/hakkisagdic/polyctl ~/polyctl
|
|
104
|
+
mkdir -p ~/.local/bin && ln -s ~/polyctl/bin/polyctl ~/.local/bin/polyctl # ~/.local/bin must be on PATH
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
A symlink, not a shell alias: neither `/bin/sh`, which runs polyctl's commit hook, nor an agent the
|
|
108
|
+
watchdog starts without your shell can see an alias. On **Windows**, `bin/polyctl.ps1` (`bin/pctl.ps1`) covers `status`,
|
|
109
|
+
`board` and `doctor` with nothing installed; for the rest,
|
|
110
|
+
`winget install Python.Python.3.12 && pip install polyctl` ([windows](docs/windows.md)).
|
|
111
|
+
|
|
112
|
+
Install polyctl outside the projects it governs, never into a `.venv` inside one: an agent can write there,
|
|
113
|
+
and Python runs a `.pth` file it leaves before polyctl starts. polyctl names such a file and `polyctl doctor` names
|
|
114
|
+
an installation inside the tree ([safety](docs/safety.md#what-python-runs-as-it-starts-from-inside-the-tree)).
|
|
115
|
+
|
|
116
|
+
Until 0.7.0 polyctl was called ao, on PyPI ao-orchestrator, at github.com/hakkisagdic/agent-orchestrator (which GitHub now redirects); nothing of the old name is read any more - no command, variable, folder or format - and a project an older ao set up starts over with `polyctl init`.
|
|
117
|
+
|
|
118
|
+
> **Where this came from.** Extracted from a 30-epic durable-workflow product built
|
|
119
|
+
> over weeks by exactly this loop. Every guard in here exists because something went
|
|
120
|
+
> wrong first: a watchdog that started a second turn on one session and left a rename
|
|
121
|
+
> half-applied; fifteen agent processes accumulated in one repository; a timestamp bug
|
|
122
|
+
> that made live evidence look three hours stale. [`docs/lessons.md`](docs/lessons.md)
|
|
123
|
+
> is the list. None of it was designed in advance.
|
|
124
|
+
|
|
125
|
+
## The rules it enforces
|
|
126
|
+
|
|
127
|
+
These are not style preferences. Each one is a failure that cost real hours.
|
|
128
|
+
|
|
129
|
+
- **Whoever writes the code does not verify it, and does not decide it may land.**
|
|
130
|
+
- **A plan is read, never edited** — when the document a slice is judged against can be
|
|
131
|
+
edited by the thing being judged, every later check is circular.
|
|
132
|
+
- **Pulling work is not authorising it.** A tracker item is something a person wrote,
|
|
133
|
+
not a specification anyone verified. It enters the queue with a written acceptance
|
|
134
|
+
boundary or it does not enter.
|
|
135
|
+
- **Heavy operations belong to one actor.** Gates are serialised machine-wide; N
|
|
136
|
+
projects running N test suites is not N times the throughput, it is one suite that
|
|
137
|
+
no longer finishes.
|
|
138
|
+
- **Authority lives in always-included context, never in a mailbox.** A stuck agent is
|
|
139
|
+
exactly the agent not reading its mail.
|
|
140
|
+
- **`push` is never granted by this tool.** Nor PRs, force-pushes, or hook bypasses.
|
|
141
|
+
|
|
142
|
+
## Agent support
|
|
143
|
+
|
|
144
|
+
`polyctl` reads each agent's own session store; the adapter says where and in what shape.
|
|
145
|
+
|
|
146
|
+
| verified | adapters |
|
|
147
|
+
|---|---|
|
|
148
|
+
| **full** — every capability exercised in a production run | kiro, claude-code, antigravity |
|
|
149
|
+
| **partial** — reads state, some capabilities unexercised | opencode, command-code, codex, qoder, openai-api, warp |
|
|
150
|
+
| **documented** — written from published docs, not yet run | cursor-agent |
|
|
151
|
+
| **untested** — schema present, needs a first run | gemini, aider, amp, copilot, amazon-q, deepseek, ollama, droid, grok, hermes, kilocode, kimi, omp, pi, pr-agent, qwen, reasonix, trae |
|
|
152
|
+
|
|
153
|
+
Warp uses `oz`; polyctl finds it in the Warp app bundle under `/Applications` or
|
|
154
|
+
`~/Applications` even when it is off PATH. `polyctl init --agent warp` uses the
|
|
155
|
+
files-only setup: no Warp MCP registration. Replies and sessions remain
|
|
156
|
+
unmeasured, and Warp is ineligible as a reviewer. See the [measurement](docs/audit/2026-10-15-warp-store.md).
|
|
157
|
+
|
|
158
|
+
`polyctl adapters` shows this table against what is actually installed on your machine, and
|
|
159
|
+
— with [keyflip](https://github.com/hakkisagdic/keyflip) — whether an account exists
|
|
160
|
+
even when the CLI does not. Adding one is a JSON file; see
|
|
161
|
+
[`docs/adapters.md`](docs/adapters.md).
|
|
162
|
+
|
|
163
|
+
The suite runs on Linux, macOS and Windows with Python 3.9 and 3.12, on hosted runners and
|
|
164
|
+
locally before every push ([commands](docs/commands.md#tests)).
|
|
165
|
+
|
|
166
|
+
## Documentation
|
|
167
|
+
|
|
168
|
+
**[getting started](docs/getting-started.md)** · **[commands](docs/commands.md)** ·
|
|
169
|
+
[protocol](docs/protocol.md) · [safety](docs/safety.md) · [threat model](docs/threat-model.md) · [roles](docs/roles.md) ·
|
|
170
|
+
[privacy](docs/privacy.md) · [security policy](SECURITY.md) ·
|
|
171
|
+
[capability matrix](docs/capability-matrix.md) ·
|
|
172
|
+
[architecture decisions](docs/adr/README.md) ·
|
|
173
|
+
[slices](docs/slices.md) · [gates](docs/gates.md) · [sources](docs/sources.md) ·
|
|
174
|
+
[adapters](docs/adapters.md) · [parallel](docs/parallel.md) · [cloud](docs/cloud.md) ·
|
|
175
|
+
[models](docs/models.md) · [telegram](docs/telegram.md) · [mcp](docs/mcp.md) · [telemetry](docs/telemetry.md) ·
|
|
176
|
+
[surfaces](docs/surfaces.md) · [ledger](docs/ledger.md) · [recovery](docs/recovery.md) ·
|
|
177
|
+
[keyflip](docs/keyflip.md) · [ide-extensions](docs/ide-extensions.md) ·
|
|
178
|
+
**[lessons](docs/lessons.md)**
|
|
179
|
+
|
|
180
|
+
## Status
|
|
181
|
+
|
|
182
|
+
Working today: every command in [the command list](docs/commands.md), exercised daily against a real
|
|
183
|
+
project. Still specification: every passage the documents mark as not built yet, read lanes,
|
|
184
|
+
a lane's role and the merge queue among them, and cross-project parallel *execution* (the
|
|
185
|
+
view exists; running several implementers at once is governed by the machine gate lock but
|
|
186
|
+
has not been run in anger).
|
|
187
|
+
|
|
188
|
+
What polyctl's own ledgers show about the guarantee on this repository, measured: [evidence](docs/evidence.md).
|
|
189
|
+
|
|
190
|
+
MIT.
|