quantum-reasoning-skill 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# Quantum Reasoning Skill
+> **Superseded:** this standalone skill was merged into **Axiomize 2.0** and now lives as
+> `axiomize.reasoning` in **[Furox-Art/axiomize-quantum-skills-2.0](https://github.com/Furox-Art/axiomize-quantum-skills-2.0)**,
+> where it ships next to the scientific modeling engine as `skills/quantum-reasoning/`.
+> New work, issues, and contributions should go to the Axiomize repo. This repository is kept
+> for historical reference and will be archived.
+
+A **model-agnostic reasoning skill** that keeps multiple genuinely different possibilities alive, verifies and compares them, suppresses weak paths, revives useful alternatives when evidence changes, and selects the best-supported result only at the end.
+
+> This is quantum-inspired classical reasoning, not quantum computation.
+
+## Main artifact
+
+The project is centered on [`SKILL.md`](./SKILL.md). The skill changes the model's reasoning procedure without retraining the model.
+
+```text
+problem
+  -> open diverse possibilities
+  -> verify independently
+  -> compare contradictions and shared assumptions
+  -> score / classify branches
+  -> allocate compute dynamically
+  -> suspend or reject weak branches
+  -> revive branches when evidence changes
+  -> verify collapse criteria
+  -> select the best-supported answer
+```
+
+## Design goals
+
+- Reduce early lock-in to the first plausible answer.
+- Maintain genuinely independent hypotheses or solution strategies.
+- Prefer falsification and tool-based verification over self-confidence.
+- Expand search when uncertainty is high and concentrate compute when evidence is strong.
+- Detect correlated branches so repeated assumptions are not counted as independent evidence.
+- Keep high-information alternatives recoverable instead of deleting them too early.
+- Work across hosts that can preserve the skill instruction contract.
+- Make reasoning-control decisions measurable without exposing private chain-of-thought.
+
+## Repository contents
+
+- [`SKILL.md`](./SKILL.md) — model-facing protocol
+- [`reference/branch_controller.py`](./reference/branch_controller.py) — deterministic reference scoring, state transition, revival, uncertainty and collapse logic
+- [`docs/MEASUREMENT.md`](./docs/MEASUREMENT.md) — explicit formulas, thresholds and calibration requirements
+- [`docs/COMPATIBILITY.md`](./docs/COMPATIBILITY.md) — capability-based host compatibility contract
+- [`examples/usage.md`](./examples/usage.md) — task examples
+- [`examples/host-integration.md`](./examples/host-integration.md) — generic host integration patterns
+- [`benchmark/cases.jsonl`](./benchmark/cases.jsonl) — deterministic seed cases
+- [`benchmark/evaluate.py`](./benchmark/evaluate.py) — baseline-vs-skill evaluator
+- [`benchmark/validate_submission.py`](./benchmark/validate_submission.py) — reproducible community-result bundle validator
+- [`benchmark/schemas/`](./benchmark/schemas/) — JSON Schema contracts for cases, metadata, result rows and comparison output
+- [`benchmark/README.md`](./benchmark/README.md) — reproducible benchmark protocol
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contribution and independent benchmark-submission policy
+- [`SECURITY.md`](./SECURITY.md) — vulnerability-reporting policy
+- [`CITATION.cff`](./CITATION.cff) — citation metadata
+- [`tests/`](./tests/) — behavioral and validation tests
+- GitHub Actions validation on pushes and pull requests
+- CI-gated automated tag and GitHub Release publishing
+
+## Core capabilities
+
+- Adaptive multi-branch reasoning
+- Semantic diversity requirements
+- Active / dormant / rejected branch states
+- Independent verification rules
+- Contradiction and shared-assumption checks
+- Correlation penalty for duplicated/shared-assumption branches
+- Interference-like cross-branch comparison
+- Dynamic compute allocation from uncertainty
+- Measurable branch revival rules
+- Explicit stopping / collapse criteria
+- Baseline-vs-skill benchmark telemetry
+- Final requirement and contradiction check
+
+## Usage
+
+Install or provide `SKILL.md` to a compatible agent/skill system, then invoke it for difficult reasoning tasks. No Python package or model fine-tuning is required to use the skill itself.
+
+See [`docs/COMPATIBILITY.md`](./docs/COMPATIBILITY.md) before integrating a new host and [`examples/host-integration.md`](./examples/host-integration.md) for generic installation patterns.
+
+The Python reference implementation is optional. It exists to make the qualitative policy auditable and testable:
+
+```python
+from reference.branch_controller import Branch, BranchMetrics, collapse_decision
+```
+
+## Benchmarking
+
+The repository provides the **protocol, cases, schemas, evaluator and submission validator** needed to test the skill. Real model evaluations are intentionally **community-run**: users test the models/providers they have access to and may submit reproducible results back to the project.
+
+The project does not require the maintainer to run every commercial or local model, and it does not treat the absence of maintainer-run model tests as a missing implementation feature.
+
+A valid comparison uses the **same model, model version, task set, tool access, temperature/sampling settings and token-budget policy** with and without `SKILL.md`.
+
+```bash
+python benchmark/evaluate.py \
+  --cases benchmark/cases.jsonl \
+  --baseline path/to/baseline-results.jsonl \
+  --skill path/to/skill-results.jsonl \
+  --output comparison.json
+```
+
+Community PR bundles are machine-checked. They must contain their own `cases.jsonl`, raw baseline and skill JSONL files, metadata, the generated comparison output and a short README. CI recomputes the comparison and rejects tampered or incomplete bundles.
+
+```bash
+python benchmark/validate_submission.py \
+  --root benchmark/results/community \
+  --allow-empty
+```
+
+Third-party results remain measurements from their submitters, not automatic project endorsements or universal performance claims. A single positive run is not enough to claim general improvement.
+
+Users can submit results through the **Benchmark result** issue template or as a reproducible benchmark-result pull request. See [`benchmark/README.md`](./benchmark/README.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+## Validation
+
+Run the repository checks locally with:
+
+```bash
+python -m unittest discover -s tests -v
+python benchmark/evaluate.py --help
+python benchmark/validate_submission.py --root benchmark/results/community --allow-empty
+```
+
+CI validates the skill contract, local links, Python syntax, benchmark seed data, JSON Schema files, community benchmark bundles and behavioral tests. Third-party GitHub Actions are pinned to exact commit SHAs.
+
+## Releases
+
+Release publishing is repository-native and CI-gated. Update `CHANGELOG.md`, then change the root `VERSION` file to a semantic version. A release is considered only after the `validate-skill` workflow succeeds on `main`; the `publish-release` workflow then creates the corresponding `v<version>` tag and GitHub Release if it does not already exist.
+
+## Status
+
+**v0.3.1 — hardened measurable prototype.** The branch-control mechanism, benchmark infrastructure, host compatibility contract, community-result validation, repository security/citation metadata and CI-gated release controls are implemented. Real-model evaluation is intentionally delegated to independent users and contributors, and the project makes no universal performance claim without reproducible external evidence.

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are applied to the current `main` branch and the latest published release.
+
+## Reporting a vulnerability
+
+Do not publish exploit details, credentials, tokens, private benchmark data, or other sensitive material in a public issue.
+
+Prefer GitHub's private **Report a vulnerability** / Security Advisory flow when it is available for this repository. If that private channel is unavailable, open a minimal public issue that only requests a private contact path and does not include vulnerability details.
+
+## Scope
+
+Relevant reports include vulnerabilities in repository automation, benchmark ingestion/validation, release workflows, or reference code that could cause untrusted contributed content to execute unexpectedly, alter releases, or expose secrets.
+
+Reasoning-quality disagreements and ordinary protocol bugs are not security vulnerabilities; use the normal bug-report issue form for those.

package/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: quantum-reasoning
+description: Maintain multiple genuinely different candidate hypotheses or solution paths, test them against evidence and tools, suppress weak or contradictory paths, revive useful alternatives when new evidence appears, and collapse to the best-supported answer only at the end.
+---
+
+# Quantum Reasoning Skill
+
+A model-facing reasoning protocol inspired by the idea of keeping multiple possibilities alive before selection. It runs on classical models and classical hardware; it is not quantum computation.
+
+## When to use
+
+Use this skill when a problem is difficult, ambiguous, high-stakes, multi-step, or vulnerable to early commitment: mathematics, scientific reasoning, debugging, planning, architecture, model selection, hypothesis testing, and technical diagnosis.
+
+Do not add branching overhead to trivial questions.
+
+## Core protocol
+
+### 1. Frame the state
+
+Identify the objective, constraints, verified facts, assumptions, unknowns, and available tools. Keep facts separate from hypotheses.
+
+### 2. Open a diverse possibility set
+
+Create several materially different candidate paths. Diversity is mandatory: do not count paraphrases, cosmetic variants, or branches that depend on the same hidden assumption as independent possibilities.
+
+Prefer orthogonal strategy classes when applicable, such as:
+
+- direct derivation
+- counterexample / falsification
+- decomposition
+- alternative model or mechanism
+- numerical or executable test
+- independent reconstruction
+- adversarial critique
+
+### 3. Maintain branch states
+
+Treat each candidate as one of:
+
+- **active** — worth more compute now
+- **dormant** — currently weak but potentially recoverable
+- **rejected** — contradicted or decisively invalidated
+
+Never permanently reject a branch merely because another branch initially looks more plausible.
+
+### 4. Evaluate each branch independently
+
+Judge branches using evidence, not eloquence. Consider:
+
+- empirical or logical support
+- external verification
+- independence from other branches
+- information gain
+- contradiction count and severity
+- unresolved assumptions
+- expected value of another reasoning step
+- compute / tool cost
+
+Self-reported model confidence alone is weak evidence.
+
+### 5. Use tools to falsify, not merely confirm
+
+When available, route claims through the strongest suitable verifier: executable code, numerical tests, formal solvers, source lookup, direct file inspection, unit tests, symbolic algebra, or an independent model pass.
+
+Actively search for evidence that would disprove leading branches.
+
+### 6. Apply interference-like comparison
+
+Compare branches against each other without pretending to perform quantum interference.
+
+- Reinforce conclusions independently reached by different verified paths.
+- Penalize branches that conflict with verified facts.
+- Detect shared assumptions so correlated branches are not double-counted.
+- Transfer newly verified facts to every branch they constrain.
+- Preserve meaningful disagreement instead of averaging incompatible claims.
+
+### 7. Allocate compute dynamically
+
+Use uncertainty to control width and depth.
+
+- **Low uncertainty:** narrow quickly and deepen the strongest path.
+- **High uncertainty:** widen the possibility set.
+- **High-value unresolved branch:** spend additional tool or reasoning budget.
+- **Redundant or contradicted branch:** move to dormant or rejected.
+
+Branch count is adaptive, not fixed.
+
+### 8. Permit branch revival
+
+If new evidence invalidates a leading assumption or materially improves a dormant branch, restore that branch to active status and re-evaluate the ranking.
+
+### 9. Stop when more search has low value
+
+Collapse the possibility set when one result is sufficiently verified, remaining branches are redundant or falsified, or additional search is unlikely to change the decision enough to justify its cost.
+
+If multiple branches remain genuinely unresolved, report the alternatives and what evidence would distinguish them.
+
+### 10. Produce the answer
+
+Synthesize only from the strongest supported surviving branches. Run a final contradiction and requirement check before answering.
+
+Do not expose hidden chain-of-thought. Return the conclusion, concise supporting evidence, important uncertainty, and materially different surviving alternatives when necessary.
+
+## Adaptive intensity
+
+Use a rough internal intensity level:
+
+- **light:** 2–3 distinct candidates, one comparison pass
+- **standard:** 4–8 candidates, verification + pruning + one revival check
+- **deep:** 8+ candidates only when the problem and compute budget justify it; use repeated verification and adaptive expansion
+
+Do not mechanically maximize branch count. The goal is better search of the possibility space, not more text.
+
+## Operational reference policy
+
+When the host system can track aggregate branch metadata, use explicit normalized values in `[0, 1]` for evidence, verification, independence, information gain, contradiction severity, unresolved assumptions, compute cost, shared-assumption overlap, and semantic redundancy.
+
+A provider-agnostic reference controller is available in [`reference/branch_controller.py`](./reference/branch_controller.py). Its defaults make the qualitative protocol testable:
+
+- independence is reduced when branches share critical assumptions or are near-duplicates
+- strong contradiction can reject a branch
+- weak branches become dormant instead of disappearing
+- dormant branches can revive after a material evidence, verification, or contradiction change
+- uncertainty controls a recommended search width
+- collapse requires a verified leader, low contradiction, and a meaningful margin over surviving alternatives
+
+The exact scoring weights and thresholds are **reference defaults, not validated constants**. They must be calibrated against benchmark evidence rather than treated as universal truths. See [`docs/MEASUREMENT.md`](./docs/MEASUREMENT.md) for the auditable formulas and thresholds.
+
+Hosts that cannot expose these aggregate measurements should still follow the qualitative protocol above and must not invent numeric telemetry.
+
+## Benchmark requirement
+
+Do not claim that this skill improves reasoning merely because the protocol sounds plausible. Compare the same model and task configuration with and without the skill and measure at least accuracy, compute/token cost, latency, error recovery, contradiction resolution, and branch diversity when observable.
+
+The reproducible benchmark schema and evaluator live under [`benchmark/`](./benchmark/README.md).
+
+## Non-negotiable rules
+
+1. Do not call this real quantum computation.
+2. Do not treat repeated wording as independent evidence.
+3. Do not let one branch evaluate itself without challenge when verification is possible.
+4. Prefer falsification and executable checks over intuition.
+5. Preserve a recoverable record of high-information dormant branches.
+6. Collapse only after cross-branch comparison.
+7. Never fabricate evidence, tool results, sources, certainty, or branch telemetry.
+8. Do not present reference thresholds as empirically validated until benchmark evidence exists.

package/VERSION

@@ -0,0 +1 @@
+0.3.1

package/benchmark/README.md

@@ -0,0 +1,134 @@
+# Benchmark protocol
+
+This directory measures whether the skill improves results rather than merely producing more reasoning text.
+
+## Who runs the benchmarks
+
+Real model evaluations are intentionally **community-run**. The repository supplies the benchmark protocol, seed cases, JSON Schemas, evaluator and submission validator; users run experiments on the models/providers they have access to.
+
+Maintainer-run access to every commercial or local model is not required. The project therefore separates **benchmark infrastructure** from **third-party empirical results**.
+
+Submitted results are evidence from the contributor who produced them. They are not automatically endorsed by the project and should not be generalized beyond the tested model/version/configuration without replication.
+
+## Principle
+
+Run the **same model, model version, task set, tool access, temperature/sampling settings, and token budget policy** twice:
+
+1. baseline: normal instructions without `SKILL.md`
+2. skill: the same setup with `SKILL.md`
+
+Do not compare different models and attribute the difference to the skill.
+
+## Seed cases
+
+`cases.jsonl` contains deterministic smoke-test cases. They are intentionally small and are **not sufficient evidence of reasoning improvement**. A serious evaluation should add difficult held-out tasks from the target domains and report their provenance/licensing.
+
+Each case has:
+
+```json
+{"id":"...","domain":"...","prompt":"...","accepted_answers":["..."]}
+```
+
+## Machine-readable schemas
+
+The contracts are versioned with the repository:
+
+- [`schemas/case.schema.json`](./schemas/case.schema.json) — one benchmark case
+- [`schemas/result.schema.json`](./schemas/result.schema.json) — one baseline/skill result row
+- [`schemas/metadata.schema.json`](./schemas/metadata.schema.json) — experiment metadata
+- [`schemas/comparison.schema.json`](./schemas/comparison.schema.json) — evaluator comparison output
+
+A result row requires:
+
+```json
+{
+  "case_id": "math-arithmetic-001",
+  "answer": "323",
+  "tokens": 120,
+  "tool_calls": 0,
+  "latency_ms": 950
+}
+```
+
+Failed/refused runs should still be represented rather than silently removed. The optional `status` field may be `ok`, `refusal`, `timeout`, or `error`.
+
+Skill-aware runners may additionally record observable aggregate telemetry such as `branches_total`, `branches_distinct`, `revived_branches`, `recovered_errors`, `contradictions_found`, and `contradictions_resolved`. Do not store private chain-of-thought.
+
+## Evaluate one run
+
+```bash
+python benchmark/evaluate.py \
+  --cases benchmark/cases.jsonl \
+  --skill path/to/skill-results.jsonl
+```
+
+## Compare baseline vs skill
+
+```bash
+python benchmark/evaluate.py \
+  --cases benchmark/cases.jsonl \
+  --baseline path/to/baseline-results.jsonl \
+  --skill path/to/skill-results.jsonl \
+  --output comparison.json
+```
+
+The evaluator reports exact-answer accuracy, mean token use, tool calls, latency, branch diversity, revival/error recovery, contradiction resolution, and baseline-to-skill deltas.
+
+## Required experimental controls
+
+For a publishable comparison, record at minimum:
+
+- provider and exact model/version
+- date of the run
+- decoding/sampling parameters
+- context and output limits
+- tool availability
+- prompt wrapper/system instructions
+- number of repetitions per case
+- random seed when the provider supports one
+- hardware/runtime details for local models
+- failures, refusals and timeouts rather than silently dropping them
+
+Use multiple repetitions for stochastic models and report confidence intervals. Keep benchmark cases separate from any prompts used while designing or tuning the skill.
+
+## Submitting community results
+
+Results can be submitted in either of two ways:
+
+1. Open a **Benchmark result** issue and provide the required metadata plus links/attachments to the result artifacts.
+2. Open a pull request containing a reproducible result bundle under:
+
+```text
+benchmark/results/community/<provider>-<model>-<YYYY-MM-DD>/
+```
+
+Every benchmark-result PR bundle must contain:
+
+```text
+metadata.json
+cases.jsonl
+baseline.jsonl
+skill.jsonl
+comparison.json
+README.md
+```
+
+Including `cases.jsonl` inside the bundle makes the exact evaluated case set immutable and reviewable even when custom cases are used.
+
+Generate `comparison.json` with `benchmark/evaluate.py`; do not hand-edit it. Before opening a PR, validate the bundle:
+
+```bash
+python benchmark/validate_submission.py --root benchmark/results/community
+```
+
+CI runs the same validator. It rejects missing artifacts, incomplete metadata, duplicate/missing case results, and a `comparison.json` that differs from a fresh evaluator recomputation.
+
+See [`../CONTRIBUTING.md`](../CONTRIBUTING.md) for the complete submission and integrity policy.
+
+## Interpretation
+
+A useful result is not simply "skill accuracy is higher". Report the trade-off between accuracy and compute. A skill that gains 1 percentage point while using 5x tokens may be undesirable for many workloads.
+
+The reference thresholds in `reference/branch_controller.py` are defaults to test, not validated constants. Benchmark evidence should drive later calibration.
+
+The project makes no universal performance claim from a single model, provider, benchmark or contributor submission. Independent replication is preferred.

package/benchmark/cases.jsonl

@@ -0,0 +1,6 @@
+{"id":"math-arithmetic-001","domain":"mathematics","prompt":"Compute 17 * 19.","accepted_answers":["323"],"notes":"Exact-answer sanity case."}
+{"id":"math-algebra-001","domain":"mathematics","prompt":"Solve x^2 - 5x + 6 = 0. Return the roots in ascending order separated by a comma.","accepted_answers":["2, 3","2,3"],"notes":"Checks independent verification of a simple factorization."}
+{"id":"logic-contradiction-001","domain":"logic","prompt":"Premises: All A are B. No B are C. Some A are C. Are the premises jointly consistent? Answer yes or no.","accepted_answers":["no"],"notes":"Requires contradiction detection."}
+{"id":"debug-python-001","domain":"debugging","prompt":"A Python function is intended to return the first item of xs: def first(xs): return xs[1]. What integer index should replace 1?","accepted_answers":["0"],"notes":"Minimal root-cause diagnosis."}
+{"id":"science-units-001","domain":"scientific-reasoning","prompt":"A car travels at 20 m/s for 15 s at constant speed. How many meters does it travel? Return only the number.","accepted_answers":["300"],"notes":"Simple quantitative verification case."}
+{"id":"probability-001","domain":"probability","prompt":"A fair coin is flipped twice. What is the probability of exactly one head? Return a decimal.","accepted_answers":["0.5",".5"],"notes":"Checks enumeration versus shortcut reasoning."}