@paradigma-inc/flywheel 0.1.95 → 0.1.102

package/README.md

@@ -362,14 +362,32 @@ npx --yes @paradigma-inc/flywheel setup --mode cli --antigravity --project
 
 ## Public Update Flow
 
-After a new release:
+Flywheel checks for newer public CLI releases during normal command use and
+prints stale-version advisories to stderr only. To update the managed local
+package and refresh detected local MCP host and bundled-skill setup artifacts,
+run:
 
 ```bash
-npx --yes @paradigma-inc/flywheel@latest setup --mode mcp --install-skill
+flywheel update --yes
 ```
 
-Reruns are idempotent and should be used as the primary recovery path for setup
-and update issues.
+Check status without changing files:
+
+```bash
+flywheel update --check
+```
+
+Preview package and local setup refresh steps without changing files:
+
+```bash
+flywheel update --dry-run
+```
+
+If no local Flywheel setup artifacts are detected, rerun the public installer:
+
+```bash
+curl -fsSL https://flywheel.paradigma.inc/install | sh
+```
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.95",
+  "version": "0.1.102",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [
@@ -25,6 +25,7 @@
     "open": "^10.2.0",
     "ora": "^9.0.0",
     "picocolors": "^1.1.1",
+    "semver": "^7.8.0",
     "skills": "1.4.7",
     "string-width": "^8.2.0",
     "wrap-ansi": "^10.0.0"

package/skills/flywheel-llm-proof-paper/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: flywheel-llm-proof-paper
+description: Sanity-check LaTeX and BibTeX papers for fake or mismatched references and optional Slop Guard prose lint signals before submission.
+---
+
+# LLM-Proof Paper
+
+## When To Use
+
+Use this skill when the user wants to sanity-check, LLM-proof, submission-check, or preflight an academic paper before sharing, submitting to arXiv, or sending to reviewers. The normal input is a LaTeX project containing `.tex` and `.bib` files, but the checker can also run against a directory with only a manuscript and bibliography files.
+
+This is a universal local skill. It does not depend on a specific agent runtime: run the bundled Python checker from this skill directory, inspect the report, then summarize hard failures and warnings.
+
+## What It Checks
+
+Hard checks block submission:
+
+- malformed or unresolved DOI and arXiv identifiers
+- Crossref DOI or arXiv metadata that clearly contradicts a comparable BibTeX title
+
+Soft checks need author review:
+
+- BibTeX entries with no DOI or arXiv ID, which need an agent/manual title
+  search before they are trusted
+- references whose DOI or arXiv ID resolves, but whose BibTeX title contains
+  LaTeX syntax the checker intentionally does not interpret
+- references whose DOI resolves but no catalog title metadata is available for
+  automatic comparison
+- Slop Guard prose lint output when enabled, including AI self-disclosure,
+  assistant tone markers, placeholder text, and formulaic writing signals
+
+The checker intentionally does not report missing cite keys, duplicate BibTeX
+keys, or unused BibTeX entries; LaTeX/BibTeX already covers compile-time
+citation consistency.
+
+The boundary is intentional: the script handles objective catalog lookups and
+high-confidence plain-title comparisons for `.bib` entries. It does not parse
+LaTeX citations; LaTeX/BibTeX owns citation consistency, and checking every
+BibTeX entry avoids fragile citation-command allowlists. It is not a LaTeX
+interpreter; when title normalization would require judgment, the report leaves
+that as an agent/manual warning instead of adding another fragile parsing rule.
+
+Load [references/checks.md](references/checks.md) only when you need the detailed taxonomy or want to tune the checker.
+
+## Invocation Questionnaire
+
+Before running the checker, ask a short startup questionnaire unless the user has
+already specified every choice. Use the active host's user-question mechanism:
+
+- Codex: `request_user_input`
+- Claude Code: `AskUserQuestion`
+
+If neither tool is available, present the same choices in Markdown and ask the
+user to reply with option labels or "Other". Ask for the paper root separately
+when it is missing; if several likely roots exist, offer them as choices.
+
+Ask these choices together when the host supports grouped questions:
+
+1. `run_profile`:
+   - Standard preflight (recommended): every bibliography entry, network
+     metadata verification, and Slop Guard if selected. Full papers can take a
+     minute or two because scholarly metadata lookups are network-bound.
+   - Offline structural pass: add `--offline`; bibliography parsing and
+     optional Slop Guard still run, but catalog lookups are skipped.
+2. `writing_lint_mode`:
+   - Run Slop Guard (recommended): include `--slop-guard`. This uses the local
+     `sg` CLI when available, otherwise `uvx --from slop-guard sg`; the first
+     `uvx` run may install Slop Guard into uv's cache.
+   - Skip Slop Guard: do not run prose lint.
+   - Local-only Slop Guard: include `--slop-guard` only if `sg` is already
+     installed as a shell command; otherwise explain that the user can install
+     Slop Guard or choose the normal `uvx` path.
+3. `output_mode`:
+   - Markdown report file (recommended): write
+     `paper-llm-proof-report.md` under the paper root.
+   - Markdown stdout: print the report instead of writing a file.
+   - JSON stdout: use `--format json` for downstream tooling.
+
+Map answers directly to flags: offline adds `--offline`; Slop Guard adds
+`--slop-guard`; JSON output adds `--format json`; report-file output adds
+`--format markdown --out <paper-root>/paper-llm-proof-report.md`.
+
+## Workflow
+
+1. Locate the paper root.
+   - Prefer the directory containing the main `.tex` file, `.bib` files, or build config.
+   - If multiple candidate roots exist, choose the one that contains the manuscript source and bibliography together.
+2. Run the invocation questionnaire and map the answers to checker flags.
+3. Run the bundled checker from this skill directory.
+
+```bash
+uv run --script scripts/check_paper.py /absolute/path/to/latex-project --format markdown --out /absolute/path/to/latex-project/paper-llm-proof-report.md
+```
+
+When `--out` is used, the checker prints a one-line stderr summary with hard
+failure count, warning count, and the exit code while leaving the full report in
+the requested file.
+
+The checker declares its Python dependencies in script metadata, so use
+`uv run --script` or execute `scripts/check_paper.py` directly to provision them
+automatically.
+
+1. Treat exit code `2` as a blocker.
+   - Do not wave away hard failures.
+   - Fix or explicitly escalate every hard failure before treating the paper as submission-ready.
+   - For hard reference failures, do a second-pass agent check before final
+     reporting: search the DOI, arXiv ID, or exact title in public scholarly
+     sources; if the paper is real and the checker missed an edge case, report
+     it as a checker false positive with the evidence.
+2. Review warnings manually.
+   - Manual-reference warnings mean the checker needs the calling agent to search the exact title.
+   - Slop Guard warnings mean the text contains residue or prose-lint signals that should be reviewed; do not accuse the author.
+3. Report results in submission-risk order.
+   - Start with hard failures if any exist.
+   - Include exact file paths and line numbers.
+   - For fake or unverifiable references, name the key and the verification method that failed.
+   - For references with no DOI or arXiv ID, search the exact title yourself and say whether the checker flagged a real risk or just needs manual confirmation.
+   - For warnings, explain what needs attention and what evidence would resolve it.
+
+## Useful Commands
+
+Check bibliography entries:
+
+```bash
+uv run --script scripts/check_paper.py /paper --format markdown --out /paper/paper-llm-proof-report.md
+```
+
+Emit machine-readable JSON:
+
+```bash
+uv run --script scripts/check_paper.py /paper --format json
+```
+
+Skip network verification for an offline structural pass:
+
+```bash
+uv run --script scripts/check_paper.py /paper --offline
+```
+
+Enable Slop Guard as warning-only prose-lint evidence:
+
+```bash
+uv run --script scripts/check_paper.py /paper --slop-guard
+```
+
+## Result Contract
+
+When this skill completes a pass, it should produce:
+
+- a local report file when `--out` is used
+- a clear hard-failure count
+- a clear warning count
+- enough file, line, key, and verification-method evidence for the author to act
+- no hard claim that a warning is true unless the evidence is direct
+
+If there are hard failures, say the paper is not ready for submission. If there are only warnings, say the paper needs author review in the listed areas before submission.

package/skills/flywheel-llm-proof-paper/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "LLM-Proof Paper"
+  short_description: "Check papers for fake references and prose slop signals"
+  default_prompt: "Use $flywheel-llm-proof-paper to sanity-check a LaTeX and BibTeX paper before submission."

package/skills/flywheel-llm-proof-paper/references/checks.md

@@ -0,0 +1,60 @@
+# Check Taxonomy
+
+## Hard Reference Checks
+
+The checker verifies every parsed entry in the discovered or explicitly supplied
+BibTeX files. It does not parse LaTeX citation commands; LaTeX/BibTeX owns
+compile-time citation consistency, and checking the `.bib` entries directly
+avoids fragile citation-command allowlists.
+
+Verification order:
+
+1. DOI from `doi`, `url`, `note`, or `eprint` fields.
+2. arXiv ID from `eprint` plus `archivePrefix`/`eprinttype`, `url`, or arXiv DOI.
+
+A reference is hard-failed when the strongest available identifier cannot be resolved, or when resolved metadata clearly conflicts with a comparable BibTeX title. Entries with no DOI or arXiv ID are warnings, not hard failures: the calling agent should search the exact title and report whether the reference is real, suspicious, or just missing machine-checkable metadata.
+
+Title comparison is intentionally limited. The checker normalizes plain text,
+accent commands, links, and simple one-argument formatting macros. It does not
+try to interpret arbitrary LaTeX. If an identifier resolves but the BibTeX title
+still contains unsupported LaTeX commands, the checker emits
+`title-needs-agent-check` so the consuming agent can compare the reference
+manually.
+
+The checker does not flag missing cite keys, duplicate BibTeX keys, or unused
+BibTeX entries. LaTeX/BibTeX already owns compile/renderability checks; this
+skill is focused on whether reference identifiers exist and point at the named
+paper.
+
+## Reference Warnings
+
+Reference warnings should trigger an agent/manual title search, not automatic rewrites.
+
+Common warning patterns:
+
+- bibliography entries with no DOI or arXiv ID
+- DOI resolver hits where Crossref/doi.org content negotiation does not provide
+  title metadata for automatic comparison
+- identifiers that resolve, but need agent/manual title comparison because the
+  BibTeX title is not confidently normalizable
+
+Generic URLs without a DOI or arXiv ID are intentionally left to the
+agent/manual exact-title search rather than brittle HTML title scraping.
+
+## Slop Guard
+
+`--slop-guard` strips manuscript text and passes it to Slop Guard through the
+local CLI, not MCP. The checker prefers `sg -j -` when `sg` is already
+installed as a shell command; otherwise it uses
+`uvx --from slop-guard sg -j -`.
+
+Treat Slop Guard results as triage evidence only. It covers AI
+self-disclosure, assistant tone markers, bracketed placeholders, stock phrases,
+and structural prose tics. A low score or prose-lint finding is never a hard
+failure by itself.
+
+## Catalog Pacing
+
+The checker uses open, no-key catalog endpoints only. Crossref and arXiv
+requests are serialized, retried with bounded exponential jitter, and paced to
+the public service limits.