quantum-reasoning-skill 1.0.0 → 1.1.1

package/SKILL.md

@@ -1,146 +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.
+---
+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

@@ -1 +1 @@
-0.3.1
+1.1.1

package/index.js

@@ -1 +1,207 @@
-module.exports = { name: 'quantum-reasoning-skill', version: '1.0.0', description: 'Quantum-inspired reasoning skill for exploring multiple solution paths', skill: require('./SKILL.md') }; 
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * quantum-reasoning-skill
+ *
+ * A real, executable entry point for the Node/MCP host ecosystem. It reads the
+ * skill contract that ships with this package and exposes it programmatically
+ * and from the command line.
+ *
+ * The previous implementation did `require('./SKILL.md')`, which made Node
+ * parse Markdown as JavaScript and throw a SyntaxError on every import.
+ * SKILL.md is now read as text via fs.readFileSync.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_FIELDS = ['name', 'description'];
+
+const SKILL_FILE = path.join(__dirname, 'SKILL.md');
+const VERSION_FILE = path.join(__dirname, 'VERSION');
+
+/**
+ * Parse leading `---` delimited front matter from the skill document.
+ * Deliberately dependency-free: the contract only uses `key: value` pairs.
+ *
+ * @param {string} text
+ * @returns {{fields: Record<string,string>, fenceEnd: number}}
+ */
+function parseFrontMatter(text) {
+  const lines = text.split(/\r?\n/);
+  if (lines.length === 0 || lines[0].trim() !== '---') {
+    throw new Error('SKILL.md must start with a `---` front matter fence');
+  }
+  let fenceEnd = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      fenceEnd = i;
+      break;
+    }
+  }
+  if (fenceEnd === -1) {
+    throw new Error('SKILL.md front matter is not closed');
+  }
+  const fields = Object.create(null);
+  for (const line of lines.slice(1, fenceEnd)) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+    const idx = trimmed.indexOf(':');
+    if (idx === -1) continue;
+    const key = trimmed.slice(0, idx).trim();
+    let value = trimmed.slice(idx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    fields[key] = value;
+  }
+  return { fields, fenceEnd };
+}
+
+/**
+ * Read the packaged skill contract from disk.
+ *
+ * @returns {string}
+ */
+function readSkillDocument() {
+  return fs.readFileSync(SKILL_FILE, 'utf8');
+}
+
+/**
+ * Read the packaged VERSION file.
+ *
+ * @returns {string}
+ */
+function readVersion() {
+  const raw = fs.readFileSync(VERSION_FILE, 'utf8').trim();
+  return raw.startsWith('v') ? raw.slice(1) : raw;
+}
+
+/**
+ * Validate the skill contract.
+ *
+ * @param {string} text
+ * @returns {{name: string, description: string, descriptionLength: number,
+ *            bodyLines: number, valid: boolean, problems: string[]}}
+ */
+function validateSkill(text) {
+  const { fields, fenceEnd } = parseFrontMatter(text);
+  const problems = [];
+  for (const field of REQUIRED_FIELDS) {
+    if (!fields[field]) {
+      problems.push(`front matter must define a non-empty \`${field}\``);
+    }
+  }
+  if (fields.name && fields.name !== 'quantum-reasoning') {
+    problems.push('front matter `name` must be `quantum-reasoning`');
+  }
+  const bodyLines = text.split(/\r?\n/).slice(fenceEnd + 1).length;
+  if (bodyLines < 20) {
+    problems.push(`SKILL.md body is too short (${bodyLines} lines, expected >= 20)`);
+  }
+  return {
+    name: fields.name || '',
+    description: fields.description || '',
+    descriptionLength: (fields.description || '').length,
+    bodyLines,
+    valid: problems.length === 0,
+    problems,
+  };
+}
+
+/**
+ * Load and validate the packaged skill in one call.
+ *
+ * @returns {object} the parsed skill definition
+ */
+function loadSkill() {
+  const document = readSkillDocument();
+  const { fields } = parseFrontMatter(document);
+  const report = validateSkill(document);
+  return {
+    name: report.name,
+    description: report.description,
+    version: readVersion(),
+    document,
+    valid: report.valid,
+    problems: report.problems,
+    metadata: fields,
+  };
+}
+
+const USAGE = `quantum-reasoning — inspect the packaged skill contract
+
+Usage:
+  quantum-reasoning              Print the skill summary
+  quantum-reasoning --json       Print the full report as JSON
+  quantum-reasoning --validate   Exit non-zero if the contract is invalid
+  quantum-reasoning --path       Print the absolute SKILL.md path
+  quantum-reasoning --help       Show this message
+
+Exit codes:
+  0  success
+  1  invalid skill contract (--validate)
+  2  SKILL.md could not be read
+`;
+
+function main(argv) {
+  const args = argv.slice(2);
+  const wantsJson = args.includes('--json');
+  const wantsValidate = args.includes('--validate');
+  const wantsPath = args.includes('--path');
+
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  let report;
+  try {
+    report = validateSkill(readSkillDocument());
+  } catch (error) {
+    process.stderr.write(`error: ${error.message}\n`);
+    return 2;
+  }
+  report.version = readVersion();
+  report.path = SKILL_FILE;
+
+  if (wantsPath) {
+    process.stdout.write(`${SKILL_FILE}\n`);
+    return 0;
+  }
+  if (wantsJson) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(`skill:   ${report.name || '<missing name>'}\n`);
+    process.stdout.write(`status:  ${report.valid ? 'valid' : 'INVALID'}\n`);
+    process.stdout.write(`file:    ${SKILL_FILE}\n`);
+    process.stdout.write(`version: ${report.version}\n`);
+    process.stdout.write(`body:    ${report.bodyLines} lines\n`);
+    for (const problem of report.problems) {
+      process.stdout.write(`  - ${problem}\n`);
+    }
+  }
+  if (wantsValidate && !report.valid) {
+    return 1;
+  }
+  return 0;
+}
+
+module.exports = {
+  name: 'quantum-reasoning-skill',
+  version: readVersion(),
+  skillFile: SKILL_FILE,
+  parseFrontMatter,
+  readSkillDocument,
+  readVersion,
+  validateSkill,
+  loadSkill,
+};
+
+if (require.main === module) {
+  process.exitCode = main(process.argv);
+}

package/package.json

@@ -1 +1,41 @@
-{"name":"quantum-reasoning-skill","version":"1.0.0","description":"Quantum-inspired reasoning skill for exploring multiple solution paths","main":"index.js","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"keywords":["ai-agents","reasoning","quantum-inspired","multi-branch"],"author":"Furox-Art","license":"MIT","repository":{"type":"git","url":"git+https://github.com/Furox-Art/quantum-reasoning-skill.git"},"bugs":{"url":"https://github.com/Furox-Art/quantum-reasoning-skill/issues"},"homepage":"https://github.com/Furox-Art/quantum-reasoning-skill#readme"} 
+{
+  "name": "quantum-reasoning-skill",
+  "version": "1.1.1",
+  "description": "Quantum-inspired reasoning skill for exploring multiple solution paths",
+  "main": "index.js",
+  "bin": {
+    "quantum-reasoning": "index.js"
+  },
+  "files": [
+    "index.js",
+    "SKILL.md",
+    "VERSION",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node index.js --validate && node -e \"const s=require('./index.js'); if(!s.loadSkill().valid){console.error('skill contract invalid');process.exit(1)}\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai-agents",
+    "reasoning",
+    "quantum-inspired",
+    "multi-branch",
+    "agent-skills",
+    "mcp",
+    "claude-skill"
+  ],
+  "author": "Furox-Art",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Furox-Art/quantum-reasoning-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Furox-Art/quantum-reasoning-skill/issues"
+  },
+  "homepage": "https://github.com/Furox-Art/quantum-reasoning-skill#readme"
+}

package/.github/ISSUE_TEMPLATE/benchmark-result.yml

@@ -1,81 +0,0 @@
-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

package/.github/ISSUE_TEMPLATE/bug-report.yml

@@ -1,38 +0,0 @@
-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