polyctl 0.7.0__py3-none-any.whl
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/__init__.py +7 -0
- polyctl/__main__.py +5 -0
- polyctl/a2a.py +226 -0
- polyctl/a2a_mcp.py +546 -0
- polyctl/acp.py +417 -0
- polyctl/adapters/README.md +101 -0
- polyctl/adapters/aider.json +32 -0
- polyctl/adapters/amazon-q.json +15 -0
- polyctl/adapters/amp.json +16 -0
- polyctl/adapters/antigravity.json +120 -0
- polyctl/adapters/claude-code.json +229 -0
- polyctl/adapters/cloud-generic.json +57 -0
- polyctl/adapters/codex.json +47 -0
- polyctl/adapters/command-code.json +45 -0
- polyctl/adapters/copilot.json +17 -0
- polyctl/adapters/cursor-agent.json +29 -0
- polyctl/adapters/deepseek.json +13 -0
- polyctl/adapters/droid.json +34 -0
- polyctl/adapters/gemini.json +30 -0
- polyctl/adapters/grok.json +22 -0
- polyctl/adapters/hermes.json +34 -0
- polyctl/adapters/kilocode.json +30 -0
- polyctl/adapters/kimi.json +23 -0
- polyctl/adapters/kiro.json +332 -0
- polyctl/adapters/ollama.json +29 -0
- polyctl/adapters/omp.json +34 -0
- polyctl/adapters/openai-api.json +68 -0
- polyctl/adapters/opencode.json +162 -0
- polyctl/adapters/pi.json +24 -0
- polyctl/adapters/pr-agent.json +54 -0
- polyctl/adapters/profiles.json +9 -0
- polyctl/adapters/qoder.json +163 -0
- polyctl/adapters/qwen.json +27 -0
- polyctl/adapters/reasonix.json +25 -0
- polyctl/adapters/rewriters/rtk.json +24 -0
- polyctl/adapters/trae.json +31 -0
- polyctl/adapters/vendors.json +42 -0
- polyctl/adapters/warp.json +88 -0
- polyctl/allowlist.py +1756 -0
- polyctl/api_review.py +920 -0
- polyctl/cli.py +835 -0
- polyctl/conformance_harness.py +9 -0
- polyctl/demo.py +503 -0
- polyctl/drivers.py +146 -0
- polyctl/email.py +160 -0
- polyctl/features.py +98 -0
- polyctl/journal.py +144 -0
- polyctl/language.py +945 -0
- polyctl/lib.py +1296 -0
- polyctl/matrix.py +660 -0
- polyctl/mcp.py +1362 -0
- polyctl/ntfy.py +169 -0
- polyctl/outbound.py +39 -0
- polyctl/parts/__init__.py +5 -0
- polyctl/parts/cli_authority.py +2615 -0
- polyctl/parts/cli_channels.py +1325 -0
- polyctl/parts/cli_checks.py +2293 -0
- polyctl/parts/cli_completion.py +686 -0
- polyctl/parts/cli_evidence.py +141 -0
- polyctl/parts/cli_gain.py +375 -0
- polyctl/parts/cli_harness.py +392 -0
- polyctl/parts/cli_hooks.py +1816 -0
- polyctl/parts/cli_install.py +638 -0
- polyctl/parts/cli_lanes.py +106 -0
- polyctl/parts/cli_maintenance.py +2536 -0
- polyctl/parts/cli_next.py +248 -0
- polyctl/parts/cli_pr.py +53 -0
- polyctl/parts/cli_project.py +2857 -0
- polyctl/parts/cli_review.py +5158 -0
- polyctl/parts/cli_status.py +898 -0
- polyctl/parts/lib_adapters.py +2933 -0
- polyctl/parts/lib_alarms.py +2106 -0
- polyctl/parts/lib_events.py +224 -0
- polyctl/parts/lib_evidence.py +412 -0
- polyctl/parts/lib_gates.py +2099 -0
- polyctl/parts/lib_lanes.py +829 -0
- polyctl/parts/lib_mail.py +1541 -0
- polyctl/parts/lib_next.py +652 -0
- polyctl/parts/lib_pr.py +331 -0
- polyctl/parts/lib_slices.py +3337 -0
- polyctl/parts/lib_state.py +2415 -0
- polyctl/parts/lib_transcript.py +4118 -0
- polyctl/pressure.py +325 -0
- polyctl/prices.json +47 -0
- polyctl/procs.py +1194 -0
- polyctl/settings.py +505 -0
- polyctl/skill/SKILL.md +365 -0
- polyctl/skillkit.py +503 -0
- polyctl/storage.py +2055 -0
- polyctl/telegram.py +327 -0
- polyctl/tiers.py +123 -0
- polyctl/verdicts.py +41 -0
- polyctl/watchdog.py +3887 -0
- polyctl/web.py +337 -0
- polyctl-0.7.0.dist-info/METADATA +235 -0
- polyctl-0.7.0.dist-info/RECORD +99 -0
- polyctl-0.7.0.dist-info/WHEEL +4 -0
- polyctl-0.7.0.dist-info/entry_points.txt +5 -0
- polyctl-0.7.0.dist-info/licenses/LICENSE +21 -0
polyctl/skill/SKILL.md
ADDED
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: polyctl
|
|
3
|
+
description: Run a software project with agents the way polyctl (polyctl) expects — roles, the per-slice loop, authority, the mailbox protocol, single-writer checks, alarms, and every polyctl command. Use whenever a repository has a .polyctl/ directory, when asked to coordinate, implement, review or refill work under polyctl, or when a watchdog wakes you.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# polyctl playbook
|
|
7
|
+
|
|
8
|
+
<!-- polyctl-playbook v1 — generated by `polyctl skill install`; regenerate rather than edit -->
|
|
9
|
+
|
|
10
|
+
polyctl sits on the agent you already run. It adds no harness and no restart: a few
|
|
11
|
+
files under `.polyctl/`, a mailbox, an MCP server, an optional watchdog. Everything
|
|
12
|
+
below is what an orchestrating agent must know to behave correctly in such a
|
|
13
|
+
repository. The files are the protocol; MCP and the CLI are faster doors onto
|
|
14
|
+
the same room.
|
|
15
|
+
|
|
16
|
+
## 1. Roles, and what each may do
|
|
17
|
+
|
|
18
|
+
| role | decides | never |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| **human** | push, PR, force-push, hook bypass, epic boxes, architectural contracts, procurement, credentials | — |
|
|
21
|
+
| **architect** | scope: writes backlog slices with an *invariant* acceptance boundary; answers `polyctl_ask` decisions; judges anomalies; refills the queue; re-specifies over-budget slices | product code from a wake; polyctl's own source; push |
|
|
22
|
+
| **implementer** | how: works the first READY pre-authorised slice; gates, review, `polyctl commit-ok`, local commit | inventing scope; self-review; push; waiting silently |
|
|
23
|
+
| **reviewer** | verdict on a boundary: APPROVED / NEEDS_CHANGES with findings | reviewing its own work |
|
|
24
|
+
| **watchdog** | nothing — it measures and acts mechanically (nudge, reap, wake, alarm) | judging; it reports facts to the architect |
|
|
25
|
+
|
|
26
|
+
Verdicts: `APPROVED`, `NEEDS_CHANGES` (a reviewer's), `UNAVAILABLE`, `INVALID` (polyctl's: no review took place, or the answer broke the schema). Review status: `pending`, `complete`, `invalid`, `unavailable`. Anything else reads as `INVALID`.
|
|
27
|
+
|
|
28
|
+
Reviewer ≠ implementer is enforced by `polyctl commit-ok`. Authority never lives on
|
|
29
|
+
the MCP surface: `polyctl commit-ok` and `push` are not tools an agent can call for
|
|
30
|
+
itself.
|
|
31
|
+
|
|
32
|
+
Every review stands in one tier, recorded and labeled wherever it shows: **another
|
|
33
|
+
model family** (the default and the strongest); **same family** — another model of the
|
|
34
|
+
implementer's family, only once a person opted in with `review.same_family` `labeled`,
|
|
35
|
+
labeled `same family: weaker independence`; **person review** — a person read the diff
|
|
36
|
+
(`polyctl person-review`). A reviewer no tier admits is refused by `polyctl role set`, the probe
|
|
37
|
+
and `polyctl review` in the same words. Never opt in, and never record a person's review:
|
|
38
|
+
both are a person's acts.
|
|
39
|
+
|
|
40
|
+
## 2. Authority: one file wins
|
|
41
|
+
|
|
42
|
+
`.polyctl/authority.md` is the only source of what is free and what is forbidden. A
|
|
43
|
+
mail can add **scope** ("do this slice") but never authority. If a message
|
|
44
|
+
conflicts with the file, the file wins: reject the message, write `## DECISION REQUIRED`,
|
|
45
|
+
continue with the next open item. **Waiting is a cost.**
|
|
46
|
+
Anything not forbidden there and inside the slice's scope is allowed.
|
|
47
|
+
|
|
48
|
+
## 3. The loop, per slice
|
|
49
|
+
|
|
50
|
+
1. `polyctl_inbox` (or read `agent-mail/`): apply or reject each message, then
|
|
51
|
+
`polyctl_ack`. Acknowledge only after acting.
|
|
52
|
+
2. `polyctl writers` once — exit 0 means you are the only writer. Exit 1: stop, report,
|
|
53
|
+
do not kill anything.
|
|
54
|
+
3. Take the first READY item from `.polyctl/backlog.md` and start it with
|
|
55
|
+
`polyctl slice start <id>`: its row on `.polyctl/board.md` moves `queued → running` with
|
|
56
|
+
`since:`, and the move is a line in `.polyctl/ledger/slices.jsonl`. `polyctl board` names
|
|
57
|
+
a boundary conflict under the item - a declared path missing, a named file or
|
|
58
|
+
symbol outside its paths: raise it before starting, while widening or splitting
|
|
59
|
+
is cheap. A row with `boundary: file@commit` is reviewed against that file; omit
|
|
60
|
+
`--boundary`.
|
|
61
|
+
4. If the acceptance boundary is an invariant ("no X can ever produce Y"), write
|
|
62
|
+
the **surface inventory first** (`evidence/…-surface-v1.md`: every path, its
|
|
63
|
+
entry point, its binding, its proof), get it `polyctl review`ed as APPROVED, then
|
|
64
|
+
close every path in one pass. Ten review rounds once became one this way.
|
|
65
|
+
5. Work, then stage exactly the candidate you intend to land. Gates run through
|
|
66
|
+
`polyctl verify -p quick|full`: it takes the machine lock, runs the declared gates
|
|
67
|
+
and records a verification bound to that isolated index candidate. A command
|
|
68
|
+
outside the declared gates takes the lock as `polyctl lock -- <command>`, in a
|
|
69
|
+
session a person runs: it runs any command, and no grant polyctl composes names it.
|
|
70
|
+
6. `polyctl review --boundary "…"` — independent, on the same staged candidate and
|
|
71
|
+
boundary, never your own. Fix findings, restage, reverify and re-review. Over
|
|
72
|
+
the round budget? The architect re-specifies; do not grind. Exit 3 means no
|
|
73
|
+
reviewer could review (quota, login): not a round, not a verdict — park the
|
|
74
|
+
review, continue with the next READY item; the watchdog nudges when the
|
|
75
|
+
window reopens. Every structured review records the running slice ID and
|
|
76
|
+
reviewed boundary; round accounting accepts only completed prospective
|
|
77
|
+
reviews for that exact slice. A review for another slice at the same HEAD can
|
|
78
|
+
neither consume nor reset this slice's budget. `polyctl review --commits <range>`
|
|
79
|
+
is retrospective evidence only, never a round in the prospective budget and
|
|
80
|
+
never authority for a candidate.
|
|
81
|
+
With submitted reviews (`polyctl review submit`) the order each time you are free is:
|
|
82
|
+
a returned review first — land it or fold its findings into its slice; else
|
|
83
|
+
submit a green, code-complete slice and take the next READY item; else, with
|
|
84
|
+
`review.max_inflight` reviews running, keep developing. Never wait on a
|
|
85
|
+
reviewer, and never start new work while a returned review sits uncollected:
|
|
86
|
+
`polyctl status` names it and the watchdog raises it. A parked slice holds no slot.
|
|
87
|
+
7. `polyctl commit-ok --verify` — runs the quick gates itself when verification is
|
|
88
|
+
stale, then persists a grant only for the exact staged index candidate when
|
|
89
|
+
its verification and newest matching prospective review approve, that review
|
|
90
|
+
found every criterion the boundary lists met (numbered, or separated by
|
|
91
|
+
semicolons; a refusal names each one not met or never judged), no urgent
|
|
92
|
+
mail is unacknowledged, and no plan drift exists. Authority rows form a
|
|
93
|
+
predecessor hash chain; `polyctl commit-check` refuses a malformed or broken chain
|
|
94
|
+
before it considers a grant. Enforcement is enrolled only when the root
|
|
95
|
+
`.polyctl-project` has exact `polyctl-project-v1\n` bytes in HEAD or the active index;
|
|
96
|
+
`.polyctl/config.json` must then be a valid, non-empty top-level JSON object. Its
|
|
97
|
+
shared pre-dispatch/enforcement reader consumes at most 1,048,576 bytes and
|
|
98
|
+
rejects container nesting deeper than 64 before recursive JSON decoding. An
|
|
99
|
+
exact polyctl pre-commit body expresses only the static intent to run
|
|
100
|
+
`polyctl commit-check` against Git's active index. `polyctl hooks
|
|
101
|
+
status`, doctor, and init call Git's hook runner with an isolated synthetic
|
|
102
|
+
index; only polyctl's nonce-bound refusal is `installed (execution proved)`.
|
|
103
|
+
`polyctl hooks` resolves Git's effective path, never
|
|
104
|
+
overwrites foreign/protected content, and requires explicit
|
|
105
|
+
`--allow-shared-hooks` for the whole mutation set when any eligible target is
|
|
106
|
+
shared, external, or selected by global/system config. Then one local commit
|
|
107
|
+
with `polyctl commit -m "…"`, which runs the same authority check as the hook,
|
|
108
|
+
cannot skip it, and ends the message with the grant's Polyctl- trailers - leave
|
|
109
|
+
those lines out of the message. **No push.**
|
|
110
|
+
8. `polyctl_report {kind: "done"}`, board `running → done` with the gates named,
|
|
111
|
+
next item. Blocked by a decision? `polyctl_ask` with options, then
|
|
112
|
+
`polyctl slice block "…" --waiting decision` parks the slice under `blocked` with the
|
|
113
|
+
reason as its `needs:`; move to the next READY item — park and continue.
|
|
114
|
+
`--waiting human|architect|decision|external` says who it waits on:
|
|
115
|
+
`waiting: human` reaches a person directly. `polyctl slice start <id>` resumes a slice
|
|
116
|
+
you parked; a block the architect, a person or the watchdog made is theirs to
|
|
117
|
+
lift, and only the architect or a person drops a slice. With nothing READY
|
|
118
|
+
here, a nudge may name a secondary project's READY item: continue there.
|
|
119
|
+
|
|
120
|
+
**Working while the architect is away.** The architect is a person's quota and
|
|
121
|
+
attention, and both run out. What you settle alone: which READY item comes
|
|
122
|
+
next, how to split a slice that will not fit, whether a finding is in scope,
|
|
123
|
+
when to park and move on. What you never settle, however long nobody answers:
|
|
124
|
+
landing without an independent review, widening your own authority, anything
|
|
125
|
+
`.polyctl/authority.md` forbids. Blocked: record the question (`polyctl_ask`), park the
|
|
126
|
+
slice (`polyctl slice block "D-…"`) and take the next READY item. An unanswered
|
|
127
|
+
question never stops the queue, and it is never asked twice. The architect
|
|
128
|
+
answers the parked questions in one pass on return (`polyctl decisions`); `polyctl doctor`
|
|
129
|
+
shows how long it has been away and how many wait.
|
|
130
|
+
|
|
131
|
+
**When a rule is wrong.** The rules you work under - this playbook, a steering or
|
|
132
|
+
rule file, `.polyctl/authority.md`, a gate - are never yours to change because you judge
|
|
133
|
+
them wrong, however sure you are: only a person's decision, or a slice whose scope
|
|
134
|
+
names the change, touches them. Propose it:
|
|
135
|
+
`polyctl propose "…" --why "…" [--rule-file <path>]`, or `polyctl_propose`. It is recorded in
|
|
136
|
+
the decision ledger with the outcomes of the recent slices, and a person accepts or
|
|
137
|
+
rejects it; `polyctl decisions` shows the answer. Until then, work on under the rule as
|
|
138
|
+
it stands. The same change proposed twice is one proposal.
|
|
139
|
+
|
|
140
|
+
## 4. Talking: the mailbox and its tools
|
|
141
|
+
|
|
142
|
+
- Files: `agent-mail/<YYYYMMDD-HHMM>-<from>-to-<to>-<KIND>-<slug>.md`. Delivery
|
|
143
|
+
is by deletion: the receiver removes a message after acting on it. Every
|
|
144
|
+
message polyctl writes carries a front-matter envelope (`kind/from/to/slice/at/id`)
|
|
145
|
+
and is mirrored to `.polyctl/ledger/mail.jsonl` (`polyctl mail log`, `polyctl mail search`).
|
|
146
|
+
- Tools: `polyctl_inbox`, `polyctl_ack`, `polyctl_report {blocked|status|done}`, `polyctl_ask`
|
|
147
|
+
(options, answerable from a phone), `polyctl_decisions`, `polyctl_propose` (a change to a
|
|
148
|
+
rule, for a person to decide), `polyctl_status`, `polyctl_board`, `polyctl_next` (what stands
|
|
149
|
+
in the way now, and whose hand closes it), `polyctl_notices`, `polyctl_fanout`,
|
|
150
|
+
`polyctl_watchdog`.
|
|
151
|
+
- **One blocker, one report.** `polyctl_report` folds a repeat into the standing
|
|
152
|
+
file and returns `repeated: N`; when you see it, end the turn with one line.
|
|
153
|
+
Eighty copies of one request once produced eighty anomalies and forty wakes.
|
|
154
|
+
- **Urgent** from the architect (`## URGENT`) reaches you through
|
|
155
|
+
`polyctl lock`, `polyctl verify` and `polyctl commit-ok`, which refuse until acknowledged.
|
|
156
|
+
- **Markers** follow the project's `language` setting, English unless it is `tr`:
|
|
157
|
+
`## URGENT`, `## STOP`, `## DECISION REQUIRED`, and `URGENT` or `HANDOFF` as a file's
|
|
158
|
+
kind; in Turkish `## ACİL`, `## DUR`, `## KARAR GEREKLİ`, `ACIL` and `DEVIR`. Both
|
|
159
|
+
languages' markers are read in every project, so a message written in either is understood.
|
|
160
|
+
|
|
161
|
+
## 5. Measure before concluding
|
|
162
|
+
|
|
163
|
+
Never conclude from a name, a cwd, an mtime or a diff size. `polyctl status` (who is
|
|
164
|
+
working, quota, problems), `polyctl board` (READY / running / blocked with `needs:`),
|
|
165
|
+
`polyctl next` (which command stands in the way now, and whose hand holds it: a
|
|
166
|
+
person's items first, then the staged candidate's landing chain;
|
|
167
|
+
`polyctl next --short` prints the menu-bar line and dropdown lines for SwiftBar or
|
|
168
|
+
xbar, where a person runs `polyctl surfaces install|uninstall swiftbar --dir <dir>`
|
|
169
|
+
to write or remove polyctl's plugin in the folder named),
|
|
170
|
+
`polyctl doctor` (binaries, last wake, last tick, channels, live alarms),
|
|
171
|
+
`polyctl writers` (turns, not processes; orphans set aside), `polyctl watchdog explain`
|
|
172
|
+
(why the watchdog did or did not act, every measurement and verdict),
|
|
173
|
+
`polyctl since last` (what happened while you were away), `polyctl digest`.
|
|
174
|
+
Your shell's output may pass through a proxy that compresses it (`polyctl doctor` names
|
|
175
|
+
one, and its `measurement-filter` problem lists the measurement commands the proxy
|
|
176
|
+
rewrites): take a size, a path list or a count from polyctl's records, not from the terminal.
|
|
177
|
+
|
|
178
|
+
## 6. Alarms: who acts
|
|
179
|
+
|
|
180
|
+
| level | who | channel |
|
|
181
|
+
|---|---|---|
|
|
182
|
+
| yellow | the architect | mailbox anomaly + architect wake |
|
|
183
|
+
| orange | a person | desktop + Telegram / ntfy |
|
|
184
|
+
| red | a person, now | e-mail (an orange standing an hour; exhausted quota; failed wakes; a hold standing four hours) |
|
|
185
|
+
|
|
186
|
+
Set the channels up during setup, not after the first stall: `polyctl email setup`
|
|
187
|
+
(formsubmit.co, no server), `polyctl telegram setup` or `polyctl ntfy setup --topic-url <url>`.
|
|
188
|
+
`polyctl alarms` lists live episodes; `polyctl alarms test --level red` rings every channel for real.
|
|
189
|
+
|
|
190
|
+
## 7. The architect's routine
|
|
191
|
+
|
|
192
|
+
When woken by the watchdog, resumed after a quota pause (the desktop app's
|
|
193
|
+
auto-continue is a second resume path), or simply returning: **first**
|
|
194
|
+
`polyctl status`, `polyctl board`, `polyctl doctor`, then the mailbox — `*-to-<architect>-*` and
|
|
195
|
+
`watchdog-to-*-ANOMALY-*` — and the questions parked for you, `polyctl decisions`.
|
|
196
|
+
Watchdog files are facts, not verdicts. Decide, write decisions with
|
|
197
|
+
`polyctl decide "…" --scope <slice> --why "…"` (`--urgent` for `## URGENT`), answer
|
|
198
|
+
questions with `polyctl answer`, delete what you processed with
|
|
199
|
+
`polyctl mail ack <file-or-glob>`. Empty queue: refill from the specification with
|
|
200
|
+
invariant boundaries, or from a bound source by writing `.polyctl/inbox/` and running
|
|
201
|
+
`polyctl source import` — never leave an implementer waiting for lack of a slice.
|
|
202
|
+
Over-budget slice: re-specify (inventory first); the budget restarts at your
|
|
203
|
+
decision. A slice that will not be finished is dropped on the record with
|
|
204
|
+
`polyctl slice abandon --slice <id> --why "…"`, never deleted from the board, and a
|
|
205
|
+
block you made is lifted with `polyctl slice start <id>`. A wake edits
|
|
206
|
+
`.polyctl/backlog.md`, `.polyctl/board.md` and `.polyctl/inbox/` and no other file — never
|
|
207
|
+
product code, never polyctl's own source; `polyctl note` is the only
|
|
208
|
+
door to the mailbox you need. A rule proposal (`polyctl proposals`) waits for a person,
|
|
209
|
+
not for you: never answer one, and `polyctl answer` refuses it from a turn polyctl started. A
|
|
210
|
+
rule of your own that is wrong is proposed the same way, with `polyctl propose`.
|
|
211
|
+
|
|
212
|
+
## 8. Parallel agents
|
|
213
|
+
|
|
214
|
+
Worktrees per agent; the canonical checkout has one writer. Before any fan-out
|
|
215
|
+
of sub-agents: `polyctl fanout ok --agents N` (hard cap, recent limit hit, provider
|
|
216
|
+
window). After: `polyctl fanout record --agents N --done D --errors E --tokens T`.
|
|
217
|
+
|
|
218
|
+
## 9. Setup, once per repository
|
|
219
|
+
|
|
220
|
+
`polyctl start [--yes]` is a person's first-run wizard from nothing to a working, governed
|
|
221
|
+
project: it detects the installed agent CLIs and their model families, proposes a
|
|
222
|
+
cross-family implementer/reviewer pair (preferring measured `verified` levels), writes
|
|
223
|
+
the choice as a profile, asks before running `polyctl demo`, `polyctl init`, `polyctl hooks install`
|
|
224
|
+
and `polyctl prove` (`--yes` runs only the steps that need no person), and ends by listing
|
|
225
|
+
the steps only a person can take (`polyctl harness seen --ask`).
|
|
226
|
+
`polyctl init --profile agy-codex|codex-agy|claude-codex` writes `.polyctl/` (config with the role
|
|
227
|
+
blocks: who implements, reviews, judges; board, backlog, authority, gates), the exact
|
|
228
|
+
root `.polyctl-project` marker, the mailbox, this playbook, and the MCP registration. It
|
|
229
|
+
never stages `.polyctl-project`: a person includes that marker in the first authorized
|
|
230
|
+
candidate. Enforcement begins when its exact `polyctl-project-v1\n` bytes reach HEAD or
|
|
231
|
+
the active index. A project an older polyctl set up has polyctl state and no tracked marker:
|
|
232
|
+
`polyctl init --adopt` keeps all of that state, stages the marker, installs the current
|
|
233
|
+
hooks, and names the commit left to land.
|
|
234
|
+
Removal is two-phase: commit the marker deletion while state still
|
|
235
|
+
enforces, then run `polyctl remove --yes` again to remove the remaining state. A single-harness
|
|
236
|
+
setup reviews with another model of the implementer's family only when a person chooses it
|
|
237
|
+
(`--review-tier same-family --by NAME`), or with no model reviewer at all (`--review-tier
|
|
238
|
+
person`); `polyctl doctor` names the tier in force.
|
|
239
|
+
|
|
240
|
+
The MCP server is registered for detected agents (`.mcp.json` for Claude Code,
|
|
241
|
+
`.kiro/settings/mcp.json` for Kiro), each registration naming a role when the harnesses
|
|
242
|
+
reading it hold only one here: that server lists only that role's tools, and a reviewer's
|
|
243
|
+
only reads. Ask the human before running init; afterwards
|
|
244
|
+
tell them to restart the app in this directory and run `polyctl doctor`. Add `--watchdog`
|
|
245
|
+
(or `polyctl watchdog install`) for unattended runs; it installs a companion job that runs
|
|
246
|
+
`polyctl doctor --check` every fifteen minutes as the second, independent check.
|
|
247
|
+
|
|
248
|
+
## 10. When the run degrades
|
|
249
|
+
|
|
250
|
+
A reviewer out of quota is exit 3, not a verdict; the architect out of quota
|
|
251
|
+
means wakes wait for the reset and the queue must already hold work; the
|
|
252
|
+
implementer out of credits is a red alarm days ahead (`polyctl doctor` shows the
|
|
253
|
+
burn rate of its own account; an implementer whose adapter declares no account polyctl can
|
|
254
|
+
read has no credits alarm). A person may bypass a gate with `polyctl waive` — on the record — and
|
|
255
|
+
`polyctl catchup` reconciles it when the way is clear, with a reviewer of a model family
|
|
256
|
+
other than the one that wrote the work, who judges it against what its commit messages
|
|
257
|
+
claim; a split closes on the move proof, run on what landed, with no reviewer, when its grant
|
|
258
|
+
recorded the proof or a person states it only moved code (`polyctl catchup --move-only S --by NAME`).
|
|
259
|
+
Nothing is skipped silently and nothing is lost.
|
|
260
|
+
|
|
261
|
+
## 11. Never
|
|
262
|
+
|
|
263
|
+
Push. Open a PR. Force-push or bypass hooks. Tick an epic box. Change an
|
|
264
|
+
architectural contract (write `## DECISION REQUIRED` instead). Change a rule you work
|
|
265
|
+
under because you judge it wrong (propose it with `polyctl propose`). Present fixture evidence
|
|
266
|
+
as production-qualified. Touch another repository. Kill a process you did not
|
|
267
|
+
start. Run anything in a repository whose owner has not approved it.
|
|
268
|
+
|
|
269
|
+
## 12. Commands
|
|
270
|
+
|
|
271
|
+
| command | one line |
|
|
272
|
+
|---|---|
|
|
273
|
+
| `polyctl start [--yes]` | a person's first-run wizard: detect installed agent CLIs and model families, propose a cross-family implementer/reviewer pair (measured `verified` levels first), write the profile, ask before `polyctl demo`, `polyctl init`, `polyctl hooks install` and `polyctl prove` (`--yes` runs only the steps that need no person), and list the steps only a person can take; never records a person's approval or installs software |
|
|
274
|
+
| `polyctl init` | write polyctl state plus an exact unstaged `.polyctl-project` enrollment marker; idempotent |
|
|
275
|
+
| `polyctl init --adopt` | adopt polyctl state no tracked `.polyctl-project` covers: keep it all, stage the marker, install the current hooks, and name any tracked coordination files with the command that lands or untracks them; idempotent |
|
|
276
|
+
| `polyctl skill install` | (re)write this playbook for the detected agents (polyctl-owned files only; `--rules` for the owner's rule files) |
|
|
277
|
+
| `polyctl remove --yes` | two phases: commit `.polyctl-project` deletion under enforcement, then remove POLYCTL-owned state |
|
|
278
|
+
| `polyctl update [--dry-run\|--yes]` / `polyctl uninstall [--yes] [--purge]` | a person's commands, never an agent's: update polyctl the way it was installed, the command shown first; take polyctl's jobs, hooks and MCP entries off the machine, a dry run unless `--yes` |
|
|
279
|
+
| `polyctl completion zsh` | a person's shell setup: print the script that completes polyctl's commands in bash, zsh, fish or PowerShell |
|
|
280
|
+
| `polyctl status` / `polyctl watch` / `polyctl watch --all` / `polyctl watch --web [--port N]` | the panel: who is working, quota, problems, mail; `--web` serves the panel, the board, the pipeline and the fleet as read-only pages and `/api/*` JSON on 127.0.0.1 |
|
|
281
|
+
| `polyctl board` | READY / running / blocked (`needs:`) / verified / done |
|
|
282
|
+
| `polyctl next [--json\|--short]` | what stands in the way now and whose hand closes it, each with the command: a person's items first, then the staged candidate's landing chain at its first open stage. Read-only — it names a person's command, never runs it |
|
|
283
|
+
| `polyctl room search <words>` / `polyctl mail compact <days>` | stored messages across projects; collapse old bodies to stubs |
|
|
284
|
+
| `polyctl content add <source>@<commit> [--skills a,b] [--steering c,d] [--agents e,f] [--from <dir>] [--dry-run]` / `verify` | borrow skills, steering and agent definitions pinned and text-only, hooks never; check they have not drifted |
|
|
285
|
+
| `polyctl backup --to <dir|ref|remote:name>` / `polyctl restore <dir>` | the governance off this disk, and back, verified |
|
|
286
|
+
| `polyctl hunt [run|discard <id>|status]` | a bounded read-only bug hunt; leads to the architect, never a verdict |
|
|
287
|
+
| `polyctl pr watch --once` | opt-in with `pr.watch`: read this checkout's pull requests through gh, never write to GitHub, and mail the implementer a failed check, a conflict or requested changes, once per head |
|
|
288
|
+
| `polyctl split-check` | is the staged candidate a pure move? a `move-only` slice cannot land otherwise, and its grant records the proof its waived review later closes on |
|
|
289
|
+
| `polyctl adapters [list|validate|conform]` | every adapter and its source; check a candidate before relying on it |
|
|
290
|
+
| `polyctl role [set|swap]` | the role table; a reassignment takes effect on the next slice. `set reviewer <adapter> --model M` composes the reviewer from its adapter; a tool reviewer, which polyctl runs over the staged candidate on its own provider, also needs `--family F` |
|
|
291
|
+
| `polyctl stats [--all] [--since D] [--until D]` | slice outcomes from the ledgers: rounds, first-pass rate, time, size, defects found later |
|
|
292
|
+
| `polyctl gain [--since D] [--all] [--days N] [--slices] [--json] [--sources] [--quota]` | one surface for what polyctl measured: slices, reviews, board, spend, activity, lane evidence and a daily trend, read from the ledgers; `--quota` asks the implementer's account |
|
|
293
|
+
| `polyctl export otlp [--out <file>] [--attested]` | the project's ledger as OpenTelemetry traces in the OTLP/JSON encoding (one `ExportTraceServiceRequest`), written to `--out` or stdout; refuses unattested ledgers unless `--attested` asks for only checkpoint-attested rows; strictly read-only, polyctl sends nothing anywhere |
|
|
294
|
+
| `polyctl evidence [record --platform windows --run ID]` / `polyctl evidence show [--all] [--json]` | a platform lane's CI run read through `gh` and recorded in the chained evidence ledger, and what each platform's newest run still vouches for; a red, unplaceable or stale run is a finding of `polyctl doctor --check` |
|
|
295
|
+
| `polyctl doctor --consistency [--repair]` | board, ledgers, review artefacts and git checked against each other |
|
|
296
|
+
| `polyctl prove [--no-review]` | run the guarantees: the hook refuses, the reviewer answers, a throwaway slice lands |
|
|
297
|
+
| `polyctl demo [--keep]` | a person's command: the guarantee played in a scratch folder with a stand-in reviewer, a change with a bug refused and its fix landed; it touches nothing outside that folder |
|
|
298
|
+
| `polyctl worktrees [prune --yes]` | each worktree and what keeps it; retire merged or rejected ones, state archived |
|
|
299
|
+
| `polyctl lane start <item>` / `polyctl lane list` / `polyctl lane remove <item>` | a worktree of its own for a READY board item, beside the main checkout on `lane/<lane>` - the id with each run of characters a branch cannot hold made one hyphen, so `ACME-187/1` is on `lane/ACME-187-1` - prepared from the `lane.*` settings before it is called ready; remove refuses uncommitted changes |
|
|
300
|
+
| `polyctl recall <words>` | decisions, answers, waivers, review findings and lessons from every project that share the words |
|
|
301
|
+
| `polyctl board ready` | exactly the items that may start now; exit 1 names a broken `needs:` edge |
|
|
302
|
+
| `polyctl board add ID "title" --acceptance "…" [--needs A,B] [--role R]` | admits one item to `queued`, only with its acceptance boundary; refused, it writes nothing |
|
|
303
|
+
| `polyctl slice start <id> [--boundary-file F]` / `polyctl slice block "…" [--waiting W]` / `polyctl slice abandon --why "…"` | move a slice between the board's sections, each move a line in `.polyctl/ledger/slices.jsonl`: the implementer starts a READY item or resumes a slice it blocked; anyone blocks a running slice; dropping one (to `rejected`) and a boundary file are the architect's or a person's |
|
|
304
|
+
| `polyctl slice status [<id>]` / `polyctl slices [--open]` | where a slice stands, since when and how it got there, its rounds and its newest review's findings; every slice one line, a row moved or removed by hand named |
|
|
305
|
+
| `polyctl fleet` | every project on this machine at a glance |
|
|
306
|
+
| `polyctl tail` | the implementer's transcript, live |
|
|
307
|
+
| `polyctl agents` | the sessions this project's harnesses told polyctl of through their lifecycle hooks, and what each is doing: working, waiting, idle or ended |
|
|
308
|
+
| `polyctl agent-hook <event> [--harness ID]` | what a harness's lifecycle hook runs, not a command to type: it records the event in the event log and prints nothing |
|
|
309
|
+
| `polyctl harness probe [ID…] [--sessions]` | a person's command: ask each harness that speaks ACP what it supports, sending no prompt, and keep the answer |
|
|
310
|
+
| `polyctl harness seen --by NAME` / `--digest D` / `--ask` | a person's command, never an agent's: read each change an agent made to what a harness reads here - hooks, plugins, MCP servers, instructions - then record exactly those bytes as seen, by the digest or on a yes at a terminal; until then no wake, refill, nudge, hunt or lane starts in the tree, so change none of it unless your slice asks. What `polyctl init` and `polyctl skill install` write of their own is seen already |
|
|
311
|
+
| `polyctl events [--follow] [--project P] [--since T]` | what polyctl did on this machine, one line an event: verifications, submitted and finished reviews, grants, mail, nudges and wakes; `--follow` prints each as it is written, `--json` as a line of JSON |
|
|
312
|
+
| `polyctl mail list|read|send|log|search|ack` | the mailbox and its ledger; `ack` deletes processed messages (delivery confirmation) |
|
|
313
|
+
| `polyctl note` | architect → implementer note without raw file writes (`--urgent`) |
|
|
314
|
+
| `polyctl decide` | record an architect decision (`--scope`, `--why`, `--answers D-…`) |
|
|
315
|
+
| `polyctl ask` / `polyctl answer <D-id> <key>` / `polyctl decisions` | questions with options; the answers unpark slices. An answer is a key the question offers, `x <text>` for your own words; anything else is refused, naming the keys. An answered question keeps its answer: `--change` replaces it, and the first stays on the record |
|
|
316
|
+
| `polyctl propose "…" --why "…" [--rule-file <path>]` | propose a change to a rule you work under instead of editing it: recorded in the decision ledger with who, why, the rule file and the recent slices' outcomes, and asked of a person, who accepts or rejects it with `polyctl answer`; it writes no rule file |
|
|
317
|
+
| `polyctl proposals [--all]` | the rule proposals waiting for a person; `--all` adds the decided ones, their answers and whether the rule file changed since |
|
|
318
|
+
| `polyctl lock -- <cmd>` | hold the writer lock, run a gate, record it |
|
|
319
|
+
| `polyctl verify -p quick|full` | run the declared gates and record the measured result |
|
|
320
|
+
| `polyctl merge-check <branch>` | gate the result of a merge before merging; the record names both parents |
|
|
321
|
+
| `polyctl review --boundary "…" [--paths …]` | independent prospective review of the exact staged candidate; `--paths` narrows its staged scope |
|
|
322
|
+
| `polyctl review --commits <range>` | retrospective review of landed work; never authorizes a candidate |
|
|
323
|
+
| `polyctl ci review --base B --reviewer A --model M --family F --author-family F` | a step a person writes into a CI workflow, never an agent's command: a pull request's change reviewed by a model of another family; it grants nothing |
|
|
324
|
+
| `polyctl review submit [--boundary …]` / `polyctl review collect <R-id>\|--any` / `polyctl reviews` / `polyctl review cancel <R-id>` | submit pins the staged tree and reviews it in the background, returning an id at once; collect takes a finished one; `polyctl reviews` lists them with what each is doing - starting, preparing, waiting and on what, or which reviewer runs; cancel ends a review and the reviewer it started, never a bare `kill`; `polyctl commit-ok --review <R-id>` grants only on the pinned tree |
|
|
325
|
+
| `polyctl commit-ok [--verify] [--by NAME] [--ask] [--digest D]` | persist authority for the exact isolated index candidate, verification and prospective review; a candidate holding only coordination paths (including `.polyctl/` itself, such as `.polyctl/gates.json` and `.polyctl/config.json`, and no unseen harness configuration: `polyctl harness seen --ask` first) is a person's coordination commit (`--by NAME` with `--ask` or `--digest D`, never an agent's) with no product gates or review (`--review`, `--verify` and `-p`/`--profile` refused) |
|
|
326
|
+
| `polyctl commit-check` | revalidate the latest persisted grant against Git's active index without issuing or consuming one; `--range A..B` holds each landed commit to the tree its Polyctl- trailers name |
|
|
327
|
+
| `polyctl writers [--clean]` | live turns (not processes); orphans set aside |
|
|
328
|
+
| `polyctl hold` / `polyctl hold release` | stop unattended turns and keep them stopped |
|
|
329
|
+
| `polyctl watchdog install|uninstall|status|explain|trace` | the unattended loop and its instruments |
|
|
330
|
+
| `polyctl doctor [--check]` | health: binaries, last wake, last tick, channels, alarms; `--check` exits 1 on problems |
|
|
331
|
+
| `polyctl alarms [test]` | live alarm episodes; ring the channels |
|
|
332
|
+
| `polyctl email setup|test|status` | the red channel |
|
|
333
|
+
| `polyctl telegram setup|test|install` | the orange channel and phone decisions |
|
|
334
|
+
| `polyctl ntfy setup|test|status` | outbound phone channel via ntfy.sh or your own ntfy server |
|
|
335
|
+
| `polyctl fanout ok|record|history` | budget gate for sub-agent fan-outs; `--roots R --per-root K` for pipelines |
|
|
336
|
+
| `polyctl credits` | the implementer's own credit account and offline estimate, or that its adapter declares none polyctl can read; `--all` reads every shipped adapter that declares a lookup or its transcripts |
|
|
337
|
+
| `polyctl features [on|off <key>]` | the switches and what each costs; all off = deterministic polyctl |
|
|
338
|
+
| `polyctl mode [show|lite|full]` | the project mode and what each mode does and does not protect; `lite` is the basic setup without enforcement (`enforcement: off - lite` — no reviewer probe, no commit hooks, `polyctl commit` refused), a person's act with `--by NAME` on the record; `full` checks an independent reviewer route and hooks and refuses naming what is missing |
|
|
339
|
+
| `polyctl config [list|get|set|unset] [<setting> <value>] [--machine]` | what a person can set: every threshold with its value, default and source (docs/configuration.md); a person's command, not an implementer's. `review.same_family` and `mode` change only with `--by NAME`, on the record |
|
|
340
|
+
| `polyctl collect-review <nonce> --response F --model M --by NAME` | a person records a stand-in session's answer to the review request polyctl wrote when no reviewer could be reached; never an agent's command |
|
|
341
|
+
| `polyctl person-review --by NAME [--commits <range>]` / `--verdict APPROVED\|NEEDS_CHANGES --digest D [--findings F]` | a person reads the staged diff (or a landed range) and its digest, then records the verdict on exactly those bytes; `polyctl commit-ok` grants on it and `polyctl catchup` closes a waived range on it, labeled `person review`; never an agent's command |
|
|
342
|
+
| `polyctl waive review\|gates [--gates G] --slice S --by NAME --why …` / `polyctl catchup` | a person's bypass of `review` or `gates` on the record (`inventory` is refused); a `gates` waiver stands in for the failed gates it names (all of the profile's when `--gates` is omitted) on one staged candidate whose verification ran every gate of the profile; catchup re-runs waived gates on the landed commit and closes the waiver when they pass, reviews each waived review's landed range with a model family other than the one that wrote it against what its commit messages claim, closes a `move-only` split on the proof its grant recorded, run again, and replays deferred work. `polyctl catchup --plan` previews, names what closes by proof, and writes nothing; `polyctl catchup --limit 10` and `polyctl catchup --slice S` bound a run; `polyctl catchup --author-family F --by NAME` is a person naming the family where the grant recorded none, and `polyctl catchup --move-only S --by NAME` a person stating which waived slices only moved code, each closing only where the proof holds; neither is an agent's command. A run exits 3 when the reviews it started decided nothing, 1 when a waived gate failed or a ledger could not be written, and 0 when it made progress or had nothing to do |
|
|
343
|
+
| `polyctl pings setup [--url-env NAME]` / `polyctl hooks [status|install|uninstall] [--allow-shared-hooks]` / `polyctl push allow` | dead man's switch; static polyctl hook intent plus Git-executed, nonce-bound pre-commit proof; explicit authorization for shared/external/global mutation; human push window |
|
|
344
|
+
| `polyctl cost [--since 24h] [--usd]` | what the coordination spends: implementer turns by class, wasted turns, review counts; `--usd` prices the tokens in US dollars from the table polyctl ships, an estimate, unknown for a model it does not price |
|
|
345
|
+
| `polyctl since last|2h|today|<git ref>` | what happened since; the ref reaches git as one argument, never shell text |
|
|
346
|
+
| `polyctl digest` | landed work, gates, reviews, decisions in one page |
|
|
347
|
+
| `polyctl notices` / `polyctl prune` | alert history; trim records and logs |
|
|
348
|
+
| `polyctl source list|status|import` | external queues (Linear, Jira) feeding the board |
|
|
349
|
+
| `polyctl handoff` | write a resume briefing when the centre runs out of quota |
|
|
350
|
+
| `polyctl projects` / `polyctl adapters` | every workspace with a local agent session; supported agents |
|
|
351
|
+
| `polyctl mcp serve [--project all]` / `polyctl mcp config` | the MCP server (tools, read-only resources and prompts) and its client config; with `--role <role>`, that role's tools alone; with `--project all`, every registered project |
|
|
352
|
+
| `polyctl a2a serve` / `polyctl a2a-mcp serve` | A2A: serve the board; bridge remote agents into MCP |
|
|
353
|
+
|
|
354
|
+
Every time a command takes (`--since`, `--until`, `--days`, `--window`, `polyctl since`,
|
|
355
|
+
`polyctl mail compact`) is written `30m`, `2h`, `1d`, `1w`, `today`, `yesterday` or a date
|
|
356
|
+
such as `2026-09-17`; a number alone keeps the unit its option always had. A command that
|
|
357
|
+
cannot run says why in one line, and `POLYCTL_DEBUG=1` shows the traceback. `polyctl --version`
|
|
358
|
+
names the installed version.
|
|
359
|
+
|
|
360
|
+
## 13. Read further
|
|
361
|
+
|
|
362
|
+
`docs/` in the polyctl repository: roles, protocol, gates, safety, recovery,
|
|
363
|
+
watchdog (the contract and the fault catalog), alarms, fanout, mcp, telegram,
|
|
364
|
+
sources, parallel, slices, ledger, lessons (twenty-three, each a stall that
|
|
365
|
+
will not happen again if the rule holds).
|