challenge-plans 0.1.0__tar.gz

challenge_plans-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

challenge_plans-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: release
+
+# Publish to PyPI via Trusted Publishing (OIDC) — no long-lived token stored.
+# Trigger: push a version tag, e.g. `git tag v0.1.0 && git push origin v0.1.0`.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    name: Build & publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/challenge-plans
+    permissions:
+      id-token: write        # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run tests (never publish a red build)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+          pytest -q
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

challenge_plans-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+dist/
+build/
+.DS_Store

challenge_plans-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Thanks for your interest in challenge-plans.
+
+## Dev setup
+
+```bash
+pip install -e ".[dev]"     # installs the package + pytest
+pytest                      # pythonpath/testpaths are preconfigured
+challenge-plans doctor      # check your backend CLIs are logged in
+```
+
+Python ≥ 3.10. The only runtime dependency is PyYAML.
+
+## Ground rules
+
+- **Tests pin behavior.** Every non-trivial change should keep `pytest` green; add a test for new behavior. The suite encodes the invariants established across the project's adversarial-review rounds — don't loosen them without a reason.
+- **Dogfood it.** This is an adversarial-review tool; we review our own plans and diffs with it. Running `challenge-plans run <your-change>.diff --type diff` before opening a PR is encouraged.
+- **No silent simplification of guarantees.** The integrity, verification, and false-consensus guards (see README) are load-bearing; if you change one, say so explicitly in the PR.
+- **Keep it backend-neutral.** The tool must work with at least one subscription CLI and degrade gracefully (advisory) when only one model family is available.
+
+## Reporting issues
+
+Open a GitHub issue with the command you ran, the JSON/Markdown output it printed (redact anything sensitive), and what you expected.

challenge_plans-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text of the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 challenge-plans contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

challenge_plans-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: challenge-plans
+Version: 0.1.0
+Summary: Multi-agent adversarial review & deliberation for plans/specs on subscription CLIs (reduce rework before execution)
+Project-URL: Homepage, https://github.com/hiadrianchen/challenge-plans
+Project-URL: Repository, https://github.com/hiadrianchen/challenge-plans
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# challenge-plans
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue.svg)]()
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/hiadrianchen/challenge-plans/ci.yml?branch=main)](https://github.com/hiadrianchen/challenge-plans/actions)
+
+> 中文文档: [README-zh.md](README-zh.md)
+
+**Adversarially review your plan or spec before you execute it — across the coding CLIs you already have logged in. No API keys.**
+
+`challenge-plans` orchestrates the subscription AI coding CLIs already on your machine (Claude Code, Codex, …) to cross-examine a plan/spec and surface the flaws that cause rework downstream — and to vote across options when you're unsure. It also reviews a raw `git diff` as a lightweight **code review** pass, and drops in as an **agent skill**. It runs on your existing subscriptions, so there are no per-token API charges. It slots into the superpowers plan lifecycle: `writing-plans → challenge-plans → executing-plans`.
+
+```text
+$ challenge-plans run plan.md --type spec --profile standard --sink markdown
+
+# challenge-plans · challenge · verdict: request_changes
+- panel: expected 3 / collected 3 · complete ✓
+- diversity: 2 families
+- verified: 3 high/critical reviewed by Verifier (✓ verified, may hard-gate; ? unverified, advisory)
+- surviving objections: 4
+
+- [high✓]   sensitive data sent to a third-party LLM with no privacy boundary  @L42-43  (security_or_privacy_boundary, by claude:scope-boundary)
+- [high✓]   "schema-aligned" claimed but there's no contract test             @L12-30  (integration_contract_gap, by gpt:correctness)
+- [high✓]   no measurable acceptance threshold                               @L1      (contract_violation, by preflight)
+- [medium?] missing_fields vs null semantics left undefined                  @L32-34  (ambiguity_to_wrong_implementation)
+```
+
+## Why challenge-plans
+
+- 🔑 **No API keys, no per-token charges** — it drives the subscription CLIs you're already logged into (Claude Code, Codex). Bring at least one.
+- 🧪 **Evidence beats headcount** — a minority objection with a reproduction can override a majority vote; correctness is not decided by voting.
+- 🤝 **Cross-family verification** — an objection only earns hard-gate authority (`✓`) when an *independent model family* reproduces it with concrete, line-anchored evidence. Single-model claims stay advisory.
+- 🛡️ **Guards 7 known multi-agent failure modes** — vote loss, option anchoring, premature hand-off, majority-over-minority, single-round complacency, false consensus, false convergence. Each was hit (and fixed) while building this tool with its own adversarial process.
+- 🌍 **Reads in your language** — the codebase is English, but `--lang zh` (or `ja`, `de`, `fr`, …) makes every reviewer write its findings in your language while JSON keys and line anchors stay machine-stable. One flag, no separate build — see [Output in your language](#output-in-your-language).
+
+## Quickstart
+
+Requires Python ≥ 3.10 (PyYAML installs automatically). Bring at least one logged-in coding CLI — **Claude Code** (`claude`) or **OpenAI Codex** (`codex`); two different vendors unlock cross-family verification.
+
+```bash
+git clone https://github.com/hiadrianchen/challenge-plans && cd challenge-plans
+pip install -e .                                                          # exposes the `challenge-plans` command
+challenge-plans doctor                                                    # which backend CLIs are logged in
+challenge-plans run examples/spec-sample.md --type spec --sink markdown   # see a verdict on the bundled sample
+```
+
+Hand the repo to your coding agent instead — *"Install and set up challenge-plans from this repo, then run `challenge-plans doctor`"* — and it'll do the above. To use it **as an agent skill**, drop [SKILL.md](SKILL.md) where your agent discovers skills.
+
+## Use
+
+```bash
+challenge-plans doctor                                                                 # which backends are ready
+challenge-plans run path/to/spec.md --type spec --profile standard --sink markdown     # harden a plan/spec
+challenge-plans run change.diff --type diff --sink markdown                             # review a git diff
+challenge-plans weigh path/to/options.yaml --profile standard --sink markdown           # vote across options
+challenge-plans run path/to/spec.md --enforce                                           # CI gate: non-approve exits non-zero
+challenge-plans run path/to/spec.md --type spec --sink markdown --lang zh                # findings written in Chinese
+# not pip-installed? prefix with: PYTHONPATH=src python3 -m challenge_plans.cli ...
+```
+
+Ready-to-run samples live in [`examples/`](examples/) (`spec-sample.md`, `options.yaml`). `options.yaml`:
+```yaml
+question: Refactor auth with approach A or B?
+options:
+  - id: A
+    text: One-shot rewrite — concentrated risk, clean result
+  - id: B
+    text: Incremental migration — slower, every step reversible
+```
+
+- `--profile fast|standard|deep`, `--sink stdout|markdown`, `--enforce` (non-approve verdicts exit non-zero; advisory exit 0 by default).
+- `--lang <code>` writes the human-readable output in your language (default `en`) — see [below](#output-in-your-language).
+- `[sev✓]` = cross-family verified, may hard-gate; `[sev?]` = unverified, advisory only.
+- **Artifact types:** `--type spec` and `--type diff` are supported; `plan` / `decision` are reserved (rubric pending).
+
+The bundled [SKILL.md](SKILL.md) routes **review/QA** of a plan/spec to `run` automatically; option-voting is the `weigh` subcommand.
+
+### Output in your language
+
+challenge-plans ships an English codebase, but the reviewers can answer in **any** language — just add `--lang`:
+
+```bash
+challenge-plans run plan.md --type spec --lang zh     # objections, evidence, reproductions in Chinese
+challenge-plans weigh options.yaml --lang ja          # deliberation reasons in Japanese
+```
+
+`--lang` only switches the **human-readable prose** (steelman, titles, evidence, reproductions, vote reasons). JSON keys, enum values, and `L12-15` line anchors stay verbatim, so parsing, dedup, and CI gates are unaffected. It's equivalent to exporting `CHALLENGE_PLANS_LANG` once. There's no separate translated build to maintain — the same English source localizes on demand.
+
+**As an agent skill:** your agent just passes `--lang <your-language>` and the whole cross-review comes back localized. The bundled [SKILL.md](SKILL.md) documents the flag so the calling agent can set it from the user's language automatically.
+
+## Two modes
+
+challenge-plans isn't one feature — it's two modes on one engine. The **calling agent routes by intent**; the user never has to pick:
+
+| | **challenge** (adversarial) | **weigh-options** (deliberation) |
+|---|---|---|
+| When | You have a **drafted** plan/spec to poke holes in / harden | You have **several options / a pile of to-dos** and aren't sure which |
+| Routing signal | a single drafted artifact + "review / find flaws / can this execute" | multiple candidates + "which one / rank these / is it worth it" |
+| Aggregation | **Evidence survival** — a minority can be right, **no majority vote** | **Weighted majority + exposed dissent** — only genuine trade-offs get voted on |
+| Output | 6-state verdict + surviving objections + reproductions / counter-evidence | ranked options + vote tally + strongest dissent |
+
+**The agent picks the mode — it isn't dumped on the user:** it reads the intent and routes "review a drafted artifact" to adversarial mode and "choose among options" to deliberation, with deterministic routing signals defining the boundary. During deliberation, if an option is flagged with a **mechanically verifiable blocker**, the recommendation is **downgraded to `discuss` and you're asked to verify it in challenge mode** rather than adopting it outright — so a vote can never outweigh a falsifiable minority objection.
+
+## How it works
+
+**Adversarial mode** (reduce-rework loop):
+```
+drafted artifact + bounded context
+  → multiple persona/CLI challengers each steelman → find flaws (bound to specific text, no hedging)
+  → Verifier (cross-family) produces a minimal reproduction / contradicting source line
+  → dedup by canonical key + evidence-survival
+  → single verdict pipeline → 6-state verdict + panel-integrity check
+  → (--deep: multi-round to two-condition convergence)
+```
+
+**Deliberation mode** — the methodology is a strict three-phase flow. The `weigh` CLI implements phase ③ (it votes on the options you hand it); phases ①② are the calling agent's responsibility before invoking it — **no shortcuts**:
+```
+① align    (agent) share full background with every voter first — the question, constraints, known facts — don't pre-supply options
+② collect  (agent) each voter independently, unseen by the others and not fed the orchestrator's preferences, generates candidates → dedup/cluster into an option pool
+③ vote     `challenge-plans weigh` votes on that option pool (model_family-weighted to block false consensus) → ranking + tally + dissent
+           hands back to a human only on a tie / missing votes; otherwise closes the loop and returns a result
+```
+
+## What it guards against — 7 multi-agent failure modes
+
+These traps are ones a naive multi-agent setup almost always falls into — and ones **we hit ourselves while building this tool with its own adversarial process**. Each guard is built into the design, and the design is dogfooded:
+
+1. **Vote/finding loss** — a challenger is truncated/timed-out/unparseable and the system silently aggregates a partial panel. **Guard:** machine-readable capture + per-voter integrity self-check; missing votes never approve or declare a majority.
+2. **Option anchoring** — the orchestrator only offers its own pre-picked options, so agents merely ratify the framing. **Guard:** deliberation always diverges (generate first, vote second); voters aren't fed the orchestrator's preferences.
+3. **Premature hand-off** — the orchestrator bounces the open decision back to the human mid-way instead of finishing the vote. **Guard:** close the loop and return a result; hand back only on a tie / missing votes.
+4. **Majority over minority** — out-voting a minority that has a reproducible blocker. **Guard:** two modes with split aggregation + the escape gate; adversarial mode bans voting and lets evidence beat headcount.
+5. **Single-round complacency** — one pass declared sufficient. **Guard:** `--deep` multi-round to convergence + adversarial review of the code itself before shipping.
+6. **False consensus** — same-model personas counted as independent votes, so one model's bias gets cloned into a "majority". **Guard:** per-`model_family` weight cap, raw/weighted both shown, single-family warning.
+7. **False convergence** — declaring "done" when no *new* objection appeared but an old blocker is still open. **Guard:** two-condition convergence (new_surviving == 0 **and** unresolved_required == 0).
+
+## Backends
+
+challenge-plans drives whatever subscription coding CLI you already have logged in — e.g. **Claude Code** (`claude`) or **OpenAI Codex** (`codex`). You don't need any specific one. With **two different vendors** it can cross-verify findings; with one, results stay advisory. No API keys, and no per-token API charges from this tool (`doctor` checks the CLIs are logged in, not your billing; usage still counts against your normal subscription limits).
+
+## Status
+
+**v1 — usable.** Both modes work end-to-end, validated against a real spec and pinned by a pytest suite, hardened across multiple cross-agent adversarial-review rounds.
+
+Known boundaries (also reflected in the run output): concern dedup is exact-anchor only; no idle-timeout (wall-clock only); deliberation blockers are flagged, not yet auto-verified by the Verifier; the open-decision divergence phase is the calling agent's job; `manual_paste`/Gemini adapters are follow-ups.
+
+## Testing
+
+```bash
+pip install -e ".[dev]" && pytest      # pythonpath/testpaths preconfigured
+```
+The suite pins every invariant established across the adversarial-review rounds.
+
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). The project is dogfooded: reviewing your own change with `challenge-plans run <change>.diff --type diff` before opening a PR is encouraged.
+
+## License
+
+[Apache-2.0](LICENSE).

challenge_plans-0.1.0/README-zh.md

@@ -0,0 +1,159 @@
+# challenge-plans（中文）
+
+[![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue.svg)]()
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/hiadrianchen/challenge-plans/ci.yml?branch=main)](https://github.com/hiadrianchen/challenge-plans/actions)
+
+> English: [README.md](README.md)
+
+**在执行一份 plan/spec 之前，用你已登录的编码 CLI 对它做多 agent 对抗式评审。无需 API key。**
+
+`challenge-plans` 编排你本机已有的订阅编码 CLI（Claude Code、Codex…）交叉拷问一份 plan/spec，把会导致后续返工的坑提前挖出来；拿不准时还能对多个选项投票。它也能审一份 `git diff`、当一次轻量 **code review**，并可作为 **agent skill** 接入。它跑在你已有的订阅上，没有按 token 的 API 费用。卡进 superpowers 计划生命周期：`writing-plans → challenge-plans → executing-plans`。
+
+```text
+$ challenge-plans run plan.md --type spec --profile standard --sink markdown
+
+# challenge-plans · challenge · verdict: request_changes
+- panel: expected 3 / collected 3 · complete ✓
+- diversity: 2 families
+- verified: 3 high/critical reviewed by Verifier (✓ verified, may hard-gate; ? unverified, advisory)
+- surviving objections: 4
+
+- [high✓]   sensitive data sent to a third-party LLM with no privacy boundary  @L42-43  (security_or_privacy_boundary, by claude:scope-boundary)
+- [high✓]   "schema-aligned" claimed but there's no contract test             @L12-30  (integration_contract_gap, by gpt:correctness)
+- [high✓]   no measurable acceptance threshold                               @L1      (contract_violation, by preflight)
+- [medium?] missing_fields vs null semantics left undefined                  @L32-34  (ambiguity_to_wrong_implementation)
+```
+
+## 为什么用 challenge-plans
+
+- 🔑 **无 API key、不按量计费** —— 驱动你已登录的订阅 CLI（Claude Code、Codex），至少有一个即可。
+- 🧪 **证据胜过人数** —— 一条带可复现反证的少数派异议可以压过多数票；正确性不靠投票决定。
+- 🤝 **跨家族验证** —— 一条异议只有当**另一个独立模型家族**用具体、带行锚的证据复现后，才获得硬 gate 资格（`✓`）；单模型声明只算 advisory。
+- 🛡️ **内建防住 7 个多 agent 编排失败模式** —— 票据丢失、选项锚定、半途甩锅、多数压少数、单轮即收、虚假共识、假收敛。每一个都是开发本工具时用它自己的对抗流程真实踩中并修掉的。
+- 🌍 **按你的语言输出** —— 源码是英文，但 `--lang zh`（或 `ja`、`de`、`fr`…）让每个评审都用你的语言写结论，而 JSON 键与行锚保持机器稳定。一个参数搞定，不另维护翻译版本 —— 见 [按你的语言输出](#按你的语言输出)。
+
+## 快速开始
+
+需要 Python ≥ 3.10（PyYAML 自动安装）。至少有一个已登录的编码 CLI —— **Claude Code**（`claude`）或 **OpenAI Codex**（`codex`）；两个不同厂商解锁跨家族验证。
+
+```bash
+git clone https://github.com/hiadrianchen/challenge-plans && cd challenge-plans
+pip install -e .                                                          # 暴露 `challenge-plans` 命令
+challenge-plans doctor                                                    # 看哪些后端 CLI 已登录
+challenge-plans run examples/spec-sample.md --type spec --sink markdown   # 在自带样例上跑出一个 verdict
+```
+
+也可以把 repo 交给你的编码 agent —— *“从这个 repo 安装并配置好 challenge-plans，然后跑 `challenge-plans doctor`”* —— 它会替你做上面这些。**作为 agent skill**：把 [SKILL.md](SKILL.md) 放到你 agent 发现 skill 的目录即可。
+
+## 使用
+
+```bash
+challenge-plans doctor                                                                 # 哪些后端就绪
+challenge-plans run path/to/spec.md --type spec --profile standard --sink markdown     # 硬化一份 plan/spec
+challenge-plans run change.diff --type diff --sink markdown                             # 审一份 git diff
+challenge-plans weigh path/to/options.yaml --profile standard --sink markdown           # 在多个选项间投票
+challenge-plans run path/to/spec.md --enforce                                           # CI gate：非 approve 退非零
+challenge-plans run path/to/spec.md --type spec --sink markdown --lang zh                # 异议/证据用中文输出
+# 未 pip 安装时前缀：PYTHONPATH=src python3 -m challenge_plans.cli ...
+```
+
+[`examples/`](examples/) 有可直接跑的样例（`spec-sample.md`、`options.yaml`）。`options.yaml`：
+```yaml
+question: 重构鉴权用方案 A 还是 B？
+options:
+  - id: A
+    text: 一次性重写——风险集中但干净
+  - id: B
+    text: 渐进迁移——慢但每步可回滚
+```
+
+- `--profile fast|standard|deep`、`--sink stdout|markdown`、`--enforce`（非 approve 退非零；默认 advisory 退 0）。
+- `--lang <代码>` 让人类可读输出用你的语言（默认 `en`）—— 见 [下文](#按你的语言输出)。
+- `[sev✓]` = 跨家族已验证、可硬 gate；`[sev?]` = 未验证、仅 advisory。
+- **artifact 类型：** `--type spec` 与 `--type diff` 均可用；`plan` / `decision` 保留（rubric 待补）。
+
+bundled 的 [SKILL.md](SKILL.md) 自动把“审/QA 一份 plan/spec”路由到 `run`；投票走 `weigh` 子命令。
+
+### 按你的语言输出
+
+challenge-plans 源码是英文的，但评审可以用**任意**语言作答 —— 加上 `--lang` 即可：
+
+```bash
+challenge-plans run plan.md --type spec --lang zh     # 异议、证据、复现用中文
+challenge-plans weigh options.yaml --lang ja          # 议事理由用日语
+```
+
+`--lang` 只切换**人类可读的文字**（steelman、标题、证据、复现、投票理由）。JSON 键、枚举值、`L12-15` 行锚保持原样，所以解析、去重、CI gate 都不受影响。等价于设一次 `CHALLENGE_PLANS_LANG`。没有另一份翻译版本要维护 —— 同一份英文源按需本地化。
+
+**作为 agent skill：** agent 只要传 `--lang <用户语言>`，整份交叉 review 就用该语言返回。bundled 的 [SKILL.md](SKILL.md) 写明了这个参数，方便调用 agent 据用户语言自动设置。
+
+## 两种模式
+
+challenge-plans 不是单一功能，而是同一引擎上的两种模式。**调用 agent 按意图自动路由**，用户无需手动指定：
+
+| | **对抗模式（challenge）** | **议事模式（weigh-options）** |
+|---|---|---|
+| 何时 | 有一份**成型的** plan/spec 要挑刺/硬化 | 有**几个选项 / 一堆 to-do** 拿不准选哪个 |
+| 路由信号 | 单一成型 artifact + “帮我审/找漏洞/能不能执行” | 多个候选 + “选哪个/排序/值不值得做” |
+| 聚合 | **证据存活制**：少数派可对，**禁多数投票** | **加权多数 + 暴露异议**：纯偏好取舍才投票 |
+| 产出 | 六态 verdict + 存活异议 + 复现反证 | 排序选项 + 票数 + 最强异议 |
+
+**模式由 agent 选、不甩给用户**：agent 读意图 → “审成型 artifact”走对抗、“在选项里挑”走议事，边界由确定性路由信号判定。议事中若某选项被标出**可机械验证的硬伤(blocker)**，推荐**降级为 `discuss` 并提示你去 challenge 模式核验**，而非径自采纳——所以投票永远压不掉能被证伪的少数派。
+
+## 工作原理
+
+**对抗模式**（reduce-rework loop）：
+```
+成型 artifact + bounded context
+  → 多 persona/CLI challenger 各自 steelman→找漏洞(绑具体文本,禁hedging)
+  → Verifier 跨家族出最小可复现反证 / 矛盾源行
+  → 按 canonical key 去重 + 证据存活判定
+  → 单一裁决管线出 verdict(六态) + 面板完整性核对
+  →(--deep: 多轮到双条件收敛)
+```
+
+**议事模式** —— 方法论是标准三段。`weigh` CLI 实现第 ③ 段（对你给定的选项投票）；①② 段由调用 agent 在调用前负责，**禁止抄近路**：
+```
+① 背景对齐  (agent) 先给所有 voter 充分背景(待决问题/约束/已知信息), 不预设选项
+② 意见收集  (agent) 各 voter 独立·互不可见·不被喂主控偏好地发散生成候选 → 去重聚类成选项池
+③ 组织投票  `challenge-plans weigh` 对该选项池投票(model_family 加权防虚假共识) → 排序+票数+异议
+           平票/缺票才交人, 否则完成闭环带回结果
+```
+
+## 它内建防住的 7 个多 agent 失败模式
+
+这些坑是 naive 多 agent 编排几乎必踩的，也是我们**用对抗流程开发本工具时自己真实踩出来的**——每一个都被设计成机制挡住（dogfood 出来的护城河）：
+
+1. **票据丢失**：challenger 输出被截断/超时/解析失败，系统静默拿残缺面板聚合。**防**：机械可读捕获 + 逐 voter 完整性自检；缺票绝不出 approve/宣布多数。
+2. **选项锚定**：主控只抛自己预选的选项让大家投。**防**：议事必走“发散在前、投票在后”，voter 不被喂主控偏好。
+3. **半途甩锅**：主控中途把开放决定甩回人工而不完成投票。**防**：完成闭环带回结果，仅平票/缺票才交人。
+4. **多数压少数**：用多数投票否掉有可复现 blocker 的少数派真问题。**防**：两模式分治 + 串联逃逸门，对抗模式禁投票、证据压票数。
+5. **单轮即收**：一轮对抗就宣布够了。**防**：`--deep` 多轮到收敛 + 写码前对代码再对抗。
+6. **虚假共识**：同模型多 persona 的票被当独立票。**防**：按 model_family 加权封顶、raw/weighted 双显、单家族告警。
+7. **假收敛**：某轮没新异议但旧 blocker 还 open 就宣布收敛。**防**：双条件收敛（new_surviving==0 且 unresolved_required==0）。
+
+## 后端
+
+challenge-plans 驱动你已登录的任一订阅编码 CLI —— 如 **Claude Code**（`claude`）或 **OpenAI Codex**（`codex`）。**不绑定任何特定一家。** 有**两个不同厂商**时可跨家族互验；只有一个时结论保持 advisory。无 API key、本工具不产生 per-token API 费用（`doctor` 只验登录、不查账单；用量仍计入你正常订阅额度）。
+
+## 状态
+
+**v1 — 可用。** 两模式端到端可跑，对真实 spec 验证过、由 pytest 套件钉住不变量，经多轮跨 agent 对抗 review 加固。
+
+已知边界（输出里亦标）：concern 去重为精确锚点；无 idle-timeout（用墙钟）；议事 blocker 目前只标注、尚未自动转 Verifier 核验；开放决策的发散阶段由调用 agent 负责；`manual_paste`/Gemini adapter 为后续。
+
+## 测试
+
+```bash
+pip install -e ".[dev]" && pytest      # pythonpath/testpaths 已配
+```
+测试套件钉住了历次对抗 review 确立的全部不变量。
+
+## 贡献
+
+欢迎 issue / PR —— 见 [CONTRIBUTING.md](CONTRIBUTING.md)。本项目 dogfood：开 PR 前用 `challenge-plans run <change>.diff --type diff` 审一遍自己的改动。
+
+## 许可
+
+[Apache-2.0](LICENSE)。