martin1847/evolab / skills/cto-orchestration
cto-orchestration
Unverified以 CTO/orchestrator 模式管理多 agent 软件交付。用户要求“你做 CTO/编排者”“派 omp/codex 去做”“goal 模式派发”、管理多会话开发或接入这套工作流时使用;“复盘/收口/retro/retrospective”“工作盘点/盘点候选/stocktake”也必须触发,盘点只提案不动工。新项目先用 repo-governance-bootstrap 建治理骨架。不用于单 agent 小任务、无需评审循环的局部改动或纯文档初始化。
references/agentctl/cto-guard-stop.py
View on GitHub#!/usr/bin/env python3
"""cto-guard-stop — Stop-event enforcement for cto-orchestration. ONE rule:
(S1) ending a turn while THIS repo has a RUNNING agentctl seat with no live watcher -> block
the stop and say so.
Field, 2026-09-02: the orchestrator seat came back from a review round, ran one forensic command
and ended its turn. A seat was RUNNING, its watcher had been TERM'd with the host's task, and no
wakeup was armed — 44 minutes of pure idle until a human asked. Prose cannot reach that moment:
moment of". The prompt-time twin that used to cover "after the fact" was deleted 2026-09-03
(减法批); its seat census stayed, as `seat-census.py`.
FAIL-OPEN, ALWAYS. A Stop hook is the only gate whose false positive costs every turn end in the
session, so every unanswerable case (unparseable payload, unlistable run dir, missing agentctl, a
`status` that never returned, any internal failure) exits 0 with a one-line `systemMessage` WARN
and lets the turn end. It never exits 2 — on Stop, exit 2 BLOCKS with stderr as the reason, which
is exactly the verdict a blind gate must not reach. `stop_hook_active` short-circuits first:
Claude Code / codex set it while already continuing because of a stop hook, and blocking there is
how a Stop hook wedges a session (the harness also caps consecutive blocks at 8, which is a fuse,
not a design).
The seat census, the ownership filter and the "no watcher armed" predicate live in
`seat-census.py` in this directory and are IMPORTED, never copied: the fact and the verdict over
it stay separately readable, and a second consumer would not have to re-implement the fact. The
"is this repo being orchestrated" predicate comes through the same module from `identity.py`, so
E1, this gate and the compaction reminder fire on ONE fact instead of three approximations of it
(audit §2, 2026-09-06: this gate blocked turn ends over seats belonging to other checkouts
whenever the payload cwd had no decidable git top level).
Wiring: entry in `guard-hooks.json` (Stop). Same script serves Claude Code and codex — both send
`stop_hook_active` on stdin and both read `{"decision":"block","reason":…}` on stdout; codex needs
the hook trusted once via `/hooks` (README §Wiring).
PYTHON FLOOR 3.9: the shebang is `#!/usr/bin/env python3`, which on a stock macOS host is
/usr/bin/python3 3.9.6, so annotations use `typing.Optional` and never PEP 604 `X | None` — a
module-level `|` raises TypeError at LOAD time, i.e. the gate is silently disabled (R1 B1: the
sibling failed to import and every turn end got the "could not be loaded" WARN instead of a
verdict). `test/cto-guard-stop.test.sh` pins both scripts against /usr/bin/python3 when present.
KILL CRITERION (slug `s1-stop-unwatched-seat`, retro GATE-AUDIT): hits=0 ∧ false>=2 ⇒ kill —
"false" here is a block raised over a seat that was not this repo's business or was already being
supervised, because a gate that argues with a correct turn end burns one round every time.
"""
import json
import os
import sys
from types import ModuleType
from typing import Optional
_CENSUS = "seat-census.py"
# Both texts are module literals spent AT their sink (inline `json.dumps`), which is what keeps
# them on the injected-text meter (test/loc-budget.test.sh weighs literals at the sink and
# resolves one local per name — a message handed through a helper would be spent unweighed).
_BLOCK = (
"DENY: 结束 turn 时有 RUNNING 席位没人看 — %s%s. Why: 没有活 watcher 的 RUNNING 席位在你收工"
"后无人收割,空转到有人来问(2026-09-02 实证 44 分钟:席位 RUNNING、watcher 随宿主任务被 TERM、"
"编排位跑完一条取证命令即结束 turn)。正路:`agentctl watch <S>` 交宿主后台跑(前台 Bash 超时会"
"连 watcher 一起杀);确实要放着不管就 `agentctl stop <S>`,或显式挂一个 wakeup 再结束。"
"Read: cto-orchestration/references/agentctl/README.md §强制层\n"
)
_WARN = (
"WARN (cto-guard S1): %s, so unwatched-seat liveness in THIS repo went UNJUDGED and the turn "
"was allowed to end. A gate that cannot answer must not block — but its silence would read "
"as approval, so: if a seat is still working, arm `agentctl watch <S>` in the host's "
"background yourself."
)
def _census_mod() -> Optional[ModuleType]:
"""The seat census from the sibling module, or None when it cannot be loaded at all. A
missing / unreadable sibling degrades to ALLOW+WARN like every other unanswerable case rather
than taking every turn end down with it. importlib because the filename is hyphenated; the
module is pure definitions with no entrypoint, so loading it has no side effects."""
import importlib.util
path = os.path.join(os.path.dirname(os.path.abspath(__file__)), _CENSUS)
try:
spec = importlib.util.spec_from_file_location("seat_census", path)
if spec is None or spec.loader is None:
return None
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
except Exception:
return None
return mod
def main() -> int:
"""ONE warn sink, on purpose: every unanswerable branch assigns `blind` and falls through to
the single emit below. Four `print(json.dumps(...))` copies would each be weighed separately
by the injected-text meter (test/loc-budget.test.sh resolves literals AT the sink), so
the same sentence would be charged four times and the ratchet would stop meaning anything."""
blind: Optional[str] = None
try:
data = json.load(sys.stdin)
except Exception:
data = None
if not isinstance(data, dict):
blind = "the Stop payload could not be parsed"
else:
if data.get("hook_event_name") != "Stop":
return 0 # SubagentStop and every other event: not this rule's
if data.get("stop_hook_active"):
return 0 # already continuing from a stop hook: stand down
mod = _census_mod()
if mod is None:
blind = f"{_CENSUS} could not be loaded from this script's own directory"
else:
cwd = data.get("cwd")
seen = mod.census(cwd if isinstance(cwd, str) else None, mod.run_dir())
blind = seen.blind
if blind is None:
if not seen.seats:
return 0
# THE SECOND QUESTION (audit §2, 2026-09-06): a RUNNING unwatched seat of this
# repo is only this gate's business while the repo is BEING ORCHESTRATED. The
# same predicate E1 and the compaction reminder consult answers it, so all three
# gates fire on one fact; `undecidable` degrades to the fail-open WARN like every
# other unanswerable case, never to a block.
state, why = mod.identity.orchestrated(cwd, mod.run_dir())
if state != mod.identity.ORCHESTRATED:
blind = why
else:
cap_note = (f" (+{seen.overflow} owned seat(s) past the census cap were not "
"checked — there may be more) " if seen.overflow else "")
print(json.dumps({"decision": "block",
"reason": _BLOCK % (", ".join(seen.seats), cap_note)}))
return 0
if blind:
print(json.dumps({"systemMessage": _WARN % blind}))
return 0
if __name__ == "__main__":
try:
sys.exit(main())
except Exception as exc:
print(json.dumps({"systemMessage": _WARN % f"the stop gate failed internally ({exc!r})"}))
sys.exit(0)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |