@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/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/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/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.

package/skills/hypothesis-generation/references/source_ledger.md

@@ -0,0 +1,116 @@
+# Dated Source Ledger
+
+Verification and research cutoff: **2026-07-23**.
+
+Machine-readable ledger: `assets/source_ledger.csv`.
+
+## Search boundary
+
+Research used `parallel-cli` search against official or primary domains with focused queries for:
+
+- NIH rigor, reproducibility, and the 2026 replication initiative;
+- Cochrane PICO and the original well-built clinical-question article;
+- FINER’s attributed historical source and current interpretation;
+- Platt’s original strong-inference essay;
+- COS/OSF preregistration and Registered Reports;
+- SPIRIT 2025 and CONSORT 2025;
+- causal questions, counterfactuals, estimands, and bias;
+- negative controls, HARKing, multiplicity, reproducibility, and replication;
+- NIST/UNESCO responsible AI and primary evidence on output homogenization;
+- human, animal, biosafety, biosecurity, dual-use, data, and regulatory gates.
+
+Searches prioritized official domains and primary publications. Full-text extraction or search excerpts were used to verify titles, dates, versions, and relevant passages. This was a targeted skill refresh, not a systematic review, patent search, or proof of scientific novelty.
+
+## Core methodology sources
+
+### Question formulation
+
+- `SRC-COCHRANE-PICO` — current Cochrane Handbook Chapter 2. PICO is used for intervention-effect review questions, with objectives defined in advance and stakeholder input where appropriate.
+- `SRC-PICO-ORIGINAL` — Richardson et al., 1995, *The well-built clinical question*. Foundational four-part clinical-question article.
+- `SRC-FINER-1988` — Hulley and Cummings, *Designing Clinical Research*, first edition metadata (1988). It is the earliest FINER-attributed source located in this refresh.
+- `SRC-FINER-CURRENT` — Werner and Willis, 2023, current FINER interpretation.
+
+**Historical limitation:** the available targeted search confirmed the 1988 book’s bibliographic metadata and later attribution but did not establish the exact first printed use or coinage of the FINER mnemonic. The skill therefore does not claim that provenance as proven.
+
+### Multiple hypotheses and falsification
+
+- `SRC-PLATT-1964` — John R. Platt, “Strong Inference,” *Science* 146:347–353, DOI `10.1126/science.146.3642.347`.
+- `SRC-NEG-CONTROL` — Lipsitch, Tchetgen Tchetgen, and Cohen, 2010, negative controls for confounding and bias, DOI `10.1097/EDE.0b013e3181d61eeb`.
+- `SRC-HARKING` — Kerr, 1998, HARKing, DOI `10.1207/s15327957pspr0203_4`.
+- `SRC-ASA-PVALUE` — ASA statement: thresholds alone do not support scientific conclusions; p-values do not measure hypothesis truth or effect importance; full reporting is required.
+
+### Rigor, reproducibility, and replication
+
+- `SRC-NIH-RIGOR` — NIH guidance on scientific premise, rigorous design, relevant biological variables, authentication, and transparency.
+- `SRC-NIH-REPLICATION` — NIH’s agency-wide replication and reproducibility initiative, page reviewed June 22, 2026.
+- `SRC-NASEM-RR` — National Academies 2019 consensus report defining computational reproducibility and replicability with new data.
+- `SRC-TOP` — Transparency and Openness Promotion guidelines.
+- `SRC-NIH-DMS` — NIH Data Management and Sharing Policy.
+
+Open practices remain subject to consent, privacy, community governance, intellectual property, export control, and security restrictions.
+
+## Preregistration and intervention trials
+
+- `SRC-COS-PREREG` — preregistration separates planned from unplanned work; transparent exploration remains valuable.
+- `SRC-OSF-REG` — current OSF registration/preregistration implementation guidance.
+- `SRC-COS-RR` — Registered Reports and results-blind protocol review.
+- `SRC-SPIRIT-2025` — current 34-item randomized-trial protocol guideline; supersedes SPIRIT 2013.
+- `SRC-CONSORT-2025` — current 30-item randomized-trial result-reporting guideline, including open science, harms, outcomes, intervention details, and important changes.
+
+SPIRIT and CONSORT are reporting guidelines, not design-quality, ethics, regulatory, or efficacy certifications.
+
+## Causal inference and estimands
+
+- `SRC-WHATIF` — Hernán and Robins, *Causal Inference: What If*. The author page linked the latest revision found during verification.
+- `SRC-ICH-E9R1` — ICH E9(R1), defining the estimand as the precise treatment-effect target and aligning planning, design, analysis, sensitivity analysis, and interpretation.
+
+These sources ground the distinctions among target causal contrast, estimator, and estimate, and the explicit treatment of confounding, selection, collider, measurement, and intervention-definition assumptions.
+
+## Responsible AI
+
+- `SRC-NIST-GENAI` — NIST AI 600-1, covering confabulation, privacy, harmful bias/homogenization, information integrity, dangerous recommendations, and human–AI configuration.
+- `SRC-UNESCO-AI` — human rights, privacy, accountability, transparency, diversity, and human oversight.
+- `SRC-DOSHI-HAUSER` — Doshi and Hauser, 2024, DOI `10.1126/sciadv.adn5290`. In the studied story-writing task, AI-assisted outputs were more similar to one another while some individual creativity measures improved.
+
+The primary homogenization result is task-specific. The skill treats idea homogenization as a plausible risk, not a universal measured effect across scientific domains.
+
+## Ethics and oversight
+
+### Humans
+
+- `SRC-HHS-COMMON-RULE` — U.S. Common Rule/45 CFR 46 portal.
+- `SRC-BELMONT` — respect for persons, beneficence, and justice.
+- `SRC-HELSINKI` — World Medical Association Declaration of Helsinki, revised October 2024.
+
+An authorized IRB/REC or equivalent must determine applicability; the skill does not self-declare exemption.
+
+### Animals
+
+- `SRC-OLAW-PHS` — PHS Policy and IACUC/Assurance requirements for covered work.
+- `SRC-ARRIVE` — ARRIVE 2.0 reporting guidance.
+
+### Biosafety and dual use
+
+- `SRC-NIH-RSNA` — NIH Guidelines for research involving recombinant or synthetic nucleic acid molecules.
+- `SRC-NIH-BIOSEC` — current NIH biosafety/biosecurity portal.
+- `SRC-BMBL` — CDC/NIH BMBL sixth edition.
+- `SRC-WHO-LIFE` — WHO Global Guidance Framework for the Responsible Use of the Life Sciences.
+
+### U.S. dual-use transition status
+
+At the verification date:
+
+- `SRC-EO-14292` directed revision/replacement of the 2024 DURC/PEPP policy and pause/termination actions for covered dangerous gain-of-function research.
+- `SRC-NIH-NOT-25-112` stated the Executive Order superseded NIH’s 2024 implementation and rescinded NOT-OD-25-061.
+- `SRC-ASPR-DURC` still described the 2024 policy as awaiting revision or replacement and promised an update when the revised policy became available.
+
+This status is time-sensitive. Recheck current federal, funder, award, institutional, and jurisdiction-specific rules before any related work. Do not use this ledger as clearance.
+
+## Source-use rules
+
+1. Verify each citation and identifier against the live primary source before publication or registration.
+2. Recheck time-sensitive policy after the cutoff date.
+3. Link every scientific claim to evidence in `assets/evidence_ledger_template.csv`.
+4. Include challenging, null, and limitation evidence, not only support.
+5. Do not infer novelty from this source ledger; it documents the skill refresh, not a user’s research topic.
+6. Do not expose a sensitive research question in an external search query without authorization.