docs(opc): make first success machine-verifiable

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.

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。