quantum-reasoning-skill 1.0.0__tar.gz

quantum_reasoning_skill-1.0.0/.github/ISSUE_TEMPLATE/benchmark-result.yml

@@ -0,0 +1,81 @@
+name: Benchmark result
+description: Submit an independently run baseline-vs-skill model evaluation
+title: "[Benchmark] "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Submit reproducible measurements only. Do not include private chain-of-thought. For PR submissions, validate the full bundle with `python benchmark/validate_submission.py --root benchmark/results/community`.
+
+  - type: input
+    id: provider
+    attributes:
+      label: Provider
+      placeholder: Provider or local runtime
+    validations:
+      required: true
+
+  - type: input
+    id: model
+    attributes:
+      label: Exact model / version
+      placeholder: Exact model identifier and version if available
+    validations:
+      required: true
+
+  - type: input
+    id: skill_version
+    attributes:
+      label: Skill version / commit
+      placeholder: v0.3.1 or commit SHA
+    validations:
+      required: true
+
+  - type: input
+    id: run_date
+    attributes:
+      label: Run date
+      placeholder: YYYY-MM-DD
+    validations:
+      required: true
+
+  - type: textarea
+    id: controls
+    attributes:
+      label: Experimental controls
+      description: Describe sampling settings, context/output limits, tools, repetitions, seeds, prompt wrapper and hardware/runtime when relevant.
+    validations:
+      required: true
+
+  - type: textarea
+    id: artifacts
+    attributes:
+      label: Result artifacts
+      description: Link or attach metadata.json, cases.jsonl, baseline.jsonl, skill.jsonl, comparison.json and README.md. State whether the bundle passed validate_submission.py.
+    validations:
+      required: true
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Result summary
+      description: Report accuracy and compute/cost trade-offs. Include failures, refusals and timeouts.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: integrity
+    attributes:
+      label: Integrity checks
+      options:
+        - label: Baseline and skill used the same model/version, task set, tools, sampling settings and budget policy.
+          required: true
+        - label: I included the exact evaluated cases and did not remove failed runs, refusals or timeouts.
+          required: true
+        - label: comparison.json was generated from the submitted raw files and was not edited to improve the result.
+          required: true
+        - label: I did not include private chain-of-thought or fabricate unavailable telemetry.
+          required: true
+        - label: I disclosed modifications to SKILL.md, benchmark cases, wrappers or provider adapters.
+          required: true

quantum_reasoning_skill-1.0.0/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Report a reproducible defect in the skill, reference controller, benchmark tooling, or CI.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: What happened?
+      description: Describe the observed behavior and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Minimal reproduction
+      description: Include commands, inputs, or a small example that reproduces the problem.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Repository version or commit
+      placeholder: v0.3.0 or commit SHA
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, host/agent integration, OS, and relevant tool versions.
+  - type: checkboxes
+    id: sensitive
+    attributes:
+      label: Safety check
+      options:
+        - label: I have not included secrets, credentials, private chain-of-thought, or sensitive benchmark data.
+          required: true

quantum_reasoning_skill-1.0.0/.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,31 @@
+name: Feature request
+description: Propose a change to the reasoning protocol, tooling, benchmarks, or integration contract.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or limitation
+      description: What concrete limitation does this proposal address?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed change
+      description: Describe the behavior or interface you want to add or change.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence or evaluation plan
+      description: If this affects reasoning quality, explain how it could be tested without relying on anecdotal examples alone.
+  - type: checkboxes
+    id: scope
+    attributes:
+      label: Scope check
+      options:
+        - label: This proposal does not present unverified benchmark claims as established results.
+          required: true

quantum_reasoning_skill-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Summary
+
+Describe the change and the behavior it affects.
+
+## Validation
+
+- [ ] I ran `python -m unittest discover -s tests -v`.
+- [ ] I ran `python benchmark/evaluate.py --help`.
+- [ ] I added or updated tests when executable behavior changed.
+- [ ] I updated documentation when the public contract changed.
+- [ ] I did not include private chain-of-thought, secrets, credentials, or fabricated benchmark telemetry.
+
+## Benchmark-impacting changes
+
+If this changes `SKILL.md`, scoring, collapse/revival behavior, benchmark schemas, or evaluation logic, explain how existing results should be interpreted and whether new community runs are needed.

quantum_reasoning_skill-1.0.0/.github/workflows/npm-publish.yml

@@ -0,0 +1,32 @@
+name: npm Publish  
+  
+on:  
+  workflow_dispatch:  
+  push:  
+    branches: [main]  
+    paths:  
+      - "package.json"  
+      - "index.js"  
+  
+concurrency:  
+  group: npm-publish  
+  cancel-in-progress: false  
+  
+permissions:  
+  contents: read  
+  
+jobs:  
+  publish:  
+    runs-on: ubuntu-latest  
+    steps:  
+      - uses: actions/checkout@v4  
+  
+      - uses: actions/setup-node@v4  
+        with:  
+          node-version: "20"  
+          registry-url: "https://registry.npmjs.org"  
+  
+      - name: Publish to npm  
+        run: npm publish --access public  
+        env:  
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} 

quantum_reasoning_skill-1.0.0/.github/workflows/publish-release.yml

@@ -0,0 +1,79 @@
+name: publish-release
+
+on:
+  workflow_run:
+    workflows: ["validate-skill"]
+    types: [completed]
+    branches: [main]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-release
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+
+      - name: Resolve and validate version
+        id: version
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -s VERSION
+          version="$(tr -d '[:space:]' < VERSION)"
+          version="${version#v}"
+          if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+            echo "Invalid release version: $version" >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "tag=v${version}" >> "$GITHUB_OUTPUT"
+
+      - name: Require matching changelog entry
+        shell: bash
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          set -euo pipefail
+          grep -Fq "## [$VERSION]" CHANGELOG.md || {
+            echo "CHANGELOG.md must contain a ## [$VERSION] section before release." >&2
+            exit 1
+          }
+
+      - name: Check existing release
+        id: existing
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "$TAG already exists; nothing to publish."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create tag and GitHub Release
+        if: steps.existing.outputs.exists != 'true'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+          TARGET_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          set -euo pipefail
+          gh release create "$TAG" \
+            --target "$TARGET_SHA" \
+            --title "$TAG" \
+            --generate-notes

quantum_reasoning_skill-1.0.0/.github/workflows/validate-skill.yml

@@ -0,0 +1,154 @@
+name: validate-skill
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Validate skill repository contract
+        shell: bash
+        run: |
+          set -euo pipefail
+          for required in \
+            SKILL.md README.md LICENSE CHANGELOG.md VERSION CONTRIBUTING.md SECURITY.md CITATION.cff \
+            examples/usage.md examples/host-integration.md \
+            reference/branch_controller.py \
+            docs/MEASUREMENT.md docs/COMPATIBILITY.md \
+            benchmark/README.md benchmark/cases.jsonl benchmark/evaluate.py benchmark/validate_submission.py \
+            benchmark/schemas/case.schema.json benchmark/schemas/result.schema.json \
+            benchmark/schemas/metadata.schema.json benchmark/schemas/comparison.schema.json \
+            tests/test_reference.py tests/test_benchmark.py tests/test_submission_validation.py \
+            .github/ISSUE_TEMPLATE/benchmark-result.yml .github/ISSUE_TEMPLATE/bug-report.yml \
+            .github/ISSUE_TEMPLATE/feature-request.yml .github/PULL_REQUEST_TEMPLATE.md; do
+            test -s "$required"
+          done
+
+          python - <<'PY'
+          from pathlib import Path
+          import json
+          import re
+
+          root = Path.cwd().resolve()
+          skill = (root / "SKILL.md").read_text(encoding="utf-8")
+          lines = skill.splitlines()
+          if not lines or lines[0].strip() != "---":
+              raise SystemExit("SKILL.md must start with YAML front matter")
+          try:
+              end = next(i for i, line in enumerate(lines[1:], start=1) if line.strip() == "---")
+          except StopIteration as exc:
+              raise SystemExit("SKILL.md front matter is not closed") from exc
+          fields = {}
+          for line in lines[1:end]:
+              if ":" in line:
+                  key, value = line.split(":", 1)
+                  fields[key.strip()] = value.strip()
+          if fields.get("name") != "quantum-reasoning":
+              raise SystemExit("SKILL.md front matter must declare name: quantum-reasoning")
+          if not fields.get("description"):
+              raise SystemExit("SKILL.md front matter must contain a non-empty description")
+          if len(lines[end + 1:]) < 20:
+              raise SystemExit("SKILL.md body is unexpectedly short")
+
+          readme = (root / "README.md").read_text(encoding="utf-8")
+          for required in (
+              "SKILL.md", "examples/usage.md", "examples/host-integration.md",
+              "reference/branch_controller.py", "docs/MEASUREMENT.md", "docs/COMPATIBILITY.md",
+              "benchmark/README.md", "CONTRIBUTING.md", "SECURITY.md", "CITATION.cff",
+          ):
+              if required not in readme:
+                  raise SystemExit(f"README.md must reference {required}")
+
+          markdown_files = [
+              root / "README.md", root / "SKILL.md", root / "CONTRIBUTING.md", root / "SECURITY.md",
+              root / "examples/usage.md", root / "examples/host-integration.md",
+              root / "benchmark/README.md", root / "docs/MEASUREMENT.md", root / "docs/COMPATIBILITY.md",
+          ]
+          link_pattern = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
+          for document in markdown_files:
+              text = document.read_text(encoding="utf-8")
+              for raw_target in link_pattern.findall(text):
+                  target = raw_target.strip().split("#", 1)[0].split("?", 1)[0]
+                  if not target or "://" in target or target.startswith(("mailto:", "#")):
+                      continue
+                  resolved = (document.parent / target).resolve()
+                  try:
+                      resolved.relative_to(root)
+                  except ValueError as exc:
+                      raise SystemExit(f"{document.relative_to(root)} links outside repository: {raw_target}") from exc
+                  if not resolved.exists():
+                      raise SystemExit(f"Broken relative link in {document.relative_to(root)}: {raw_target}")
+
+          case_path = root / "benchmark" / "cases.jsonl"
+          seen_ids = set()
+          for line_number, raw in enumerate(case_path.read_text(encoding="utf-8").splitlines(), start=1):
+              if not raw.strip():
+                  continue
+              try:
+                  case = json.loads(raw)
+              except json.JSONDecodeError as exc:
+                  raise SystemExit(f"benchmark/cases.jsonl:{line_number}: invalid JSON: {exc}") from exc
+              required = {"id", "domain", "prompt", "accepted_answers"}
+              missing = required - set(case)
+              if missing:
+                  raise SystemExit(f"benchmark/cases.jsonl:{line_number}: missing {sorted(missing)}")
+              case_id = str(case["id"])
+              if case_id in seen_ids:
+                  raise SystemExit(f"duplicate benchmark case id: {case_id}")
+              seen_ids.add(case_id)
+              if not isinstance(case["accepted_answers"], list) or not case["accepted_answers"]:
+                  raise SystemExit(f"benchmark/cases.jsonl:{line_number}: accepted_answers must be non-empty")
+
+          schemas = sorted((root / "benchmark" / "schemas").glob("*.schema.json"))
+          if len(schemas) < 4:
+              raise SystemExit("expected case, result, metadata and comparison JSON Schemas")
+          for schema_path in schemas:
+              schema = json.loads(schema_path.read_text(encoding="utf-8"))
+              if schema.get("$schema") != "https://json-schema.org/draft/2020-12/schema":
+                  raise SystemExit(f"{schema_path}: expected JSON Schema draft 2020-12")
+              if schema.get("type") != "object" or not schema.get("required"):
+                  raise SystemExit(f"{schema_path}: must define an object with required fields")
+
+          version = (root / "VERSION").read_text(encoding="utf-8").strip().lstrip("v")
+          if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+(?:[.-][0-9A-Za-z.-]+)?", version):
+              raise SystemExit("VERSION is not a valid semantic version")
+          cff = (root / "CITATION.cff").read_text(encoding="utf-8")
+          for marker in ("cff-version: 1.2.0", "title:", "authors:", "repository-code:", "license: MIT"):
+              if marker not in cff:
+                  raise SystemExit(f"CITATION.cff missing {marker!r}")
+          if f"version: {version}" not in cff:
+              raise SystemExit("CITATION.cff version must match VERSION")
+
+          action_use = re.compile(r"uses:\s+(actions/[A-Za-z0-9_.-]+)@([^\s#]+)")
+          for workflow in (root / ".github" / "workflows").glob("*.yml"):
+              for action, ref in action_use.findall(workflow.read_text(encoding="utf-8")):
+                  if not re.fullmatch(r"[0-9a-f]{40}", ref):
+                      raise SystemExit(f"{workflow}: {action} must be pinned to an exact commit SHA")
+
+          print("Skill repository contract validated successfully.")
+          PY
+
+      - name: Compile Python sources
+        run: python -m compileall -q reference benchmark tests
+
+      - name: Run behavioral tests
+        run: python -m unittest discover -s tests -v
+
+      - name: Validate community benchmark bundles
+        run: python benchmark/validate_submission.py --root benchmark/results/community --allow-empty
+
+      - name: Check benchmark CLIs
+        run: |
+          python benchmark/evaluate.py --help > /dev/null
+          python benchmark/validate_submission.py --help > /dev/null

quantum_reasoning_skill-1.0.0/.gitignore

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

quantum_reasoning_skill-1.0.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [Unreleased]
+
+## [0.3.1] - 2026-09-07
+
+### Added
+
+- Community benchmark contribution policy in `CONTRIBUTING.md`.
+- GitHub **Benchmark result**, **Bug report**, and **Feature request** issue forms.
+- Pull-request checklist for tests, documentation, benchmark integrity, and sensitive-data hygiene.
+- Draft 2020-12 JSON Schemas for benchmark cases, result rows, experiment metadata, and comparison output.
+- `benchmark/validate_submission.py` for machine-validating reproducible community benchmark bundles.
+- Tests that reject missing benchmark artifacts, tampered comparisons, and incomplete integrity metadata.
+- Capability-based host compatibility contract in `docs/COMPATIBILITY.md`.
+- Generic native-skill, persistent-instruction, and controller-assisted integration examples.
+- `SECURITY.md` vulnerability-reporting policy.
+- `CITATION.cff` research-software citation metadata.
+
+### Changed
+
+- Benchmark documentation now explicitly assigns real-model evaluation to users and contributors rather than requiring maintainer-run access to every model/provider.
+- Community benchmark PRs now include the exact `cases.jsonl` used and are re-evaluated by CI from their raw baseline/skill files.
+- Third-party benchmark submissions are treated as reproducible external measurements, not automatic project endorsements or universal performance claims.
+- Release publishing now runs only after `validate-skill` succeeds on `main`; a failed validation cannot publish a release.
+- GitHub Actions dependencies are pinned to exact commit SHAs and CI enforces future pinning.
+- CI now validates schemas, version/citation consistency, host/documentation links, and community result bundles.
+
+## [0.3.0] - 2026-09-07
+
+### Added
+
+- Deterministic reference branch controller with explicit scoring and state transitions.
+- Shared-assumption and semantic-correlation penalty.
+- Quantified dormant/rejected state rules and branch revival triggers.
+- Uncertainty-based recommended search width.
+- Explicit collapse criteria and leader-margin checks.
+- Measurement specification documenting formulas and calibration requirements.
+- Reproducible baseline-vs-skill benchmark protocol.
+- Seed benchmark cases and JSONL result schema.
+- Benchmark evaluator for accuracy, token/tool cost, latency, branch diversity, error recovery and contradiction resolution.
+- Behavioral unit tests for the branch controller and benchmark evaluator.
+- CI checks for Python compilation, benchmark schema validation and behavioral tests.
+- Automated GitHub tag and Release publishing driven by the `VERSION` file.
+
+### Changed
+
+- `SKILL.md` now distinguishes qualitative protocol rules from unvalidated reference thresholds.
+- `README.md` now documents the measurable framework and makes clear that empirical performance improvement has not yet been demonstrated.

quantum_reasoning_skill-1.0.0/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use this software or reasoning protocol, please cite it using the metadata below."
+title: "Quantum Reasoning Skill"
+type: software
+authors:
+  - name: "Furox-Art"
+repository-code: "https://github.com/Furox-Art/quantum-reasoning-skill"
+url: "https://github.com/Furox-Art/quantum-reasoning-skill"
+license: MIT
+version: 0.3.1
+date-released: 2026-09-07
+keywords:
+  - reasoning
+  - language-models
+  - agent-systems
+  - test-time-compute
+  - benchmarking

quantum_reasoning_skill-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Contributions are welcome for the reasoning protocol, reference controller, tests, documentation, benchmark cases, host integrations and independently run model evaluations.
+
+Before changing host-facing behavior, read [`docs/COMPATIBILITY.md`](./docs/COMPATIBILITY.md). Executable behavior changes should include tests.
+
+## Community-run benchmarks
+
+The project does **not** require the maintainer to purchase access to every model or provider. Real model evaluations are intentionally community-run.
+
+The repository provides:
+
+- the benchmark protocol;
+- deterministic seed cases;
+- machine-readable JSON Schemas;
+- the result evaluator;
+- a reproducible submission validator;
+- CI validation and comparison tooling.
+
+Users may run controlled baseline-vs-skill experiments on models and providers they already have access to and submit the results for review.
+
+### Required metadata
+
+Every submitted model evaluation must identify at least:
+
+- provider;
+- exact model and model version when available;
+- run date;
+- skill version/commit when available;
+- baseline and skill prompt/instruction configuration;
+- temperature/sampling parameters;
+- context and output limits;
+- tool availability;
+- number of repetitions per case;
+- random seed when supported;
+- local hardware/runtime details for local models;
+- whether failures, refusals and timeouts were retained.
+
+Do not omit failed runs.
+
+### Required artifacts for a benchmark PR
+
+Place each submitted run under:
+
+```text
+benchmark/results/community/<provider>-<model>-<YYYY-MM-DD>/
+```
+
+Every bundle must include:
+
+```text
+metadata.json
+cases.jsonl
+baseline.jsonl
+skill.jsonl
+comparison.json
+README.md
+```
+
+The exact contracts are in [`benchmark/schemas/`](./benchmark/schemas/). `cases.jsonl` must contain the exact evaluated cases, including custom cases when used.
+
+`comparison.json` must be produced by `benchmark/evaluate.py` from the submitted raw result files rather than edited manually. Before submitting, run:
+
+```bash
+python benchmark/validate_submission.py --root benchmark/results/community
+```
+
+CI recomputes the comparison and rejects a bundle when its raw evidence and reported comparison disagree.
+
+### Result integrity
+
+- Use the same model/version, task set, tools, sampling settings and budget policy for baseline and skill conditions.
+- Do not expose or submit private chain-of-thought.
+- Do not fabricate missing telemetry.
+- Clearly disclose custom benchmark cases, prompt wrappers, provider-specific adapters and any modifications to `SKILL.md`.
+- Third-party benchmark submissions are measurements from their submitters, not project-maintainer endorsements.
+- A single positive run is not sufficient to establish a general performance claim.
+
+### How to submit
+
+You can either:
+
+1. open a **Benchmark result** issue using the repository issue template and link to your artifacts; or
+2. open a pull request containing the reproducible result bundle described above.
+
+For ordinary defects, use the **Bug report** form. For proposed behavior or protocol changes, use the **Feature request** form.
+
+For code or protocol changes, include tests when the change is executable and explain which behavior is being changed. Follow the pull-request checklist in `.github/PULL_REQUEST_TEMPLATE.md`.

quantum_reasoning_skill-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Furox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.