@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/scientific-visualization/scripts/style_preview.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Generate a deterministic preview for a bundled scientific figure style."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import sys
+from typing import Any
+
+from _common import CliError, emit_json, positive_float
+
+
+def build_preview(style_name: str, palette_name: str) -> tuple[Any, dict[str, Any]]:
+    """Create a deterministic multi-panel preview and palette audit."""
+    try:
+        import matplotlib as mpl
+        import matplotlib.pyplot as plt
+    except ImportError as exc:
+        raise CliError(
+            "Matplotlib is required for previews; "
+            "run with --with 'matplotlib==3.11.1'"
+        ) from exc
+    from palette_audit import audit_palette
+    from style_presets import available_palettes, style_context
+
+    palettes = available_palettes()
+    if palette_name not in palettes:
+        raise CliError(
+            f"unknown palette {palette_name!r}; "
+            f"available: {', '.join(sorted(palettes))}"
+        )
+    colors = palettes[palette_name]
+    if len(colors) < 3:
+        raise CliError("preview palette must contain at least three colors")
+    audit = audit_palette(
+        colors,
+        background="#FFFFFF",
+        role="graphical",
+        name=palette_name,
+    )
+
+    with style_context(style_name, palette_name=palette_name):
+        fig, axes = plt.subplots(
+            2,
+            2,
+            figsize=(7.0, 5.2),
+            layout="constrained",
+        )
+        x_values = [index / 10.0 for index in range(41)]
+        line_styles = ["-", "--", "-.", ":"]
+        markers = ["o", "s", "^", "D"]
+        for index in range(4):
+            values = [
+                math.sin(value + index * 0.45) + index * 0.35
+                for value in x_values
+            ]
+            axes[0, 0].plot(
+                x_values,
+                values,
+                color=colors[index % len(colors)],
+                linestyle=line_styles[index],
+                marker=markers[index],
+                markevery=8,
+                label=f"Series {index + 1}",
+            )
+        axes[0, 0].axhline(0, color="0.35", linewidth=0.7)
+        axes[0, 0].set(
+            xlabel="Time (hours)",
+            ylabel="Response (a.u.)",
+            title="Color plus redundant encoding",
+        )
+        axes[0, 0].legend(ncols=2)
+
+        categories = ["Control", "Low", "High"]
+        values = [0.0, 1.4, -0.8]
+        hatches = ["", "///", "xx"]
+        bars = axes[0, 1].bar(
+            categories,
+            values,
+            color=[colors[index % len(colors)] for index in range(3)],
+            edgecolor="black",
+            linewidth=0.7,
+        )
+        for bar, hatch in zip(bars, hatches):
+            bar.set_hatch(hatch)
+        axes[0, 1].axhline(0, color="black", linewidth=0.7)
+        axes[0, 1].set(
+            ylabel="Change from baseline (unit)",
+            title="Signed bars with visible zero",
+        )
+
+        matrix = [
+            [-2.0, -1.2, -0.4, 0.2, 1.0],
+            [-1.5, -0.8, float("nan"), 0.8, 1.7],
+            [-1.0, -0.2, 0.0, 1.1, 2.0],
+        ]
+        colormap = mpl.colormaps["RdBu_r"].with_extremes(bad="#777777")
+        image = axes[1, 0].imshow(
+            matrix,
+            cmap=colormap,
+            norm=mpl.colors.TwoSlopeNorm(vmin=-2, vcenter=0, vmax=2),
+            aspect="auto",
+            interpolation="nearest",
+        )
+        axes[1, 0].set(
+            xlabel="Sample",
+            ylabel="Feature",
+            title="Centered normalization; gray = missing",
+        )
+        colorbar = fig.colorbar(image, ax=axes[1, 0])
+        colorbar.set_label("Effect (unit)")
+
+        groups = [
+            [1.0, 1.2, 0.9, 1.1, 1.4, 0.8],
+            [1.4, 1.8, 1.6, 1.5, 2.0, 1.7],
+            [0.7, 0.9, 1.0, 0.6, 0.8, 1.1],
+        ]
+        for index, group in enumerate(groups):
+            offsets = [-0.08, -0.05, -0.02, 0.02, 0.05, 0.08]
+            axes[1, 1].scatter(
+                [index + offset for offset in offsets],
+                group,
+                color=colors[index % len(colors)],
+                edgecolor="black",
+                linewidth=0.4,
+                marker=markers[index],
+                zorder=2,
+            )
+            ordered = sorted(group)
+            median = (ordered[2] + ordered[3]) / 2
+            axes[1, 1].plot(
+                [index - 0.15, index + 0.15],
+                [median, median],
+                color="black",
+                linewidth=1.2,
+            )
+        axes[1, 1].set(
+            xticks=range(3),
+            xticklabels=categories,
+            ylabel="Observed value (unit)",
+            title="Raw observations with median",
+        )
+
+        for label, ax in zip("ABCD", axes.flat):
+            ax.text(
+                -0.12,
+                1.06,
+                label,
+                transform=ax.transAxes,
+                fontweight="bold",
+                va="top",
+            )
+        fig.suptitle(f"Style preview: {style_name} / {palette_name}")
+    return fig, audit
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Render a deterministic accessible-style preview with line, bar, "
+            "heatmap, missing-data, and raw-observation examples."
+        )
+    )
+    parser.add_argument("--output", required=True, help="output base path")
+    parser.add_argument(
+        "--style",
+        choices=("default", "nature", "science", "cell", "minimal", "presentation"),
+        default="default",
+    )
+    parser.add_argument("--palette", default="okabe_ito_on_white")
+    parser.add_argument(
+        "--formats", default="png,svg", help="comma-separated formats"
+    )
+    parser.add_argument("--dpi", type=positive_float, default=300.0)
+    parser.add_argument("--manifest", action="store_true")
+    parser.add_argument("--force", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+        from figure_export import export_figure
+
+        fig, audit = build_preview(args.style, args.palette)
+        try:
+            report = export_figure(
+                fig,
+                args.output,
+                formats=args.formats.split(","),
+                dpi=args.dpi,
+                overwrite=args.force,
+                provenance={
+                    "purpose": "deterministic bundled-style preview",
+                    "style": args.style,
+                    "palette": args.palette,
+                    "data": "synthetic values defined in style_preview.py",
+                    "transformations": [
+                        "analytical sine offsets",
+                        "explicit TwoSlopeNorm(-2, 0, 2)",
+                        "median of displayed raw observations",
+                    ],
+                    "palette_screen": {
+                        "background_review_count": audit["contrast_screen"][
+                            "review_count"
+                        ],
+                        "grayscale_review_count": audit["grayscale_screen"][
+                            "review_count"
+                        ],
+                    },
+                },
+                write_manifest=args.manifest,
+            )
+        finally:
+            import matplotlib.pyplot as plt
+
+            plt.close(fig)
+        report["palette_audit"] = {
+            "contrast_screen": audit["contrast_screen"],
+            "grayscale_screen": audit["grayscale_screen"],
+            "notice": audit["notice"],
+        }
+        emit_json(report)
+        return 0
+    except CliError as exc:
+        parser.exit(2, f"error: {exc}\n")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/scientific-writing/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: scientific-writing
+description: Draft, revise, and audit scientific manuscripts or reports with explicit evidence provenance, reporting-guideline coverage, authorship accountability, confidentiality controls, and local consistency checks. Use for manuscript sections, references, declarations, tables, figures, or submission preparation when scientific accuracy and traceability matter.
+license: MIT
+compatibility: Requires Python 3.11+ only for optional dependency-free local CLIs; core guidance is platform-neutral. Bundled tools are offline and require no API keys.
+metadata:
+  version: "2.0"
+  skill-author: K-Dense Inc.
+---
+
+# Scientific Writing
+
+## Purpose
+
+Produce clear scientific prose without inventing evidence or concealing uncertainty.
+Keep drafting, evidence verification, and submission approval as separate stages.
+
+The accountable human authors control scientific decisions and final approval. AI is
+not an author, and generated fluency is never evidence [SW-S01, SW-S03].
+
+## Non-negotiable safety rules
+
+### Confidentiality
+
+Do not send unpublished manuscripts, peer-review or editorial material, sensitive or
+restricted data, PHI or other personal data, proprietary content, or source documents
+to an external service without:
+
+1. explicit authorization from a person or body empowered to grant it; and
+2. a documented review of journal, institutional, funder, consent, ethics, contractual,
+   legal, and data-use policy.
+
+When authorization or policy is unclear, keep processing local and use only the minimum
+metadata needed. De-identification requires expert review; removing obvious names is
+not sufficient. See `references/authorship_ai_confidentiality.md`.
+
+### No fabrication
+
+Never invent or complete:
+
+- citations, references, DOI, PMID, PMCID, ISBN, URLs, or quotations;
+- results, data values, denominators, sample sizes, units, effect estimates,
+  uncertainty, statistical tests, or significance claims;
+- methods, materials, protocol details, software versions, analysis choices, or
+  deviations;
+- registrations, approvals, consent, ethics statements, participant details, or dates;
+- authors, author order, CRediT roles, acknowledgments, or permissions;
+- funding, sponsor roles, conflicts, data or code availability, or AI disclosures.
+
+Use an explicit missing, unverified, or not-applicable state. Do not substitute plausible
+boilerplate.
+
+### Evidence binding
+
+Every factual or numeric manuscript claim must map to verified evidence IDs. A human
+verifier must open the source, confirm the proposition and locator, verify bibliographic
+metadata, and record who verified it and when.
+
+Search snippets, generated summaries, memory, and another work's bibliography may aid
+discovery but do not verify a claim. See `references/evidence_workflow.md`.
+
+### Scientific fidelity
+
+- Preserve uncertainty and alternative explanations.
+- Distinguish confirmatory, exploratory, descriptive, and post hoc work.
+- Keep methods and results consistent.
+- Reconcile units, denominators, sample sizes, populations, time points, and labels.
+- Report negative, null, adverse, unexpected, failed, and inconclusive findings when
+  they belong to the study record.
+- State concrete limitations and bound generalizability.
+- Do not convert association into causation or non-significance into equivalence.
+
+## Intake
+
+Before drafting, obtain or mark unresolved:
+
+- document type, study design, stage, audience, and target venue;
+- current author instructions and policy access date;
+- protocol, registration, analysis plan, amendments, and reporting guideline;
+- manuscript or section scope;
+- verified source manifest and claim registry;
+- methods, results, tables, figures, and supplements;
+- authorship, CRediT, declarations, and approval records;
+- confidentiality classification and authorized processing boundary;
+- data, code, materials, and repository constraints.
+
+Do not ask for restricted source material if metadata or a local user-run audit is
+sufficient.
+
+## Workflow
+
+### 1. Establish the local workspace
+
+For a new draft, optionally generate fail-closed Markdown, JSON, and CSV scaffolds:
+
+```bash
+python3 scripts/scaffold_manuscript.py \
+  --output-dir ./draft-workspace \
+  --document-id local-draft \
+  --study-design randomized_trial \
+  --guideline consort-2025
+```
+
+The generator never overwrites files. Its output is explicitly not submission-ready and
+contains placeholders that the linter rejects.
+
+### 2. Select reporting guidance
+
+Choose by actual design and article type, then open the current official statement,
+checklist, explanation document, extensions, and target-journal instructions.
+
+```bash
+python3 scripts/select_reporting_guidelines.py select \
+  --study-design randomized_trial
+```
+
+Current major routes researched on 2026-07-24 include CONSORT 2025, SPIRIT 2025,
+PRISMA 2020, STROBE, STARD and STARD-AI, TRIPOD+AI, CARE, ARRIVE 2.0, SQUIRE 2.0,
+and CHEERS 2022 [SW-S06–SW-S18].
+
+The selector is non-scoring. It does not certify quality, compliance, completeness, or
+acceptance. See `references/reporting_guidelines.md`.
+
+### 3. Build the evidence record
+
+Assign:
+
+- `E` IDs to sources in `source_manifest.json`;
+- `C` IDs to claims in `claims.csv`;
+- `N`, `M`, `O`, and `R` IDs to numeric facts, methods, outcomes, and results in
+  `consistency_manifest.json`.
+
+Store a hash of claim text in CSV rather than raw claim text. During drafting, append:
+
+```text
+[claim:C001] [evidence:E001,E002]
+```
+
+Do not mark a source verified until an accountable human has opened it and confirmed
+the exact support.
+
+### 4. Create an evidence outline
+
+Outline only from recorded evidence:
+
+- objective or question;
+- section purpose;
+- claim IDs and evidence IDs;
+- methods and result IDs;
+- analysis intent and uncertainty;
+- unresolved conflicts or missing information;
+- applicable reporting topics.
+
+Keep unsupported content in an unresolved-issues list, not manuscript prose.
+
+### 5. Draft without adding facts
+
+Transform the verified outline into venue-appropriate prose. Preserve all IDs during
+drafting.
+
+- Match title and abstract to the completed main text.
+- Describe methods as performed.
+- Present results in the declared order and analysis population.
+- Separate result from interpretation unless the venue combines them.
+- Compare with prior evidence only after verifying it.
+- Keep conclusions within the observed design, population, and uncertainty.
+
+Use IMRAD only when appropriate. Structured abstracts, lists, combined sections, and
+alternative structures depend on study design and venue. See
+`references/imrad_structure.md` and `references/writing_principles.md`.
+
+### 6. Reconcile methods and results
+
+Record repeated numeric facts and method-result mappings, then run:
+
+```bash
+python3 scripts/check_consistency.py consistency_manifest.json
+```
+
+Resolve every mismatch manually. A changed value may be a legitimate analysis-set
+difference, but that difference must be named rather than silently normalized.
+
+### 7. Verify citations and claims
+
+```bash
+python3 scripts/validate_manifest.py source_manifest.json \
+  --kind source --require-verified
+python3 scripts/audit_claims.py manuscript.md claims.csv source_manifest.json
+python3 scripts/check_references.py source_manifest.json
+```
+
+The reference checker validates syntax and duplicate identifiers without network
+resolution. A human must still compare every identifier and quotation with the opened
+source. Follow NLM *Citing Medicine* or the current official style required by the
+venue [SW-S20, SW-S21].
+
+### 8. Validate authorship and disclosure
+
+Use journal criteria for authorship. Record the standardized CRediT roles as
+contribution metadata; CRediT does not itself define authorship [SW-S19].
+
+If AI was used, humans must verify all affected content and disclose the tool and
+purpose according to current journal and publisher policy. ICMJE's January 2026
+Recommendations require transparency and retain human accountability [SW-S01, SW-S02].
+
+```bash
+python3 scripts/validate_authorship.py authorship.json
+```
+
+Do not generate a disclosure from assumptions. See
+`references/authorship_ai_confidentiality.md`.
+
+### 9. Review declarations and open-science statements
+
+Verify each statement independently:
+
+- ethics and consent;
+- registration and protocol;
+- funding and sponsor role;
+- conflicts and relationships;
+- author contributions and acknowledgments;
+- data, code, materials, and protocol availability;
+- AI use.
+
+Be as open as rights and responsibilities permit, but do not expose confidential,
+personal, proprietary, licensed, or protected information. Record actual access
+conditions. See `references/research_integrity_open_science.md`.
+
+### 10. Use figures and tables only when warranted
+
+Figures and tables are optional and provenance-bound. This skill does not generate
+images or schematics.
+
+For every retained display:
+
+- link source data, code, transformations, and evidence IDs;
+- reconcile values with prose and registries;
+- document image processing, permissions, and licenses;
+- include units, denominators, sample sizes, uncertainty, and analysis population;
+- provide alt text and redundant non-color cues;
+- perform a manual accessibility and scientific check at final size.
+
+See `references/figures_tables.md`.
+
+### 11. Record non-scoring guideline coverage
+
+Record each bundled high-level topic as addressed, not applicable with rationale, or
+missing:
+
+```bash
+python3 scripts/select_reporting_guidelines.py check reporting_coverage.json
+```
+
+Then complete the official checklist using actual manuscript locations. Never claim
+adherence merely because the local coverage file passes.
+
+### 12. Lint and approve
+
+```bash
+python3 scripts/validate_manifest.py manuscript_manifest.json --kind manuscript
+python3 scripts/lint_manuscript.py manuscript.md \
+  --manifest manuscript_manifest.json
+```
+
+The linter reports issue codes and line numbers without echoing manuscript text.
+Sensitive-content warnings require manual review and are not a de-identification
+certificate.
+
+Only accountable humans may:
+
+- resolve scientific ambiguities;
+- approve author order and declarations;
+- approve external disclosure or transfer;
+- set `submission_ready` to true;
+- remove the draft banner;
+- authorize submission.
+
+## Revision and peer review
+
+Treat reviewer material as confidential. Do not upload it to an external service without
+the required authorization and policy review [SW-S01, SW-S24].
+
+For each requested change:
+
+1. record the comment without exposing it outside the approved boundary;
+2. classify it as editorial, scientific, statistical, policy, or unresolved;
+3. identify affected claims, evidence, methods, results, and displays;
+4. revise the registries before prose when facts change;
+5. re-run every affected audit;
+6. draft a response that states what changed and where;
+7. obtain human approval.
+
+Do not comply with a request that would fabricate, hide, overstate, or breach policy.
+
+## Current policy caution
+
+COPE's 2017 Core Practices were retired in 2024. As of 2026-07-24, COPE announced that
+a replacement Code of Conduct would be published in 2026; do not describe the archived
+Core Practices as current membership standards [SW-S04, SW-S05]. Distinguish formal
+COPE positions from discussion documents, webinars, comments, and case advice.
+
+## Formatting and submission
+
+The former LaTeX assets were removed because a generic polished template could allow
+plausible placeholders to ship. Use the Markdown scaffold and structured records.
+Apply the target venue's current controlled template only after verification.
+
+See:
+
+- `assets/REPORT_FORMATTING_GUIDE.md`
+- `references/professional_report_formatting.md`
+- `references/journal_policies.md`
+
+Formatting cannot convert an incomplete evidence record into a submission-ready paper.
+
+## Bundled files
+
+### Assets
+
+- `assets/manuscript_scaffold.md`
+- `assets/manuscript_manifest_template.json`
+- `assets/source_manifest_template.json`
+- `assets/claim_evidence_template.csv`
+- `assets/consistency_manifest_template.json`
+- `assets/authorship_template.json`
+- `assets/reporting_coverage_template.json`
+- `assets/reporting_guidelines.json`
+
+### Scripts
+
+- `scripts/scaffold_manuscript.py`
+- `scripts/validate_manifest.py`
+- `scripts/select_reporting_guidelines.py`
+- `scripts/audit_claims.py`
+- `scripts/check_consistency.py`
+- `scripts/check_references.py`
+- `scripts/validate_authorship.py`
+- `scripts/lint_manuscript.py`
+
+All scripts are local, deterministic, bounded, dependency-free, and network-free. See
+`references/cli_reference.md`.
+
+### References
+
+- `references/evidence_workflow.md`
+- `references/writing_principles.md`
+- `references/imrad_structure.md`
+- `references/citation_styles.md`
+- `references/reporting_guidelines.md`
+- `references/figures_tables.md`
+- `references/authorship_ai_confidentiality.md`
+- `references/research_integrity_open_science.md`
+- `references/journal_policies.md`
+- `references/professional_report_formatting.md`
+- `references/cli_reference.md`
+- `references/source_ledger.md`

package/skills/scientific-writing/assets/REPORT_FORMATTING_GUIDE.md

@@ -0,0 +1,60 @@
+# Fail-Closed Report Formatting Guide
+
+This asset replaces the former LaTeX package and example report. The former template
+contained plausible-looking placeholder findings that could compile into a polished but
+unverified document. Use the Markdown scaffold and structured registries instead.
+
+## Safe default
+
+1. Generate a workspace with `scripts/scaffold_manuscript.py`.
+2. Keep the `DRAFT — NOT FOR SUBMISSION` banner while any placeholder or verification
+   gate remains.
+3. Draft in plain Markdown. Apply publisher formatting only after content verification.
+4. Treat the target journal's current author instructions and supplied template as
+   controlling.
+5. Re-run every local audit after formatting because conversion can change citations,
+   symbols, tables, and references.
+
+## Hierarchy
+
+- Use one document title and a predictable heading hierarchy.
+- Do not encode scientific meaning only with typography or color.
+- Keep terminology, abbreviations, units, and statistical notation consistent.
+- Preserve machine-readable identifiers and evidence markers until final rendering.
+- Never replace a missing value with an aesthetically plausible value.
+
+## Tables
+
+- Every cell must derive from a named evidence record.
+- Include units, analysis population, numerator and denominator where relevant.
+- Distinguish missing, not measured, not applicable, and zero.
+- Keep exact values consistent with prose and the numeric registry.
+- Use editable tables unless the venue explicitly requires another format.
+
+## Figures
+
+Figures are optional. This skill does not generate images. A retained figure must have:
+
+- a provenance record linking it to data, code, or a licensed source;
+- a caption that identifies the analysis population, units, uncertainty, and panels;
+- alt text that communicates the figure's purpose and principal pattern without adding
+  unsupported interpretation;
+- labels or patterns in addition to color;
+- a manual check at the final display size;
+- documented permissions and transformations for reused or adapted material.
+
+Never invent a figure, image, diagram, graphical abstract, or missing visual result.
+
+## Conversion gate
+
+Before producing a submission format, confirm:
+
+- placeholders are absent;
+- factual and numeric claims map to verified evidence IDs;
+- citations and reference identifiers pass local checks;
+- methods, results, units, denominators, and sample sizes agree;
+- authorship, CRediT roles, declarations, and AI use are human-approved;
+- confidentiality and target-journal policy reviews are complete;
+- reporting-guideline coverage was reviewed without treating it as a quality score.
+
+Formatting quality cannot make incomplete evidence submission-ready.

package/skills/scientific-writing/assets/authorship_template.json

@@ -0,0 +1,56 @@
+{
+  "accountability": {
+    "all_authors_approved": false,
+    "guarantor_author_ids": []
+  },
+  "ai_use": {
+    "disclosed_in": [],
+    "human_verification_complete": false,
+    "journal_policy_checked": false,
+    "tools": [],
+    "used": false
+  },
+  "authors": [
+    {
+      "author_id": "A001",
+      "authorship_criteria": {
+        "accountable_for_work": false,
+        "drafted_or_critically_revised": false,
+        "final_approval": false,
+        "substantial_contribution": false
+      },
+      "credit_roles": [],
+      "is_human": true,
+      "name": "[[TODO:human-author-name]]"
+    }
+  ],
+  "contributors": [],
+  "corresponding_author_id": "",
+  "declarations": {
+    "ai_use": {
+      "content_sha256": "",
+      "status": "missing",
+      "verified_by": "",
+      "verified_on": ""
+    },
+    "author_contributions": {
+      "content_sha256": "",
+      "status": "missing",
+      "verified_by": "",
+      "verified_on": ""
+    },
+    "conflicts": {
+      "content_sha256": "",
+      "status": "missing",
+      "verified_by": "",
+      "verified_on": ""
+    },
+    "funding": {
+      "content_sha256": "",
+      "status": "missing",
+      "verified_by": "",
+      "verified_on": ""
+    }
+  },
+  "schema_version": "1.0"
+}