patina-cli 3.11.0

package/docs/benchmarks/latest.md

@@ -0,0 +1,112 @@
+# Benchmark Report
+
+This is the latest checked-in report for patina's deterministic suspect-zone benchmark.
+
+> Scope: this benchmark measures whether patina's stylometry layer flags fixture paragraphs as AI-like editing hotspots. It does **not** prove whether a real document was written by a human or by AI.
+
+## Current result
+
+- Status: **passing**
+- Generated at: 2026-05-20T11:14:22.284Z
+- Node: v22.17.1
+- Fixture schema: v1
+- Fixtures: 34
+- Languages: 4 (en, ja, ko, zh)
+- Overall accuracy: **100.0%** [89.8%–100.0%] (n=34, Wilson score interval, 95%)
+- Source fixtures: `tests/fixtures/suspect-zones/**`
+- Regression ranges: `tests/fixtures/suspect-zones/expected-ranges.json` (refresh with `npm run benchmark:ranges`)
+- Reproduce: `npm run benchmark:report`
+- Raw JSON: [latest.json](latest.json)
+- Detector comparison harness: [detector-comparison.md](detector-comparison.md)
+- 2025+ re-baseline plan: [docs/research/2025-rebaseline-plan.md](../research/2025-rebaseline-plan.md)
+
+## Language breakdown
+
+| lang | fixtures | accuracy | 95% CI | precision | recall | f1 | TP | FP | FN | TN |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| en | 11 | 100.0% | 74.1%–100.0% | 100.0% | 100.0% | 1 | 6 | 0 | 0 | 5 |
+| ja | 6 | 100.0% | 61.0%–100.0% | 100.0% | 100.0% | 1 | 3 | 0 | 0 | 3 |
+| ko | 11 | 100.0% | 74.1%–100.0% | 100.0% | 100.0% | 1 | 6 | 0 | 0 | 5 |
+| zh | 6 | 100.0% | 61.0%–100.0% | 100.0% | 100.0% | 1 | 3 | 0 | 0 | 3 |
+
+## Detector breakdown
+
+| lang | detector | fixtures | accuracy | 95% CI | precision | recall | f1 | TP | FP | FN | TN |
+|---|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| en | burstiness | 11 | 100.0% | 74.1%–100.0% | 100.0% | 100.0% | 1 | 6 | 0 | 0 | 5 |
+| en | lexicon | 11 | 45.5% | 21.3%–72.0% | 0.0% | 0.0% | 0 | 0 | 0 | 6 | 5 |
+| en | mattr | 11 | 45.5% | 21.3%–72.0% | 0.0% | 0.0% | 0 | 0 | 0 | 6 | 5 |
+| ja | burstiness | 6 | 100.0% | 61.0%–100.0% | 100.0% | 100.0% | 1 | 3 | 0 | 0 | 3 |
+| ja | lexicon | 6 | 50.0% | 18.8%–81.2% | 0.0% | 0.0% | 0 | 0 | 0 | 3 | 3 |
+| ja | mattr | 6 | 50.0% | 18.8%–81.2% | 0.0% | 0.0% | 0 | 0 | 0 | 3 | 3 |
+| ko | burstiness | 11 | 100.0% | 74.1%–100.0% | 100.0% | 100.0% | 1 | 6 | 0 | 0 | 5 |
+| ko | lexicon | 11 | 81.8% | 52.3%–94.9% | 100.0% | 66.7% | 0.8 | 4 | 0 | 2 | 5 |
+| ko | mattr | 11 | 45.5% | 21.3%–72.0% | 0.0% | 0.0% | 0 | 0 | 0 | 6 | 5 |
+| zh | burstiness | 6 | 100.0% | 61.0%–100.0% | 100.0% | 100.0% | 1 | 3 | 0 | 0 | 3 |
+| zh | lexicon | 6 | 50.0% | 18.8%–81.2% | 0.0% | 0.0% | 0 | 0 | 0 | 3 | 3 |
+| zh | mattr | 6 | 50.0% | 18.8%–81.2% | 0.0% | 0.0% | 0 | 0 | 0 | 3 | 3 |
+
+## Sample sizes
+
+| lang | class | fixtures |
+|---|---|---:|
+| en | ai | 6 |
+| en | natural | 5 |
+| ja | ai | 3 |
+| ja | natural | 3 |
+| ko | ai | 6 |
+| ko | natural | 5 |
+| zh | ai | 3 |
+| zh | natural | 3 |
+
+## Misclassifications
+
+All fixtures classified correctly.
+
+## Fixture log
+
+| fixture | lang | class | expected | predicted | ok | CV band | MATTR band | lexicon/1k | sample lexicon hits |
+|---|---|---|---|---|---:|---:|---:|---:|---|
+| en-ai-01 | en | ai | hot | hot | ✓ | 0.058 low | 0.928 high | 0 | — |
+| en-ai-02 | en | ai | hot | hot | ✓ | 0.09 low | 0.841 high | 0 | — |
+| en-ai-03 | en | ai | hot | hot | ✓ | 0.065 low | 0.828 high | 0 | — |
+| en-ai-04 | en | ai | hot | hot | ✓ | 0.07 low | 0.84 high | 0 | — |
+| en-ai-05 | en | ai | hot | hot | ✓ | 0.093 low | 0.879 high | 0 | — |
+| en-ai-06-chat-register | en | ai | hot | hot | ✓ | 0.034 low | 0.814 high | 0 | — |
+| en-nat-01 | en | natural | cold | cold | ✓ | 0.881 high | 0.898 high | 0 | — |
+| en-nat-02 | en | natural | cold | cold | ✓ | 0.886 high | 0.884 high | 0 | — |
+| en-nat-03 | en | natural | cold | cold | ✓ | 0.914 high | 0.882 high | 0 | — |
+| en-nat-04 | en | natural | cold | cold | ✓ | 0.494 mid | 0.854 high | 0 | — |
+| en-nat-05 | en | natural | cold | cold | ✓ | 0.853 high | 0.875 high | 0 | — |
+| ja-ai-01 | ja | ai | hot | hot | ✓ | 0.045 low | 0.833 high | 0 | — |
+| ja-ai-02 | ja | ai | hot | hot | ✓ | 0.23 low | 0.785 high | 0 | — |
+| ja-ai-03 | ja | ai | hot | hot | ✓ | 0.063 low | 0.795 high | 0 | — |
+| ja-nat-01 | ja | natural | cold | cold | ✓ | 0.487 mid | 0.719 high | 0 | — |
+| ja-nat-02 | ja | natural | cold | cold | ✓ | 0.65 high | 0.796 high | 0 | — |
+| ja-nat-03 | ja | natural | cold | cold | ✓ | 0.395 mid | 0.807 high | 0 | — |
+| ko-ai-01 | ko | ai | hot | hot | ✓ | 0.093 low | 0.977 high | 23.256 | 추세 |
+| ko-ai-02 | ko | ai | hot | hot | ✓ | 0.073 low | 0.82 high | 19.608 | 환경 |
+| ko-ai-03 | ko | ai | hot | hot | ✓ | 0.073 low | 0.79 high | 19.608 | 추세 |
+| ko-ai-04 | ko | ai | hot | hot | ✓ | 0.098 low | 0.853 high | 0 | — |
+| ko-ai-05 | ko | ai | hot | hot | ✓ | 0.098 low | 0.853 high | 0 | — |
+| ko-ai-06-chat-register | ko | ai | hot | hot | ✓ | 0.081 low | 1 high | 21.739 | 흐름 |
+| ko-nat-01 | ko | natural | cold | cold | ✓ | 0.717 high | 1 high | 0 | — |
+| ko-nat-02 | ko | natural | cold | cold | ✓ | 0.552 high | 1 high | 0 | — |
+| ko-nat-03 | ko | natural | cold | cold | ✓ | 0.68 high | 1 high | 0 | — |
+| ko-nat-04 | ko | natural | cold | cold | ✓ | 0.771 high | 0.975 high | 0 | — |
+| ko-nat-05 | ko | natural | cold | cold | ✓ | 0.996 high | 0.998 high | 0 | — |
+| zh-ai-01 | zh | ai | hot | hot | ✓ | 0.062 low | 0.902 high | 0 | — |
+| zh-ai-02 | zh | ai | hot | hot | ✓ | 0.28 low | 0.734 high | 0 | — |
+| zh-ai-03 | zh | ai | hot | hot | ✓ | 0.083 low | 0.933 high | 0 | — |
+| zh-nat-01 | zh | natural | cold | cold | ✓ | 0.506 high | 0.875 high | 0 | — |
+| zh-nat-02 | zh | natural | cold | cold | ✓ | 0.528 high | 0.936 high | 0 | — |
+| zh-nat-03 | zh | natural | cold | cold | ✓ | 0.58 high | 0.907 high | 0 | — |
+
+## How to read this
+
+- **Hot** means at least one deterministic signal crossed the benchmark threshold: low burstiness CV, low MATTR, or AI-lexicon density.
+- **Cold** means the fixture did not cross those thresholds.
+- The report is meant for regression tracking and contributor discussion, not for authorship accusation.
+- This deterministic corpus is intentionally small (34 fixtures across en, ja, ko, zh); do not treat 100% fixture accuracy as generalization to new models, genres, or edited AI text.
+- Confidence intervals use Wilson score intervals for the checked-in fixture set; external threshold sweeps and 2025+ model rebaselines are separate research follow-ups tracked in [2025+ Re-baseline Plan](../research/2025-rebaseline-plan.md).
+- Broader methodology notes live in [AI/Human Metrics Research](../research/ai-human-metrics.md) and [Quality Checks](../../tests/quality/README.md).

package/docs/integrations/docker.md

@@ -0,0 +1,19 @@
+# Docker image
+
+The npm release job does not publish Docker images automatically. GHCR
+publishing is tracked separately so the first npm release can stay npm-only.
+
+Until the image is published, build the local image:
+
+```bash
+docker build -t patina:local .
+printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \
+  | docker run --rm -i -e PATINA_API_KEY patina:local --lang en --provider openai
+```
+
+Planned tags after the GHCR publishing issue is closed:
+
+- `ghcr.io/devswha/patina:<version>` — version tag from `v<version>`.
+- `ghcr.io/devswha/patina:latest` — latest release tag.
+
+The image uses `node:18-alpine`. It does **not** include codex, claude, or gemini CLI binaries, and it never carries local login state. For container runs, use an API-backed provider or mount your own authenticated tools explicitly.

package/docs/integrations/github-action.md

@@ -0,0 +1,59 @@
+# GitHub Action
+
+Patina's standalone Action repository is [`devswha/patina-action`](https://github.com/devswha/patina-action). It runs pull request prose review without a live model call, leaves a sticky comment with file-level hotspot scores, and can fail above an optional score threshold.
+
+> The Action defaults to `patina-cli@latest`, so the `@v1` tag should be cut after the npm publish in #203. Until then, pre-release workflows can use `@main` with `patina-package: github:devswha/patina`.
+
+```yaml
+name: Patina prose score
+
+on:
+  pull_request:
+    paths:
+      - '**/*.md'
+      - '**/*.mdx'
+
+permissions:
+  contents: read
+  pull-requests: read
+  issues: write
+
+jobs:
+  patina:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: devswha/patina-action@main # replace with @v1 after npm publish + action tag
+        with:
+          patina-package: github:devswha/patina # remove after patina-cli@latest is on npm
+          report-threshold: 30
+          lang: auto
+          comment: true
+```
+
+Once `patina-cli` is on npm and `devswha/patina-action@v1` is tagged, the stable form is:
+
+```yaml
+- uses: actions/checkout@v6
+- uses: devswha/patina-action@v1
+  with:
+    score-threshold: 30
+    comment: true
+```
+
+## Inputs
+
+| Input | Default | Meaning |
+|---|---:|---|
+| `github-token` | `${{ github.token }}` | Token for changed-file detection and comments. |
+| `files` | changed PR Markdown | Optional newline/comma/JSON file list; overrides paths-filter. |
+| `lang` | `auto` | `auto`, `ko`, `en`, `zh`, or `ja`. |
+| `score-threshold` | unset | If set, fail when any file score is above this percentage. |
+| `report-threshold` | `30` | Advisory report gate when `score-threshold` is unset. |
+| `max-files` | `50` | Maximum Markdown files to score. |
+| `comment` | `true` | Create/update a sticky PR comment. |
+| `patina-package` | `patina-cli@latest` | npm package spec used by `npx`. |
+
+## What it measures
+
+The Action uses `dorny/paths-filter@v4` to find changed Markdown files, runs Patina's deterministic `patina-score` command through `npx`, and updates a sticky comment with `peter-evans/create-or-update-comment@v5`. Read the table as a review queue. Open the highest row, check the surrounding paragraph, and decide whether the prose actually needs editing for your audience. It reports **editing hotspots**, not proof that text was AI-written.

package/docs/integrations/pre-commit.md

@@ -0,0 +1,77 @@
+# Pre-commit integrations
+
+Use these recipes when you want Patina to flag AI-sounding prose before Markdown changes land in a docs or blog repository.
+
+The hook is **score-only**: it never rewrites files during commit. It uses Patina's deterministic stylometry/lexicon layer, so it does not need an API key and it does not claim authorship provenance.
+
+## pre-commit framework
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/devswha/patina
+    rev: main # replace with a release tag after v1 is cut
+    hooks:
+      - id: patina-score
+        args: [--gate, "30", --lang, auto]
+```
+
+Run it locally:
+
+```bash
+pre-commit run patina-score --all-files
+```
+
+## Husky + lint-staged
+
+```bash
+npm install --save-dev husky lint-staged patina-cli
+npx husky init
+```
+
+```jsonc
+// package.json
+{
+  "lint-staged": {
+    "*.{md,mdx}": "patina-score --gate 30 --lang auto"
+  }
+}
+```
+
+```bash
+# .husky/pre-commit
+npx lint-staged
+```
+
+## Lefthook
+
+Install the package in the repository first:
+
+```bash
+npm install --save-dev patina-cli
+```
+
+```yaml
+# lefthook.yml
+pre-commit:
+  commands:
+    patina-score:
+      glob: "*.{md,mdx}"
+      run: npx patina-score --gate 30 --lang auto {staged_files}
+```
+
+A repo-local Lefthook command if this repository is vendored or checked out:
+
+```yaml
+pre-commit:
+  commands:
+    patina-score:
+      glob: "*.{md,mdx}"
+      run: node scripts/precommit-score.mjs --gate 30 --lang auto {staged_files}
+```
+
+## Tuning
+
+- `--gate 30` means fail when more than 30% of prose paragraphs in a file trip a hot signal.
+- `--lang auto` infers language from filename and Unicode ranges; pass `ko`, `en`, `zh`, or `ja` when a repo is single-language.
+- Use this as a discussion prompt, not as an accusation. See [ETHICS.md](../ETHICS.md).

package/docs/integrations/release.md

@@ -0,0 +1,43 @@
+# Release
+
+`release.yml` is the maintainer path for npm distribution artifacts.
+
+## Dry run
+
+```bash
+gh workflow run release.yml -f publish=false -f publish_ghcr=false
+```
+
+The dry run verifies:
+
+- version metadata across `package.json`, skill files, `.patina.default.yaml`, README, and CHANGELOG;
+- unit/e2e tests;
+- benchmark report schema;
+- dogfood docs score;
+- `npm pack --dry-run` for both `patina-cli` and the `patina-humanizer` alias package.
+
+## Publish
+
+Publishing the npm packages is intended for `v*.*.*` tags:
+
+```bash
+git tag v3.11.0
+git push origin v3.11.0
+```
+
+Required secret:
+
+- `NPM_TOKEN` for npm provenance publishing.
+
+The publish job uploads:
+
+- `patina-cli` to npm;
+- `patina-humanizer` alias to npm.
+
+Docker / GHCR publishing is intentionally decoupled from npm releases while
+the container distribution issue is still open. Maintainers can run the
+experimental image path manually after npm verification:
+
+```bash
+gh workflow run release.yml --ref v3.11.0 -f publish=false -f publish_ghcr=true
+```

package/docs/internal/HARNESS.md

@@ -0,0 +1,14 @@
+# Harness Notes
+
+Status: internal maintainer note. This is not public installation guidance.
+
+## Current stance
+
+- Patina is primarily a Markdown skill plus a Node.js CLI.
+- Use specification-first review for changes that touch pattern definitions, scoring logic, or meaning-preservation behavior.
+- Keep the core skill pipeline stable unless the change explicitly targets pipeline behavior.
+- For docs-only waves, prefer `docs-review` evidence and the standard npm verification gates.
+
+## Historical context
+
+Older agent notes referenced an OMC/Ouroboros harness as the primary working lane. The current workspace uses the repo's active Codex/OMX runtime instructions from `AGENTS.md` and the bootstrap files instead. Treat older harness-specific routing as historical unless it is reintroduced in active automation.

package/docs/internal/README.md

@@ -0,0 +1,14 @@
+# Internal Maintainer Notes
+
+These files are maintainer/agent context, not public user documentation. Public docs stay in the root README files and `docs/`; internal notes should not be treated as installation or API contracts.
+
+## Triage of legacy top-level Markdown
+
+| File | Decision | Rationale |
+|---|---|---|
+| `DESIGN.md` | keep public | Active product/brand source of truth; linked from the README docs list. |
+| `HARNESS.md` | moved here | Agent/harness notes are useful for maintainers but not user-facing. |
+| `WARP.md` | moved here | Warp-specific agent context is useful for maintainers but was stale as public root docs. |
+| `AGENTS.md`, `BOOTSTRAP.md`, `USER.md`, `IDENTITY.md`, `SOUL.md`, `MEMORY.md`, `HEARTBEAT.md`, `TOOLS.md` | not tracked in this branch | Runtime/local agent files are intentionally outside the public docs set when absent from git. |
+
+If a future internal note becomes a user-facing contract, move it back into `docs/` or the root and link it from `README.md` with a clear audience.

package/docs/internal/WARP.md

@@ -0,0 +1,23 @@
+# WARP Notes
+
+Status: internal maintainer note for Warp/agent users. Public usage remains in `README.md`, localized READMEs, and `docs/`.
+
+## What this repo is
+
+Patina is a Claude Code / Codex / Cursor / OpenCode skill plus a standalone Node.js CLI. It detects and rewrites AI writing patterns in Korean, English, Chinese, and Japanese while checking meaning preservation.
+
+## Current architecture reminders
+
+- `SKILL.md`: prompt-based `/patina` orchestrator.
+- `src/cli.js` and `bin/patina.js`: standalone CLI surface.
+- `patterns/{ko,en,zh,ja}-*.md`: language-specific pattern packs, auto-discovered by prefix.
+- `docs/PATTERNS.md` and `docs/PATTERNS-{KO,EN,ZH,JA}.md`: generated/manual references for the pattern packs.
+- `core/voice.md`, `profiles/*.md`, and `core/scoring.md`: voice, profile, and scoring references.
+- `SKILL-MAX.md` and `patina-max/SKILL.md`: MAX-mode references and installable entrypoint.
+
+## Safe-change rules
+
+- Do not change the core skill pipeline unless explicitly asked.
+- When editing patterns, include before/after examples.
+- Version-sync changes must update all five version-bearing files named in `AGENTS.md`.
+- Run the relevant npm gates before claiming completion.

package/docs/research/2025-rebaseline-plan.md

@@ -0,0 +1,89 @@
+# 2025+ Re-baseline Plan
+
+Status: protocol template, no external detector/vendor claims yet.  
+Owner: maintainers.  
+Related issues: #155, #163, #170, #172, #213.
+
+Patina's checked-in benchmark is a deterministic regression corpus. It is useful
+for catching tokenizer, threshold, lexicon, and fixture drift. It is not enough
+to claim performance against current LLM output. This plan defines the evidence
+needed before making broader README or launch-page claims.
+
+## Scope
+
+Measure whether Patina flags **AI-like writing signals** and preserves meaning
+after rewriting. Do not frame the result as authorship proof.
+
+Minimum matrix:
+
+| axis | minimum coverage |
+|---|---:|
+| languages | ko, en, zh, ja |
+| classes | AI-like, natural/human, lightly edited AI, heavily edited AI |
+| registers | blog, academic-summary, product-doc, chat/update, technical how-to |
+| generators | at least one GPT-family, Claude-family, Gemini-family, and open-weight model |
+| sample size | start at 25 paragraphs per language × class × register cell before publishing claims |
+
+## Data rules
+
+- Use redistributable prompts and generated text; do not check private user text into the repo.
+- Store full text only when redistribution is allowed. Otherwise store hashes, metadata, and metrics.
+- Keep generation metadata: model, provider, date, prompt id, decoding params, language, register, and any editing pass.
+- Separate detector-facing evaluation from rewrite-quality evaluation.
+
+## Metrics
+
+For deterministic suspect-zone detection:
+
+- accuracy, precision, recall, F1
+- Wilson 95% confidence interval per language and register
+- detector sub-signal breakdown: burstiness, MATTR, lexicon
+- expected metric ranges for checked-in fixtures
+
+For rewrite quality:
+
+- before/after AI-likeness score
+- MPS or manual meaning-preservation notes
+- named entity, number, negation, and causality preservation
+- human reviewer preference where available
+
+For external detector comparison:
+
+- use `npm run benchmark:compare` for the in-tree analyzer
+- add third-party rows manually through `scripts/detector-comparison.mjs --input <json>`
+- record detector id, date, plan/version if visible, score, and hot/cold label
+- avoid scraping and avoid automated vendor calls unless a service explicitly permits it
+
+## Artifact layout
+
+Recommended local/private layout before publishing sanitized summaries:
+
+```text
+artifacts/rebaseline-2025/
+├── prompts.jsonl
+├── generations.jsonl          # only redistributable text
+├── generations.private.jsonl  # gitignored/private text if needed
+├── patina-scores.jsonl
+├── third-party.manual.json
+├── reviewer-notes.jsonl
+└── summary.md
+```
+
+Checked-in public summaries should live under `docs/benchmarks/` after review.
+
+## Publication gate
+
+Do not publish competitive claims until the report includes:
+
+1. sample sizes by language, class, register, and generator
+2. confidence intervals, not just point estimates
+3. false-positive notes for human/natural prose
+4. clear statement that Patina measures AI-like writing signals, not authorship provenance
+5. reproducible commands or a manual collection protocol
+6. issue/PR links for corpus additions and threshold changes
+
+## Current baseline
+
+The current checked-in report is `docs/benchmarks/latest.md`. It covers a small
+curated suspect-zone corpus across ko/en/zh/ja and pins deterministic feature
+ranges in `tests/fixtures/suspect-zones/expected-ranges.json`.