From 5495f094f35f217c95964faebe58eeeadab3fce6 Mon Sep 17 00:00:00 2001 From: 7fpb5574ck-maker <369284625@qq.com> Date: Fri, 28 Aug 2026 16:11:56 +0800 Subject: [PATCH] docs(opc): make first success machine-verifiable --- labs/opc-company/README.en.md | 84 +++++++++++++++++++++++----------- labs/opc-company/README.md | 86 +++++++++++++++++++++++------------ 2 files changed, 113 insertions(+), 57 deletions(-) diff --git a/labs/opc-company/README.en.md b/labs/opc-company/README.en.md index b5649b4..1b7b1a3 100644 --- a/labs/opc-company/README.en.md +++ b/labs/opc-company/README.en.md @@ -6,37 +6,67 @@ QuietHarness focuses on reliable execution by one or a few agents. The OPC Compa ## 10-minute first success +Requirements: Git and Python 3. The OPC lab uses only the Python standard library; there is no package-install step. + +From a clean checkout: + ```bash -cd labs/opc-company +git clone https://github.com/runesleo/claude-code-workflow.git +cd claude-code-workflow/labs/opc-company +python3 scripts/opc.py --help +``` + +The first-success contract is based on exit code + exact output tokens. Expected rejection cases intentionally exit `1`; expected success cases exit `0`. + +```bash +# 1) Inspect the synthetic company python3 scripts/opc.py status examples/synthetic-company +# exit 0 +# output includes: "task_count": 2, "work_continuing": true + +# 2) False completion: outcome says completed but proof/writeback are missing +python3 scripts/opc.py verify --task fixtures/false-completion/task.json --receipt fixtures/false-completion/receipt.json +# exit 1 +# output must include all three: +# OPC_VERIFY_REJECT missing_artifact +# OPC_VERIFY_REJECT missing_validation +# OPC_VERIFY_REJECT missing_owner_writeback -python3 scripts/opc.py verify \ - --task fixtures/false-completion/task.json \ - --receipt fixtures/false-completion/receipt.json -# expected: rejected - -python3 scripts/opc.py verify \ - --task examples/synthetic-company/tasks/product-release.json \ - --receipt examples/synthetic-company/receipts/product-release.valid.json -# expected: PASS - -python3 scripts/opc.py failover \ - --before fixtures/quota-failover/task.before.json \ - --after fixtures/quota-failover/task.after.json -# expected: same task, same owner, new worker, PASS - -# A blocked leaf execution path does not stop the canonical task -python3 scripts/opc.py continuation \ - --before fixtures/continuation/before.json \ - --after fixtures/continuation/after.bad-leaf-stop.json -# expected: rejected with leaf_blocker_promoted_global / premature_global_stop - -# An owner turn cannot drift to another scope without a semantic handoff -python3 scripts/opc.py continuation \ - --before fixtures/continuation/before.json \ - --after fixtures/continuation/after.bad-scope-drift.json -# expected: rejected with scope_drift_without_handoff +# 3) Valid receipt +python3 scripts/opc.py verify --task examples/synthetic-company/tasks/product-release.json --receipt examples/synthetic-company/receipts/product-release.valid.json +# exit 0 +# exact token: OPC_VERIFY_PASS + +# 4) Worker failover preserves the canonical task and owner +python3 scripts/opc.py failover --before fixtures/quota-failover/task.before.json --after fixtures/quota-failover/task.after.json +# exit 0 +# exact output: +# OPC_FAILOVER_PASS task=product-release from=worker-a to=worker-b + +# 5) A blocked leaf execution path must not stop the canonical task +python3 scripts/opc.py continuation --before fixtures/continuation/before.json --after fixtures/continuation/after.bad-leaf-stop.json +# exit 1 +# output must include BOTH: +# OPC_CONTINUATION_REJECT leaf_blocker_promoted_global +# OPC_CONTINUATION_REJECT premature_global_stop + +# 6) An owner turn cannot drift to another scope without a semantic handoff +python3 scripts/opc.py continuation --before fixtures/continuation/before.json --after fixtures/continuation/after.bad-scope-drift.json +# exit 1 +# exact token: OPC_CONTINUATION_REJECT scope_drift_without_handoff + +# 7) Positive continuation control +python3 scripts/opc.py continuation --before fixtures/continuation/before.json --after fixtures/continuation/after.good-leaf-continue.json +# exit 0 +# exact output: +# OPC_CONTINUATION_PASS task=synthetic-content-task scope=opc-merge-milestone work_continuing=true + +# Optional full regression suite +python3 tests/run.py +# exit 0; exact token: OPC_TEST_OK ``` +All fixture paths above are relative to `labs/opc-company`. If an agent runs from the repository root, either `cd labs/opc-company` first or prefix the paths accordingly. + Public: protocols, schemas, synthetic fixtures, verifier. Private: live business tasks, production topology, account bindings, schedulers, exact quota routing, trading alpha, credentials. diff --git a/labs/opc-company/README.md b/labs/opc-company/README.md index 3563595..5b68e01 100644 --- a/labs/opc-company/README.md +++ b/labs/opc-company/README.md @@ -6,42 +6,68 @@ QuietHarness 解决单个或少量 Agent 的可靠执行；OPC Company Layer 解 ## 10 分钟 First Success +运行前提：Git + Python 3。OPC Lab 只使用 Python 标准库，不需要额外安装 package。 + +从干净 checkout 开始： + ```bash -cd labs/opc-company +git clone https://github.com/runesleo/claude-code-workflow.git +cd claude-code-workflow/labs/opc-company +python3 scripts/opc.py --help +``` +First Success 的验收以「退出码 + 精确输出 token」为准。预期被拒绝的案例故意返回 `exit 1`；预期通过的案例返回 `exit 0`。 + +```bash +# 1) 查看 synthetic company 状态 python3 scripts/opc.py status examples/synthetic-company +# exit 0 +# 输出包含："task_count": 2, "work_continuing": true + +# 2) 假完成：自述 completed，但 proof / owner writeback 缺失 +python3 scripts/opc.py verify --task fixtures/false-completion/task.json --receipt fixtures/false-completion/receipt.json +# exit 1 +# 输出必须同时包含： +# OPC_VERIFY_REJECT missing_artifact +# OPC_VERIFY_REJECT missing_validation +# OPC_VERIFY_REJECT missing_owner_writeback -# 1) Agent 自述完成，但没有 artifact / validation / owner writeback -python3 scripts/opc.py verify \ - --task fixtures/false-completion/task.json \ - --receipt fixtures/false-completion/receipt.json -# 预期：拒绝 - -# 2) 真实 receipt -python3 scripts/opc.py verify \ - --task examples/synthetic-company/tasks/product-release.json \ - --receipt examples/synthetic-company/receipts/product-release.valid.json -# 预期：PASS - -# 3) Worker 额度耗尽，但任务不迁移 -python3 scripts/opc.py failover \ - --before fixtures/quota-failover/task.before.json \ - --after fixtures/quota-failover/task.after.json -# 预期：同 task / 同 owner / 新 worker，PASS - -# 4) 叶子执行面被阻塞，不等于整个 canonical task 停止 -python3 scripts/opc.py continuation \ - --before fixtures/continuation/before.json \ - --after fixtures/continuation/after.bad-leaf-stop.json -# 预期：拒绝 leaf_blocker_promoted_global / premature_global_stop - -# 5) 无 semantic handoff 不允许 owner turn 漂到另一个 scope -python3 scripts/opc.py continuation \ - --before fixtures/continuation/before.json \ - --after fixtures/continuation/after.bad-scope-drift.json -# 预期：拒绝 scope_drift_without_handoff +# 3) 合法 receipt +python3 scripts/opc.py verify --task examples/synthetic-company/tasks/product-release.json --receipt examples/synthetic-company/receipts/product-release.valid.json +# exit 0 +# 精确 token：OPC_VERIFY_PASS + +# 4) Worker failover：canonical task 与 owner 不变，只替换 worker +python3 scripts/opc.py failover --before fixtures/quota-failover/task.before.json --after fixtures/quota-failover/task.after.json +# exit 0 +# 精确输出： +# OPC_FAILOVER_PASS task=product-release from=worker-a to=worker-b + +# 5) 叶子执行面被阻塞，不得升级为整个 canonical task 停止 +python3 scripts/opc.py continuation --before fixtures/continuation/before.json --after fixtures/continuation/after.bad-leaf-stop.json +# exit 1 +# 输出必须同时包含： +# OPC_CONTINUATION_REJECT leaf_blocker_promoted_global +# OPC_CONTINUATION_REJECT premature_global_stop + +# 6) owner turn 没有 semantic handoff，不允许漂到另一个 scope +python3 scripts/opc.py continuation --before fixtures/continuation/before.json --after fixtures/continuation/after.bad-scope-drift.json +# exit 1 +# 精确 token：OPC_CONTINUATION_REJECT scope_drift_without_handoff + +# 7) continuation 正向控制组 +python3 scripts/opc.py continuation --before fixtures/continuation/before.json --after fixtures/continuation/after.good-leaf-continue.json +# exit 0 +# 精确输出： +# OPC_CONTINUATION_PASS task=synthetic-content-task scope=opc-merge-milestone work_continuing=true + +# 可选：完整回归测试 +python3 tests/run.py +# exit 0；精确 token：OPC_TEST_OK ``` +以上 fixture 路径都相对于 `labs/opc-company`。如果 Agent 从仓库根目录执行，应先 `cd labs/opc-company`，或自行补齐路径前缀。 + ## 公开边界 公开的是协议、schema、synthetic fixture 和 verifier。