Skip to content

martin1847/evolab / skills/cto-orchestration

cto-orchestration

Unverified

以 CTO/orchestrator 模式管理多 agent 软件交付。用户要求“你做 CTO/编排者”“派 omp/codex 去做”“goal 模式派发”、管理多会话开发或接入这套工作流时使用;“复盘/收口/retro/retrospective”“工作盘点/盘点候选/stocktake”也必须触发,盘点只提案不动工。新项目先用 repo-governance-bootstrap 建治理骨架。不用于单 agent 小任务、无需评审循环的局部改动或纯文档初始化。

FileKindSize
README.mdmarkdown5.3 KB
SKILL.mdskill md15.8 KB
references/agentctl/README.mdmarkdown26.8 KB
references/agentctl/agentctlexecutablescript57.6 KB
references/agentctl/codegraph-hooks.shexecutablescript2.5 KB
references/agentctl/cto-guard-agent.pyexecutablescript26.6 KB
references/agentctl/cto-guard-bash.pyexecutablescript150.5 KB
references/agentctl/cto-guard-edit.pyexecutablescript16.7 KB
references/agentctl/cto-guard-stop.pyexecutablescript7.6 KB
references/agentctl/duplexctl.pyexecutablescript239.5 KB
references/agentctl/guard-hooks.jsonconfig1.5 KB
references/agentctl/identity.pyexecutablescript113.5 KB
references/agentctl/post-checkout-codegraph.shscript18 B
references/agentctl/seat-census.pyscript10.8 KB
references/agentctl/watchctl.pyexecutablescript143.2 KB
references/agents-md-orchestration-section.mdmarkdown5.3 KB
references/decision-queue.mdmarkdown5.7 KB
references/dispatch-baseline.mdmarkdown3.7 KB
references/doc-lifecycle.pyexecutablescript9.2 KB
references/frontend-verify.mdmarkdown7.9 KB
references/goal-clauses.mdmarkdown8.0 KB
references/goal-preflight.pyexecutablescript40.9 KB
references/goal-template.mdmarkdown10.8 KB
references/implementation-discipline.mdmarkdown8.0 KB
references/measurement-protocol.mdmarkdown4.2 KB
references/onboarding-checklist.mdmarkdown3.2 KB
references/queue-freshness.pyexecutablescript3.8 KB
references/queue-hooks.jsonconfig617 B
references/retro-check.shexecutablescript28.2 KB
references/retro-hooks.jsonconfig2.2 KB
references/retro-reminder.shexecutablescript5.8 KB
references/retrospective.mdmarkdown7.7 KB
references/review-brief-preamble.mdmarkdown3.4 KB
references/review-dispatch.mdmarkdown14.4 KB
references/session-economics.pyexecutablescript18.2 KB
references/shock-in-the-loop.mdmarkdown3.8 KB
references/stocktake.mdmarkdown2.3 KB

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)
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall