@monoes/monomindcli 2.15.3 → 2.15.4

package/org-skills/hypothesis-generation/references/hypothesis_quality_criteria.md

@@ -0,0 +1,203 @@
+# Human Review Criteria for Candidate Hypotheses
+
+## No automatic quality score
+
+These criteria structure expert review. Do not sum them, assign weights, calculate a “quality score,” rank candidates automatically, or select a winner. Trade-offs and domain assumptions are not commensurable numbers.
+
+For each criterion record:
+
+- evidence or rationale;
+- uncertainty and missing information;
+- source IDs;
+- reviewer role and date;
+- revision or test needed.
+
+## Question-level review
+
+### Feasibility
+
+- Are required data, samples, methods, expertise, time, and resources available?
+- Is the unit of analysis attainable without pseudoreplication?
+- Can the needed precision or information be achieved?
+- Are approvals and governance pathways realistically available?
+- Would a pilot answer feasibility rather than the scientific hypothesis?
+
+### Interest and relevance
+
+- Which scientific, stakeholder, policy, or practical decision could the answer inform?
+- Were affected groups or domain experts involved where appropriate?
+- Is the burden of the work proportionate to its expected informational value?
+
+### Novelty
+
+Treat novelty as a separate evidence claim:
+
+- What databases, indexes, registries, patents, repositories, and grey literature were searched?
+- What queries, dates, languages, and screening limits were used?
+- Was prior work examined for conceptually equivalent terminology?
+- Did a domain expert assess near neighbors and historical literature?
+
+Use “not located within the documented search boundary” when that is all the evidence supports. Absence from a quick search is not evidence of novelty.
+
+### Ethics
+
+- Are human, animal, environmental, privacy, community, biosafety, dual-use, and regulatory implications assessed?
+- Is there a less burdensome way to answer the question?
+- Are harms, benefits, fairness, consent, and stewardship addressed?
+- Are required reviews complete before work begins?
+
+FINER—Feasible, Interesting, Novel, Ethical, Relevant—is a mnemonic for refining a question, not a pass/fail instrument. The earliest source located in this refresh is the first edition of *Designing Clinical Research* (Hulley and Cummings, 1988); later editions and current methodological articles present the mnemonic. The dated search did not establish that the 1988 edition was the first printed use, so do not claim coinage without checking the primary text.
+
+## Hypothesis-level review
+
+### Clarity
+
+- Is the statement a candidate proposition rather than an observation or question?
+- Are population/system, conditions, variables, direction, and timeframe explicit?
+- Is the mechanism separate from the hypothesis statement?
+- Are undefined terms and escape clauses removed?
+
+### Testability
+
+- Are observables and measurements available?
+- Does the candidate generate at least one prospective prediction?
+- Can a feasible design bear on the prediction?
+- Are assumptions needed to connect result to candidate stated?
+
+### Falsifiability and vulnerability
+
+- What result would be incompatible under the stated assumptions?
+- Could the candidate explain every possible outcome after the fact?
+- Are indeterminate outcomes acknowledged?
+- Does the proposed test risk only “confirming” the preferred candidate?
+
+A null result can be uninformative because of low precision, failed manipulation, insensitive measurement, missingness, or assumption failure. Record these possibilities before calling a result falsifying.
+
+### Discriminability
+
+- Which rival predicts a different observable pattern?
+- Is the difference larger than expected measurement uncertainty?
+- Can the test distinguish mixed mechanisms?
+- Are positive, procedural, and negative controls informative?
+- What result supports neither candidate?
+
+### Mechanistic adequacy
+
+- Does the mechanism specify entities, activities, ordering, and context?
+- Does it respect established constraints or explicitly identify where it departs?
+- Are intermediate steps measurable?
+- Could a simpler bias or measurement explanation produce the observation?
+
+Mechanistic detail is not evidence. A more elaborate story can be less testable.
+
+### Boundary conditions and transport
+
+- Where, when, and for whom should the candidate apply?
+- What exposure/intervention versions matter?
+- What effect modifiers or contextual dependencies are plausible?
+- Which populations, species, platforms, or scales are outside scope?
+- What independent replication or external-validation test is planned?
+
+### Assumption transparency
+
+Separate:
+
+- scientific assumptions;
+- measurement assumptions;
+- design/identification assumptions;
+- statistical/model assumptions;
+- implementation assumptions.
+
+State which assumptions are testable, partially diagnosable, or fundamentally untestable with available data.
+
+### Evidence alignment
+
+For every source:
+
+- identify the exact claim it bears on;
+- distinguish direct from indirect or analogous evidence;
+- note design, population/system, and limitations;
+- include challenging and null evidence;
+- avoid venue prestige, citation count, or author reputation as a substitute for appraisal.
+
+### Uncertainty
+
+- Are direction, magnitude, and interval uncertainty separated?
+- Is model or structural uncertainty acknowledged?
+- Is measurement uncertainty propagated or discussed?
+- Are unknown alternatives and residual confounding visible?
+- Are conclusions calibrated to the evidence?
+
+## Prediction-level review
+
+A prediction should identify:
+
+- prediction ID and parent candidate;
+- conditions and boundary conditions;
+- observable and measurement ID;
+- expected pattern, direction, magnitude/range if justified, and timing;
+- rival and rival-expected pattern;
+- falsifier/incompatible result;
+- indeterminate outcome;
+- linked analysis ID;
+- assumptions and uncertainty.
+
+Do not invent numerical effect sizes merely to appear specific. If magnitude is unknown, prespecify the direction, smallest effect of scientific interest, precision target, or a range of plausible values with rationale.
+
+## Operationalization review
+
+For each construct ask:
+
+- Does the variable actually represent the construct?
+- Is the instrument validated in the target context?
+- Are reliability, calibration, detection limits, and quality control addressed?
+- Are timing and aggregation aligned with the mechanism?
+- Are cut points prespecified and justified?
+- Are missingness and measurement error mechanisms considered?
+- Is comparability across groups, time, sites, species, or devices established?
+- Could the measurement itself be affected by exposure, outcome, or selection?
+
+## Causal-claim review
+
+Require:
+
+- a well-defined intervention/exposure contrast;
+- causal estimand;
+- target population and horizon;
+- design/target-trial analogue;
+- identification assumptions;
+- confounding, selection, collider, measurement, and reverse-causation assessment;
+- positivity/overlap and interference considerations where applicable;
+- sensitivity analyses and negative controls where scientifically defensible.
+
+Predictive performance does not identify a causal effect. Adjustment does not guarantee exchangeability. Conditioning on a mediator or collider can introduce bias.
+
+## Analysis-plan review
+
+Check:
+
+- unit and dependence structure;
+- sample-size/precision rationale;
+- exclusions and stopping;
+- outcome and analysis populations;
+- transformations and model specification;
+- effect/summary measures and uncertainty;
+- missing data and intercurrent events;
+- multiplicity across hypotheses, outcomes, subgroups, models, and looks;
+- assumptions and diagnostics;
+- robustness and sensitivity analyses;
+- confirmatory/exploratory labels;
+- deviation-reporting process.
+
+## Decision record
+
+End human review with one of:
+
+- `revise_before_test`;
+- `ready_for_preregistration_review`;
+- `blocked_by_safety_or_ethics_gate`;
+- `blocked_by_measurement_or_feasibility`;
+- `retain_as_exploratory_candidate`;
+- `requires_specialist_review`.
+
+These are workflow states, not scientific truth judgments and not outputs of a score.

package/org-skills/hypothesis-generation/references/literature_search_strategies.md

@@ -0,0 +1,208 @@
+# Evidence Search and Source Traceability
+
+## Scope
+
+This workflow supports hypothesis formulation. It is not automatically a systematic review, evidence-grade, patentability search, regulatory determination, or proof of novelty.
+
+## Data and confidentiality gate
+
+Before searching:
+
+- remove confidential identifiers, unpublished results, proprietary sequences, exact vulnerabilities, and controlled operational details from queries;
+- confirm that external search is authorized;
+- translate sensitive observations into the minimum non-sensitive concepts needed;
+- use approved local or institutional search tools when policy requires;
+- record what was withheld and how that limits the search.
+
+Do not send unpublished or sensitive data to an external search engine, AI service, citation service, or model without explicit authorization.
+
+## Frame the search
+
+Separate search objectives:
+
+1. **Phenomenon:** Has the observation or a close analogue been reported?
+2. **Mechanism:** Which processes could explain it?
+3. **Rivals:** Which alternative mechanisms, artifacts, or biases are documented?
+4. **Measurement:** How have the constructs been operationalized and validated?
+5. **Design:** Which tests discriminate the candidates?
+6. **Contrary evidence:** What findings challenge each candidate?
+7. **Safety and governance:** Which ethical, biosafety, dual-use, data, or regulatory rules apply?
+8. **Priority/novelty:** What prior work, registrations, preprints, patents, and grey literature address the same claim?
+
+Use separate queries so a mechanism search is not mistaken for a novelty search.
+
+## Question structures
+
+Choose a structure matched to the question:
+
+- PICO/PICOT: population, intervention, comparator, outcome, optional time;
+- PECO: population, exposure, comparator, outcome;
+- diagnostic: population, index test, reference standard, target condition;
+- prognostic: population, prognostic factor, outcome, time;
+- qualitative: population/sample, phenomenon, context;
+- mechanistic: system, perturbation/condition, mediator/process, observable outcome;
+- computational/theoretical: model class, assumptions, parameter regime, predicted observable.
+
+Cochrane uses PICO for intervention-effect review questions and distinguishes review PICO, PICO for each synthesis, and PICO of included studies. Do not force PICO onto every domain.
+
+## Source priority
+
+Prefer the source closest to the claim:
+
+1. law, regulation, official policy, or current institutional guidance for governance claims;
+2. original paper, protocol, dataset, standard, or methods source for primary claims;
+3. current reporting guideline and explanation/elaboration for reporting expectations;
+4. systematic review or consensus report for landscape orientation;
+5. narrative review for terminology and citation mining;
+6. preprint or conference abstract, clearly labeled, for recent unreviewed work;
+7. secondary webpages only when they point to a primary source or document current implementation.
+
+Authority does not replace critical appraisal. A primary study may be weak, and a current official policy may be jurisdiction-specific.
+
+## Search sequence
+
+### 1. Broad orientation
+
+- Search the phenomenon and field terminology.
+- Locate one or more current reviews or consensus documents.
+- Extract synonyms, controlled vocabulary, candidate mechanisms, and landmark sources.
+
+### 2. Primary evidence
+
+- Search each candidate mechanism separately.
+- Search the original observation and closest analogues.
+- Search prospective, experimental, longitudinal, and replication evidence where relevant.
+- Search measurement-validation papers for each operationalization.
+
+### 3. Rival and falsification search
+
+For every candidate, run terms such as:
+
+- alternative explanation;
+- confounding;
+- selection bias;
+- collider bias;
+- reverse causation;
+- measurement error/artifact;
+- negative control;
+- failed replication;
+- null or contradictory result;
+- boundary condition/effect modification.
+
+Record whether a source challenges the mechanism, the measurement, the design, or only its generalizability.
+
+### 4. Foundational and historical search
+
+Use backward citation tracing from methods and review papers. Search original titles, authors, books, standards, and DOI/PMID records. Recency is not a proxy for relevance.
+
+### 5. Forward citation and registration search
+
+Use citation indexes, trial registries, preregistration repositories, preprint servers, data/code repositories, and correction/retraction records as appropriate.
+
+### 6. Policy search
+
+Use current official sites and record:
+
+- jurisdiction and applicability;
+- effective or revision date;
+- superseded documents;
+- local implementation requirements;
+- date checked.
+
+For high-consequence work, a search result is not legal, regulatory, ethics, biosafety, or dual-use clearance.
+
+## Search documentation
+
+Complete `assets/search_boundary_template.json`. At minimum include:
+
+- `search_boundary_id`;
+- `searched_on`;
+- purpose;
+- databases/indexes;
+- exact queries or reproducible query descriptions;
+- date/language/source-type limits;
+- inclusion and exclusion scope;
+- stop rule or last result screened;
+- known access and coverage limitations;
+- novelty status.
+
+Use `novelty_status: not_assessed` unless a qualified human has reviewed a fit-for-purpose search. Even a comprehensive search supports only a bounded statement.
+
+## Evidence ledger
+
+Complete `assets/evidence_ledger_template.csv` with one row per source:
+
+- stable source ID;
+- linked claim IDs;
+- title and author/organization;
+- publication date;
+- source type and identifier;
+- canonical HTTPS URL;
+- access date;
+- relation: supportive, challenging, contextual, method, safety, or mixed;
+- design/document type;
+- limitations and notes.
+
+The audit validates structure and links only:
+
+```bash
+python3 scripts/audit_evidence_ledger.py \
+  local-evidence-ledger.csv \
+  local-search-boundary.json \
+  --record local-hypothesis-record.json
+```
+
+It does not visit URLs, verify existence, appraise evidence, or decide whether a citation supports a claim.
+
+## Claim-to-source notes
+
+For each consequential claim, record:
+
+- the exact source location (section, table, figure, page, or quoted sentence);
+- whether the evidence is direct, indirect, analogous, or contradictory;
+- study design and target population/system;
+- magnitude and uncertainty actually reported;
+- key limitations and conflicts;
+- applicability to the candidate.
+
+Verify every identifier and claim against the source. Do not rely on search snippets or AI-generated citations.
+
+## Search stopping
+
+Use a documented stop rule, such as:
+
+- all prespecified databases searched;
+- a fixed result depth screened per query;
+- forward/backward citation tracing completed for named seed sources;
+- predefined date and language boundary reached;
+- saturation documented for terminology or mechanisms.
+
+Do not stop merely because:
+
+- preferred evidence was found;
+- new results seem repetitive;
+- a citation count is high;
+- a source appears in a prestigious venue.
+
+## Reporting bounded conclusions
+
+Use:
+
+> Searches were conducted on YYYY-MM-DD in [indexes] using [queries/strategy]. Within the documented date, language, access, and screening limits, we located [scope]. This does not establish universal absence, priority, or novelty.
+
+For gaps:
+
+> No directly matching source was located within the documented search boundary. Related work was found on [near neighbors]. A broader specialist search is required before making a novelty claim.
+
+## Common failures
+
+- Treating impact factor or citation count as study validity
+- Searching only for support
+- Using only one database
+- Ignoring terminology changes or historical work
+- Citing a review for a claim that should cite the primary study
+- Treating preprints as peer-reviewed
+- Omitting corrections, retractions, or protocol/registration records
+- Searching confidential text verbatim
+- Claiming an exhaustive search without a reproducible protocol
+- Conflating “not found” with “does not exist”

package/org-skills/hypothesis-generation/references/preregistration_and_open_science.md

@@ -0,0 +1,205 @@
+# Preregistration, Registered Reports, and Open Science
+
+## Purpose
+
+Preregistration records a time-stamped plan before the relevant data are collected or analyzed. Its main value is making planned and data-dependent work distinguishable.
+
+Preregistration does not:
+
+- guarantee a valid design or analysis;
+- prevent all researcher degrees of freedom;
+- make a hypothesis true;
+- forbid exploration or justified adaptation;
+- replace ethics, safety, data, or regulatory review;
+- require public release of restricted information.
+
+## What to preregister
+
+### Administrative
+
+- title and project ID;
+- accountable owner and roles;
+- registration date and repository;
+- study status and prior access to relevant data;
+- conflicts, funding, and sponsor roles.
+
+### Question and candidates
+
+- observation and provenance;
+- research question and claim type;
+- candidate hypotheses and mechanisms;
+- rivals and alternative explanations;
+- causal estimands where applicable;
+- boundary conditions and uncertainty.
+
+### Predictions and controls
+
+- prediction IDs and parent candidates;
+- conditions, measurements, expected patterns, and timing;
+- falsifiers and indeterminate outcomes;
+- discriminating expectations for rivals;
+- null hypotheses;
+- positive, procedural, and negative controls.
+
+### Design
+
+- population/system and sampling;
+- experimental and analysis units;
+- allocation, randomization, concealment, and masking;
+- interventions/exposures and comparators;
+- inclusion, exclusion, attrition, and stopping;
+- sample-size or precision rationale;
+- outcomes and measurement timing;
+- ethics, safety, data, and regulatory status.
+
+### Analysis
+
+- analysis populations;
+- transformations and data exclusions;
+- models, contrasts, estimators, and effect/summary measures;
+- uncertainty intervals or other inferential summaries;
+- missing-data and intercurrent-event handling;
+- multiplicity;
+- assumptions and diagnostics;
+- sensitivity and robustness analyses;
+- rules for interpreting support, challenge, and indeterminacy.
+
+### Transparency
+
+- data, code, materials, and metadata plans;
+- restrictions and controlled-access process;
+- software/environment versions;
+- AI/tool use;
+- deviation log and reporting plan.
+
+## Timing and prior access
+
+State what had already occurred:
+
+- no data collected;
+- data collected but target outcomes unseen;
+- data available but analyst blinded;
+- summary statistics viewed;
+- exploratory analysis already performed;
+- existing dataset reused.
+
+When data have already informed the plan, label the work transparently and use independent data, a held-out set, or a new replication for confirmatory testing where feasible.
+
+## Confirmatory versus exploratory
+
+### Confirmatory
+
+- planned before checking the target result;
+- tied to specified outcomes and analyses;
+- reported whether favorable, unfavorable, or null.
+
+### Exploratory
+
+- generated after or while viewing data;
+- useful for discovery;
+- labeled as data-dependent;
+- treated as a source of future predictions.
+
+Do not call exploratory work “post hoc confirmation.”
+
+## HARKing
+
+Kerr defined HARKing as presenting a post hoc hypothesis as if it were a priori. Prevent it by:
+
+- preserving dated versions;
+- separating planned and unplanned analyses;
+- reporting all prespecified outcomes and tests;
+- documenting when each candidate was generated;
+- not rewriting unexpected results as predictions;
+- seeking independent replication.
+
+## Deviations
+
+Preregistration is a plan, not a prison. For every material deviation record:
+
+- date;
+- affected section and IDs;
+- original plan;
+- change;
+- reason;
+- who made the decision;
+- whether the target result was known;
+- likely effect on bias or interpretation;
+- whether the original analysis is still reported.
+
+Do not silently replace the registration. Preserve the original and append amendments.
+
+## Registered Reports
+
+Registered Reports add journal peer review before results are known:
+
+1. Stage 1 protocol submission;
+2. review of question, methods, and analysis;
+3. in-principle acceptance under the journal’s conditions;
+4. study conduct;
+5. Stage 2 review focused on adherence, justified deviations, and interpretation.
+
+Check the current journal policy. In-principle acceptance is not ethics approval, funding, regulatory authorization, or assurance of a favorable result.
+
+## Intervention trials
+
+For randomized intervention hypotheses:
+
+- use current registration requirements for the applicable jurisdiction, funder, and venue;
+- use SPIRIT 2025 for protocol reporting;
+- align objectives, estimands, outcomes, harms, intervention details, statistical methods, and data sharing;
+- use CONSORT 2025 for completed-trial reporting;
+- report important changes, including non-prespecified outcomes or analyses.
+
+The preregistration scaffold in this skill is generic and is not a trial-registry submission, SPIRIT checklist, protocol, statistical analysis plan, or regulatory document.
+
+## Reproducibility and replicability
+
+Use the National Academies definitions:
+
+- **reproducibility:** obtaining consistent computational results with the same data, code, methods, and analysis conditions;
+- **replicability:** obtaining consistent results in a new study addressing the same question with new data.
+
+Plan for:
+
+- stable identifiers and version control;
+- code and environment capture;
+- provenance and decision logs;
+- independent replication;
+- exact and conceptual replication;
+- boundary-condition and transport tests;
+- publication of null and challenging results.
+
+Non-replication does not automatically imply misconduct or that the original study was invalid. Differences can reveal heterogeneity, measurement limitations, context, or sampling variation.
+
+## Open-science limits
+
+“Open” does not override:
+
+- participant consent and privacy;
+- Indigenous or community data governance;
+- contractual or intellectual-property restrictions;
+- export controls;
+- biosafety and dual-use review;
+- endangered-species or sensitive-location protections;
+- security-sensitive vulnerabilities.
+
+Share the maximum responsibly permitted, not the maximum technically possible. Use metadata, synthetic examples, controlled access, or redacted protocols when full release is unsafe.
+
+## Scaffold generation
+
+Generate a local draft only after the hypothesis record validates:
+
+```bash
+python3 scripts/generate_preregistration_scaffold.py \
+  local-hypothesis-record.json \
+  -o local-preregistration.md
+```
+
+The result:
+
+- is marked as an unregistered draft;
+- includes every candidate without ranking;
+- carries unresolved placeholders;
+- requires human review and repository-specific completion;
+- does not submit, register, upload, or transmit anything.

package/org-skills/hypothesis-generation/references/security_validation.md

@@ -0,0 +1,74 @@
+# Security Validation Record
+
+Validation date: **2026-07-23** (local project date).
+
+## Baseline
+
+The repository `SECURITY.md` section recorded **10 findings** with maximum severity **CRITICAL**:
+
+- cross-file environment-variable/network exfiltration;
+- a multi-file collection/transmission chain;
+- environment harvesting in both schematic scripts;
+- credential transmission and local `.env` loading;
+- subprocess delegation and full-environment propagation;
+- fabricated or unverified model identifiers;
+- unpinned external dependencies.
+
+The affected files were:
+
+- deleted: scripts/generate_schematic.py;
+- deleted: scripts/generate_schematic_ai.py;
+- the former credential and mandatory-figure instructions in `SKILL.md`.
+
+## Remediation
+
+- Deleted both external schematic scripts and all former LaTeX/figure assets.
+- Removed credential declarations, environment access, `.env` loading, subprocesses, HTTP requests, external models, image generation, mandatory figures, and cross-skill behavior.
+- Replaced the workflow with bounded deterministic local JSON/CSV/Markdown validators and a preregistration scaffold generator.
+- Added strict duplicate-key/header detection, size/row/cell/list limits, symlink and URL-path rejection, private atomic outputs, and no implicit overwrite.
+- Added AST tests rejecting network libraries, subprocesses, executable serialization, dynamic code execution, and environment credential access.
+- Added local-first confidentiality, source verification, human accountability, ethics, biosafety, dual-use, data, clinical-scope, and regulatory gates.
+- Tools report declarations and cross-links only; they do not score or select hypotheses.
+
+## Validation results
+
+- Agent Skills reference validator: **PASS**
+- Dependency-free CLI help checks: **PASS** for all 7 public CLIs
+- Synthetic standard-library tests: **27 passed**
+- Explicit AST parse with bytecode disabled: **8 scripts parsed**
+- Bytecode artifacts: **0**
+- IDE lints: **0**
+- Documented local-path link test: **PASS**
+- Authoritative-source link extraction: **36/36 reachable, 0 errors**
+- Direct behavioral security scan: **SAFE, 0 findings**
+- Pull-request gate with `--fail-on HIGH`: **PASS**
+  - CRITICAL: 0
+  - HIGH: 0
+  - LOW: 2
+
+## Residual LOW findings
+
+The LLM-assisted pull-request scan reported:
+
+1. **Missing `allowed-tools` declaration** — informational. The Agent Skills specification does not require this optional field. The compatibility declaration and body constrain bundled tools to bounded local standard-library processing with no network, models, images, credentials, or environment access.
+2. **Missing referenced files** — analyzer false positive. It invented paths under `templates/` and mismatched existing `assets/` and `references/` files. The deterministic local-path test resolved every documented bundled path and passed. No script implements network fallback or substitute retrieval.
+
+Neither LOW finding permits data transmission, credential access, scientific scoring, or automatic hypothesis selection. No CRITICAL or HIGH issue remains.
+
+## Reproduction
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
+  -s tests/hypothesis-generation -p "test_*.py" -v
+
+uv run skills-ref validate skills/hypothesis-generation
+
+uv run skill-scanner scan skills/hypothesis-generation --use-behavioral
+
+uv run python scan_pr_skills.py \
+  --fail-on HIGH \
+  --output /tmp/hypothesis-generation-pr-scan.md \
+  skills/hypothesis-generation
+```
+
+The repository-level `SECURITY.md` is intentionally not edited in this scoped refresh; its generated snapshot updates through the repository’s normal scan process.