john-slop/tasks.md

49 KiB
Raw Blame History

John Slop implementation plan

This backlog turns the current proof of concept into a reusable detector library with three thin binaries. Check an item only after its acceptance criteria and quality gates pass. Preserve unrelated user changes while refactoring.

Definition of done

A task is done when its public behavior is documented, errors carry actionable context, automated tests cover success and failure paths, and the following pass:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo doc --no-deps

For user-visible output, add deterministic snapshots/golden assertions without terminal color. For new dependencies, disable unnecessary default features, explain their role in the commit/PR, and run the available dependency/security audit in CI.

Milestone 0 — Baseline and decisions

  • Capture current behavior with tests before moving code: plain file, recursive directory, ZIP member, invalid UTF-8, missing path, and basic Unicode matching.
  • Fix the misleading Unicode tests/comments (UTF-8 byte lengths and grapheme terminology) so test names reflect what is actually asserted.
  • Record initial decisions in docs/decisions/: evidence confidence is not authorship probability; UTF-8 byte spans are canonical; formatter writes are opt-in; no archive mutation in the first formatter release.
  • Define supported inputs and limits: extensions/MIME policy, maximum file bytes, archive bytes, expanded bytes, entry count, nesting, hidden files, symlinks, and ignore rules.
  • Establish an MSRV in Cargo.toml and CI, add license/repository metadata, and document supported platforms.
  • Move tempfile and other test-only crates to [dev-dependencies]; remove rayon, once_cell, or unicode-segmentation if the final design does not justify them.

Acceptance: the existing behavior is characterized, ambiguous product choices are written down, and a clean baseline passes all quality gates.

Milestone 1 — Library-first restructure

  • Add src/lib.rs and expose a small facade for loading config, analyzing a source, planning replacements, and reading inputs.
  • Replace demo functions and ad hoc errors in main.rs with typed domain values (SourceId, Finding, Analysis, Confidence, TextEdit).
  • Split reader.rs into input/file.rs, input/walk.rs, and input/archive.rs; yield one Result<Document, InputError> at a time rather than loading a directory into a Vec.
  • Preserve outer and inner archive identities. Prevent path traversal and decompression bombs using the limits from Milestone 0.
  • Centralize error enums with thiserror; add miette context only at presentation boundaries. Remove placeholder try_report and sample reports.
  • Add explicit [[bin]] targets for john-slop, john-slop-fmt, and john-slop-lsp; the latter two may initially call stub adapters but all three must compile.
  • Keep binary parsing/orchestration out of the library. Add clap with derive for stable help, validation, and exit-code handling.

Acceptance: integration tests can call the library without spawning a process; all binaries build; no production module is a demo; failures in one directory entry do not discard successful documents.

Requested quality and documentation pass

  • Update the declared Rust toolchain and direct dependencies to their latest stable releases; verify the locked graph with the declared toolchain.
  • Add focused behavioral and snapshot tests, including feature-matrix coverage, without snapshotting structured domain values unnecessarily.
  • Configure Tarpaulin with an enforceable coverage floor around 30%, run rust_autobadges, and publish local version/test/coverage badges.
  • Reduce the root README to a generic project landing page and move detailed usage, architecture, testing, coverage, and background links under docs/.

Milestone 2 — Typed layered configuration

  • Add Serde, figment with TOML support, and a platform-aware configuration directory crate such as directories.
  • Create assets/config.toml as the embedded replacement catalog with schema_version and documented examples.
  • Create assets/heuristics.toml as a separate embedded rule catalog with stable IDs, categories, matcher types, weights, messages, help, occurrence caps, and applicability scopes.
  • Implement exact precedence: embedded defaults < user config.toml < named user <config_name>.toml < explicit --config < explicit CLI flags.
  • Validate config names and refuse traversal, extensions, empty names, and non-ASCII characters. Resolve the user path with platform APIs.
  • Implement merge-by-ID for rule/replacement tables rather than allowing positional array replacement to produce surprising partial configuration.
  • Validate the fully resolved model: schema version, unique IDs/sources, ASCII-only replacement targets, regex compilation, finite non-negative weights, ordered thresholds, safe matchers, and edit conflicts.
  • Preserve enough provider metadata to identify the offending file and key in a miette configuration diagnostic.
  • Add john-slop config show and john-slop config paths so precedence is inspectable; output deterministic TOML or JSON.
  • Test every layer alone and in combination, including missing optional files, malformed TOML, unknown fields, named configs, array semantics, and CLI wins.

Acceptance: installed binaries work without source-tree assets, the resolved configuration is explainable, and all precedence/validation tests pass.

Milestone 3 — Heuristic detection engine

  • Define a Rule/Detector interface and a registry built entirely from the validated heuristic config. Compile reusable matchers once.
  • Implement exact phrase and regex rules with precise byte spans, match text, category, weight, message, help, and stable rule ID.
  • Add conservative first-party rules for copied assistant disclaimers, knowledge-cutoff language, prompt/response leakage, templated filler, repetitive transitions/conclusions, suspicious Unicode, and code-specific placeholder or tutorial residue.
  • Add applicability filters for prose versus source code, extension/language, include/exclude globs, and generated/vendor/minified paths.
  • Design the confidence formula: bounded weighted evidence, per-rule caps, correlated-family damping, normalization to 0..=100, and configurable low/medium/high thresholds.
  • Return zero confidence and no verdict for empty/no-evidence input. Keep unsupported/binary input distinct from a clean analysis.
  • Sort findings deterministically and deduplicate identical rule/span pairs.
  • Add table-driven unit tests for every shipped rule with positive examples and realistic near misses. Add tests for disabled rules, overrides, scope, caps, damping, threshold boundaries, and multilingual text.
  • Build a reviewed evaluation corpus that is legally distributable and labels observable low-care signals, not presumed author identity. Report per-rule precision/recall and aggregate false-positive rates before tuning defaults.
  • Document limitations, adversarial evasion, domain shift, and why the score is not an AI-authorship probability.

Acceptance: every score decomposes into visible findings; no high-confidence result can arise solely from a single weak repeated signal; the shipped rules and formula are pinned by tests.

Milestone 4 — Diagnostics and detector CLI

  • Convert each Finding into a typed miette::Diagnostic with named source, exact SourceSpan, severity, rule ID as diagnostic code, message, and help.
  • Add a summary that reports confidence band/score and counts by severity, while retaining every contributing diagnostic.
  • Build detector CLI inputs for file, directory, and stdin (--stdin-filename for language/path scoping); add ignore and maximum-size controls.
  • Add human, concise, and versioned JSON output modes. Ensure JSON and stdout diagnostics never contain logs or ANSI escapes.
  • Implement documented exit codes: 0 below fail threshold, 1 at/above it, 2 for usage/configuration/I/O failure. Add --fail-level.
  • Report per-document input errors without hiding findings from other documents; define whether partial failure returns 2 and test it.
  • Add CLI integration tests for spans containing multibyte UTF-8, multiple files, stdin, missing paths, malformed configs, stable ordering, JSON schema, and exit codes.

Acceptance: a user can trace the aggregate score to highlighted source ranges and remediation help; CI can consume stable machine output and exit statuses.

Milestone 5 — Shared ASCII replacement engine and formatter

  • Parse replacement definitions into a trie or deterministic longest-match planner and emit validated, non-overlapping TextEdits against the original source.
  • Apply edits from highest to lowest byte offset. Preserve line endings and return the original buffer unchanged when there are no edits.
  • Reject non-character-boundary and overlapping edits as typed invariant errors. Define deterministic behavior when sources share prefixes.
  • Implement john-slop-fmt stdin/stdout mode, --check, --diff, and explicit --write. Require an explicit policy for recursive directory writes.
  • Make writes atomic with a same-directory temporary file plus rename when supported; retain permissions and never rewrite on analysis/config failure.
  • Do not rewrite ZIP/DOCX/XLSX/PPTX members in this milestone; emit a clear unsupported-operation diagnostic.
  • Add unit/property tests for idempotence, Unicode boundaries, longest match, non-overlap, stable output, line endings, empty input, and no-op byte identity.
  • Add integration tests proving --check exit status, stdout purity, atomic failure behavior, config overrides, and formatter/detector agreement.

Acceptance: formatting twice equals formatting once; default invocation does not modify files; every replacement comes from the resolved typed config.

Decision: ReplacementRule::source is a non-empty Unicode String rather than a single char, enabling deterministic longest-match behavior for shared prefixes. This is a deliberate public data-contract change made before the first formatter milestone tag.

Milestone 6 — LSP binary

  • Select an actively maintained LSP framework after a short dependency/API review (evaluate tower-lsp-server); pin the decision and protocol assumptions in a decision record.
  • Implement stdio initialization/shutdown and incremental or full document synchronization with URI, version, language ID, and current text tracked per open document.
  • Build and thoroughly test byte-offset to LSP UTF-16 line/character mapping, including CRLF, emoji, combining marks, astral characters, and EOF positions.
  • Publish diagnostics only for configured ASCII-replacement findings in the initial release. Include stable codes and source john-slop.
  • Expose quick fixes/code actions using the exact edits from the shared replacement engine; reject stale-version requests.
  • Recompute after open/change/configuration updates, clear on close, and avoid publishing obsolete results when analysis overlaps newer edits.
  • Keep all protocol bytes on stdout and diagnostics/logging on stderr. Add opt-in structured logging without document contents.
  • Add in-process protocol tests for lifecycle, versions, Unicode positions, config reload, close cleanup, invalid URI, malformed messages, concurrent documents, and formatter/LSP output equivalence.

Acceptance: a standards-compliant client can see replacement diagnostics and apply a quick fix; the resulting text exactly matches john-slop-fmt under the same config.

Milestone 7 — Hardening, documentation, and release

  • Replace the placeholder README with installation, threat model, examples, configuration precedence/schema, rule authoring, confidence interpretation, CLI/formatter/LSP setup, exit codes, privacy, and limitations.
  • Publish commented sample base and named configs. Document how to disable a rule/replacement and how merge-by-ID works.
  • Add CI on the supported OS/MSRV matrix for formatting, Clippy, tests, docs, audit/deny checks, and fixture/golden consistency.
  • Add fuzz targets for TOML/config merging, regex/rule loading, UTF-8 span mapping, replacement planning, and malicious ZIP metadata. Seed them with regression fixtures.
  • Benchmark large files, many small files, rule scaling, and archive limits. Add parallelism only if measurement shows a benefit and output remains ordered.
  • Review dependency features, licenses, advisories, unsafe code, and release binary size. Generate checksums if releases distribute binaries.
  • Add changelog, contribution guide, code of conduct, security reporting instructions, release profile, and reproducible release procedure.
  • Run a false-positive review against the evaluation corpus and require an explicit sign-off before changing default rule weights or thresholds.

Acceptance: a new user can install and operate all three binaries from the README; CI enforces the documented contracts; release artifacts are reproducible and the detector's limitations are prominent.

Accepted on 2026-09-29 after the full all-feature/minimal-feature quality gate, dependency policy checks, fuzz-seed runs, reproducible packaging, and an 80.51% line-coverage run.

Milestone 8 — Meaningful coverage expansion

  • Cover configuration merging, validation failures, domain formatting, and diagnostic accessors with behavior-focused unit tests.
  • Cover archive and input resource-policy branches with generated fixtures, including unsafe, binary, malformed, and oversized members.
  • Cover remaining practical CLI, formatter, and LSP adapter branches without coupling tests to unreachable platform failures or coverage-tool artifacts.
  • Raise measured Tarpaulin line coverage toward 90%, refresh badges and development documentation, and record any intentionally uncovered remainder.

Acceptance: the suite exercises at least 90% of measurable source lines when Tarpaulin can attribute them reliably; remaining misses are documented and do not justify brittle tests or production changes made solely for instrumentation.

Accepted on 2026-09-29 at 92.16% line coverage (1,329/1,442), with the CI floor raised to 90%. Remaining misses are primarily hard-to-inject OS/I/O failures, malformed dependency internals, overflow guards, and asynchronous LSP error plumbing; pursuing them would add test-only seams or backend-sensitive checks.

Milestone 9 — Terminal-first diagnostics

  • Make colored graphical Miette diagnostics the detector default while retaining explicit plain-human, concise, JSON, and no-feature fallback modes.

Acceptance: a default detector invocation renders graphical Unicode diagnostics with ANSI severity colors; explicit machine modes remain stable and uncolored, and builds without fancy-diagnostics retain the plain human fallback.

Milestone 10 — Prompt-leakage scoring priority

  • Give distinct prompt-leakage rules lighter correlation damping (0.90ⁿ) while preserving 0.75ⁿ damping for style, typography, and source-code families and preserving per-rule occurrence damping/caps.
  • Re-run the reviewed corpus, renew the existing default-policy sign-off, and document the changed formula and showcase score without changing the sign-off mechanism itself.

Acceptance: multiple independent prompt-leakage artifacts contribute more than equally weighted correlated style signals; the diagnostic showcase score is pinned, the evaluation corpus remains free of observed regressions, and all quality/coverage gates pass.

Accepted on 2026-09-29: the showcase score is 71 (medium); reviewed positive corpus scores are pinned at 60/33/19/24/17, all five negative documents remain at zero, and matching metrics remain 11 TP, 0 FP, and 0 FN.

Optional follow-up, intentionally not required for this milestone:

  • After observing real usage, choose one direction for the default-policy sign-off feature: harden its change boundary beyond the catalog hash, or remove it if its maintenance cost exceeds its demonstrated value.

Milestone 11 — Evidence-score terminology

  • Rename the public domain model from ambiguous confidence terminology to EvidenceScore, EvidenceBand, and EvidenceThresholds; retain deprecated Rust type aliases and the legacy --fail-confidence CLI alias for migration.
  • Publish the low-care evidence-score wording across terminal output, examples, and documentation; rename --fail-confidence to --fail-score and version the JSON field rename as schema version 2.
  • Run the complete quality and coverage gates, refresh generated badges, and record the compatibility boundary and unchanged scoring formula.

Acceptance: every active user-facing contract describes the metric as a bounded low-care evidence score rather than a probability or calibrated confidence; legacy type and CLI names remain usable with clear migration guidance; JSON consumers can identify the field rename by schema version; scoring results are unchanged; and all quality/coverage gates pass.

Accepted on 2026-09-29: all-feature and minimal-feature suites, formatting, Clippy, and documentation pass; deprecated Rust aliases and the legacy CLI alias are covered; Tarpaulin remains at 92.19% (1,334/1,447 lines) against the 90% floor; and the generated badges are current.

Milestone 12 — Experimental crate boundary

  • Capture reproducible baseline cold and incremental check times from v0.1.11, identify dependency ownership, and choose the smallest crate boundary capable of excluding async/LSP dependencies from core builds.
  • Extract the reusable detector/configuration/input implementation into a john-slop-core workspace crate and the protocol engine into a john-slop-lsp workspace crate. Keep the root package as the compatibility facade and binary distribution, preserving public behavior and all three executable names.
  • Run identical clean and incremental measurements on the experiment, compare compile time, artifact size, dependency isolation, API/release cost, tests, coverage, and packaging against v0.1.11, then record an explicit merge-or-abandon recommendation.

Acceptance: the branch contains a reviewable implementation commit and a reproducible before/after report; all existing behavior and quality gates pass; any claimed build improvement is measured rather than inferred. Do not merge the experiment when its gains do not justify the added workspace and release complexity.

Completed on 2026-09-29 with a do-not-merge-yet recommendation that was subsequently superseded by the explicit Milestone 13 adoption decision. Core and no-LSP checks use roughly 35–55% less CPU/disk, but the full workspace remains effectively unchanged while package publishing, version synchronization, asset ownership, feature contracts, CI, and coverage all become more complex. The complete measurements and adoption rationale are in docs/experiments/crate-boundary.md and ADR 0004.

Milestone 13 — Supported Cargo workspace

  • Promote the experimental three-package layout to the supported project architecture. Keep the root john-slop compatibility facade and binary package as the workspace root; centralize shared package metadata, dependency versions, and lint policy with Cargo workspace inheritance while retaining per-package feature activation and optionality.
  • Add automated workspace-contract checks for membership, synchronized versions, inherited dependency sources, and core/LSP feature isolation. Make CI, packaging, and publication guidance explicitly workspace-aware and verify every publishable package in dependency order.
  • Replace the experimental recommendation with an adoption decision, update architecture/dependency/development/release documentation, run the complete feature, lint, documentation, coverage, and package gates, and refresh the generated badges and recap.

Acceptance: all three publishable packages inherit one version and one source of truth for shared dependency requirements; john-slop-core remains free of CLI/async/LSP dependencies; unqualified root commands cover every default workspace member; each package can be assembled for publication in dependency order; coverage remains at or above 90%; and the measured costs of supporting the workspace are recorded rather than hidden.

Accepted on 2026-09-29 after both feature matrices, formatting, Clippy, documentation, RustSec, cargo-deny, workspace package assembly, and the 90% coverage floor passed. Tarpaulin remains at 92.19% (1,334/1,447 lines); the workspace boundary changes dependency ownership, not executable behavior or measurable source coverage.

Milestone 14 — Readable graphical diagnostics

  • Give each graphical Miette diagnostic a visible title marker, remove the empty line between its rule-code title and message, and add one empty line after the complete diagnostic. Pin the layout in unit and showcase tests, document it, and leave human, concise, JSON, and minimal-feature fallback output unchanged.

Acceptance: adjacent graphical findings have unambiguous boundaries; title and message remain visually connected; stable rule IDs, severity symbols, colors, source annotations, help, summaries, and machine-output contracts are preserved; all quality and coverage gates pass.

Accepted on 2026-09-29 after graphical unit/showcase layout tests, the minimal-feature fallback test, both complete feature matrices, formatting, Clippy, rustdoc, and Tarpaulin passed. Coverage is 92.23% (1,342/1,455 lines) against the 90% floor.

Milestone 15 — Comprehensive diagnostic showcase

  • Extend the expected-failure showcase across prose and Rust fixtures so it demonstrates every currently shipped heuristic kind and every embedded ASCII replacement character where practical. Keep completeness aspirational rather than coupling the test dynamically to future catalog additions; document the two-file command and retain the intentional threshold failure.

Acceptance: the manual showcase visibly includes prompt leakage, style, typography, source placeholders, tutorial narration, advice, warnings, errors, fixable findings, and per-document summaries; tests pin representative coverage and formatting without asserting exact equality with the evolving catalogs.

Accepted on 2026-09-29 after the showcase exercised all 11 currently shipped heuristic rule IDs and all 10 embedded replacement characters across two documents and 25 findings. Both feature matrices, formatting, Clippy, rustdoc, and Tarpaulin passed; coverage remains 92.23% (1,342/1,455 lines).

Milestone 16 — Source-checkout installation

  • Document Cargo's explicit --path . form for installation from a local checkout, keep the remote Git installation form distinct, and smoke-test the local command in an isolated installation root.

Acceptance: a reader can distinguish installing the repository checkout from installing the upstream Git repository; the documented local command installs all three binaries with the locked, all-feature dependency graph on supported Rust; documentation checks remain clean.

Accepted on 2026-09-29 after the documented local command installed john-slop, john-slop-fmt, and john-slop-lsp into an isolated root with the locked all-feature graph. Formatting and all-feature rustdoc also passed.

Milestone 17 — Progressive documentation entry points

  • Restructure the root README around an immediately runnable quickstart and a concise product overview, then present the user-facing guides in a natural learning order. Move the dense engineering, evaluation, security, and design navigation behind a dedicated advanced guide and align the documentation index with the same progression.

Acceptance: a new reader can install and run the detector before encountering configuration details; the README explains the detector, formatter, and LSP without duplicating their full guides; common next steps are ordered by likely need; advanced reference material remains discoverable through one clear entry point; all local Markdown links resolve and documentation checks pass.

Accepted on 2026-09-29 after the root README was reduced to a quickstart, three-binary overview, and six-step learning path; the documentation index now mirrors that progression; and docs/advanced.md groups the deeper conceptual and engineering material. Every repository-local Markdown link resolves, and formatting, line-length, and all-feature rustdoc checks pass.

Milestone 18 — Full printable-ASCII replacement showcase

  • Add an opt-in Rust example and checked-in input/expected-output fixtures that map the fullwidth Unicode forms of every printable non-space ASCII character, plus ideographic space, to all 95 printable ASCII targets. Reuse the embedded fullwidth-hyphen rule, construct the remaining showcase-only rules through the public configuration API, and leave conservative production defaults unchanged.

Acceptance: the runnable example plans exactly 95 non-overlapping edits and produces the checked-in ASCII output; tests prove every byte from ASCII space through tilde is represented once as a target; documentation clearly labels the mapping as an API/configuration showcase rather than a recommended universal rewrite policy; both feature matrices and the coverage floor pass.

Accepted on 2026-09-29 after the example produced exactly 95 edits whose unique targets span ASCII space (0x20) through tilde (0x7e) and matched the checked-in output byte for byte. Formatting, Clippy, rustdoc, both feature matrices, and Tarpaulin passed; production coverage remains 92.23% (1,342/1,455 lines).

Milestone 19 — Full heuristic LSP diagnostics

  • Extend the LSP publication pipeline from replacement-only warnings to all enabled detector findings applicable to the open document, including style, prompt-leakage, and source-code rules. Compile the detector once per resolved configuration, infer applicability from file URIs and editor language IDs, map configured severities and stable heuristic IDs into LSP diagnostics, and preserve versioned ASCII quick fixes only for findings with replacement edits. Amend the original replacement-only protocol decision and update editor, usage, architecture, limitation, help, and contributor documentation.

Acceptance: repeated-transition and the other configured heuristics appear on open, accepted changes, and successful configuration reloads with exact UTF-16 ranges, configured severity, remediation text, stable john-slop codes, and version metadata; replacement findings are not duplicated and retain formatter- equivalent quick fixes; prose/source applicability is tested for file and untitled documents; stale-action, close, concurrency, and failed-reload behavior remain intact; both feature matrices and the coverage floor pass.

Accepted on 2026-09-29 after the in-process protocol suite demonstrated repeated-transition, source placeholders, tutorial narration, typography, severity/help/code/version mapping, prose/source applicability, replacement-only actions, configuration reload and rollback, stale rejection, concurrent documents, and close cleanup. Formatting, Clippy, rustdoc, both feature matrices, and Tarpaulin passed; coverage is 92.34% (1,411/1,528 lines).

Milestone 20 — Milestone and package version synchronization

  • Correct the version drift forward without moving immutable tags: bump the workspace packages and internal registry requirements to 0.1.20, refresh the lockfile and generated version badge, cut the accumulated changelog entry, and make the workspace contract verify that Cargo metadata, internal dependency requirements, the lockfile, and badge all agree. Require future Milestone N completion commits to carry workspace version 0.1.N before badge generation and tagging.

Acceptance: all three packages, their internal dependency requirements, Cargo.lock, binary --version output, changelog, badge, completion commit, and new v0.1.20 tag agree; the existing v0.1.19 and earlier tags remain untouched; workspace package assembly, both feature matrices, documentation, and the coverage floor pass.

Accepted on 2026-09-29 after all three packages, internal registry dependency requirements, root and fuzz lockfiles, reviewed evaluation sign-off, three binary version strings, changelog, and generated badge were synchronized at 0.1.20. The workspace contract now rejects metadata, dependency, lockfile, or badge drift. Formatting, Clippy, rustdoc, both feature matrices, pre-publication package assembly, and Tarpaulin passed; coverage remains 92.34% (1,411/1,528 lines).

Milestone 21 — LSP formatter parity and Unicode review diagnostics

  • Implement and advertise textDocument/formatting in the LSP using the same resolved configuration and core replacement planner as john-slop-fmt. Return deterministic UTF-16 edits against the current editor snapshot, cover Unicode/CRLF/no-op/custom-config/reload cases, and replace the misleading quick-fix-only equivalence assertion with an actual protocol request.
  • Add non-fixing review diagnostics for Unicode characters that resemble ASCII under a pinned Unicode UTS #39 profile, plus Gitea-compatible invisible and bidirectional controls. Keep these findings distinct from the smaller automatic replacement allowlist, configurable as normal heuristic rules, and document provenance, multilingual false positives, and profile boundaries.
  • Refresh examples, editor/architecture/configuration/limitations guides, evaluation fixtures and sign-off, coverage metadata, package version 0.1.21, changelog, and generated badges.

Acceptance: a real LSP formatting request produces exactly the same text as john-slop-fmt for the same source and layered configuration; formatter output contains no broader confusable rewrite; representative ASCII-lookalikes, invisible characters, and bidi controls receive exact-span CLI and LSP diagnostics without quick fixes; ordinary ASCII and reviewed multilingual near misses remain covered; formatting, Clippy, rustdoc, both feature matrices, package assembly, and the coverage floor pass before the immutable v0.1.21 tag is created.

Accepted on 2026-09-30 after real protocol-formatting parity tests, exact-span CLI/LSP Unicode diagnostics, a non-mutating shared fixture, and the renewed 13-rule evaluation corpus passed. Formatting, Clippy, rustdoc, both feature matrices, dependency policy/audit checks, and workspace package assembly pass; coverage is 92.40% (1,472/1,593 lines), and all packages, binaries, lockfiles, changelog, and the generated badge agree on 0.1.21.

Milestone 22 — Maintainable ambiguous-Unicode replacement catalog

  • Define one versioned Unicode policy asset that owns the replacement diagnostic metadata, reviewed legacy punctuation mappings, generated UTS #39 ASCII-skeleton mappings, and invisible-control diagnostic metadata. Add a deterministic generator with pinned Unicode provenance and drift checks.
  • Make the shared replacement planner efficient for the expanded catalog, load the catalog through every configuration path, and use its mappings for CLI fixes, formatter output, LSP quick fixes, and LSP document formatting. Preserve review-only behavior for invisible and bidirectional controls.
  • Expand fixtures and regression tests across letters, digits, punctuation, mathematical/fullwidth forms, multilingual risk cases, user overrides, and CLI/LSP/formatter parity. Update guides, evaluation sign-off, coverage, changelog, package version 0.1.22, badges, and release metadata.

Acceptance: the checked-in catalog covers every non-ASCII scalar whose pinned Unicode 16.0 UTS #39 skeleton is non-empty printable ASCII, except explicitly documented exclusions; each mapping produces one exact diagnostic and the same replacement through the CLI, standalone formatter, LSP quick fix, and LSP formatting; the catalog can be regenerated deterministically and drift is tested; invisible/bidi controls stay non-mutating; formatting remains idempotent; all quality, audit, package, and 90% coverage gates pass before the immutable v0.1.22 tag is created.

Accepted on 2026-09-30 after the generated 1,829-entry catalog reproduced byte-for-byte, exhaustive Unicode drift validation passed, and CLI, standalone formatter, LSP quick-fix, and LSP-formatting tests produced identical mappings. The replace, review, and off policies and diagnostic-only controls are covered across both feature matrices. Formatting, Clippy, rustdoc, evaluation, dependency policy/audit checks, and workspace package assembly pass; coverage is 93.05% (1,487/1,598 lines), and release metadata agrees on 0.1.22.

Milestone 23 — Diagnostic policy and local configuration bootstrap

  • Add typed category gates to the existing layered TOML schema while retaining [[rules]] enabled = true|false for individual diagnostics. A rule runs only when both its category and individual switches are enabled; test user, named, and explicit-layer precedence plus unknown configuration keys.
  • Add john-slop config init to write the embedded, commented default configuration to ./config.toml. Refuse to replace an existing file by default, support an explicit --force, and test the generated file by loading it through the public configuration path.
  • Update the quickstart, configuration examples, CLI help, changelog, release metadata, badges, and ignored recap; run both feature matrices, formatting, Clippy, rustdoc, package/audit checks, and Tarpaulin.

Acceptance: category and individual diagnostic switches work identically in the CLI and LSP because they resolve in the shared core configuration; a fresh john-slop config init creates a valid documented config.toml in the current directory without silently destroying user data; all release artifacts agree on 0.1.23 before the immutable v0.1.23 tag is created.

Accepted on 2026-09-30 after layered category and individual switches produced matching CLI/LSP behavior, and config generation passed create, preserve, force-overwrite, parse, and reload checks. Formatting, Clippy, rustdoc, both feature matrices, evaluation, dependency policy/audit checks, and workspace package assembly pass; coverage is 93.09% (1,523/1,636 lines), and all release metadata and binary versions agree on 0.1.23.

Milestone 24 — Runtime diagnostic catalogs

  • Load a dedicated $CONFIG_DIR/john-slop/diagnostics.toml before normal configuration overrides, and accept repeatable explicit diagnostic catalogs. Restrict these files to schema metadata and [[rules]], retain merge-by-ID, reject malformed/incomplete/duplicate definitions, and test precedence.
  • Add repeatable --diagnostics <FILE> support to the detector, formatter, and LSP adapters; add a safe command that generates a valid commented ./diagnostics.toml starter without overwriting it unless forced. Cover CLI detection, LSP reload, help, missing files, and generated-template loading.
  • Update configuration/editor/development guides, examples, changelog, evaluation sign-off, release metadata, coverage, badges, and ignored recap; run all quality, audit, and package gates.

Acceptance: adding an exact-phrase, regex, or repeated-regex diagnostic to the dedicated user catalog or an explicit catalog changes CLI and LSP diagnostics without source edits or recompilation; later normal configuration layers can override or disable those rules; code-backed matcher implementations, replacement engines, and category expansion remain explicitly out of scope; all release artifacts agree on 0.1.24 before the immutable v0.1.24 tag is created.

Accepted on 2026-09-30 after runtime catalogs added diagnostics through the CLI and LSP without rebuilding, normal configuration disabled those rules by stable ID, and invalid or code-backed definitions failed explicitly. Formatting, Clippy, rustdoc, both feature matrices, evaluation, dependency policy/audit checks, Unicode-catalog reproducibility, and workspace package assembly pass; coverage is 92.83% (1,579/1,701 lines), and all release metadata and binary versions agree on 0.1.24.

Milestone 25 — Deterministic fullwidth ASCII folding

  • Give ideographic space and every fullwidth form in U+FF01..=U+FF5E an explicit one-to-one printable ASCII replacement before generating broader UTS #39 skeleton mappings. Preserve all previously shipped fullwidth IDs and cover the complete sequence through core, formatter-example, and real LSP formatting tests.
  • Update Unicode/configuration guidance, changelog, release metadata, coverage, badges, and recap; run all quality, audit, regeneration, and package gates.

Decision: compatibility width folding takes precedence over visual-confusable skeletons for this contiguous Unicode block. These 95 reviewed mappings remain active under replace, review, and off; the bulk policy continues to govern only uts39-* mappings. This prevents visually motivated results such as fullwidth I becoming lowercase l, while preserving policy compatibility and the shared planner used by the CLI, formatter, and LSP.

Acceptance: formatting ideographic space followed by U+FF01..=U+FF5E produces ASCII space through tilde exactly, with 95 source-ordered edits and identical standalone/LSP output; the generated catalog remains deterministic; all release artifacts agree on 0.1.25 before the immutable v0.1.25 tag is created.

Accepted on 2026-09-30 after the embedded catalog width-folded all 95 compatibility forms to ASCII space through tilde and the real LSP protocol produced identical output. Formatting, Clippy, rustdoc, both feature matrices, evaluation, dependency policy/audit checks, Unicode-catalog reproducibility, and workspace package assembly pass; coverage is 92.84% (1,583/1,705 lines), and all release metadata and binary versions agree on 0.1.25.

Milestone 26 — Evidence tiers and quiet editor defaults

  • Document the research boundary between directly reviewable residue, low-confidence population-level signals, and unreliable authorship inference. Add conservative data-driven rules with positive and near-miss evaluation fixtures, while explicitly excluding fluency and perplexity proxies.
  • Make LSP diagnostics Unicode-only by default. Add an --all-diagnostics testing switch and a minimum-weight opt-in that always retains Unicode findings while suppressing lighter non-Unicode signals. Cover the policy through unit, protocol, and CLI-help tests.
  • Update editor/configuration guidance, changelog, evaluation sign-off, release metadata, coverage, badges, and recap; run all quality, audit, regeneration, and package gates.

Decision: rule weight remains bounded evidence for scoring, not a probability of AI authorship. LSP visibility is a separate presentation policy: Unicode findings are shown by default because they are exact and fixable; non-Unicode rules require an explicit all-diagnostics switch or minimum-weight threshold. This keeps subtle research-derived vocabulary and style clues out of the default editor experience without weakening CLI analysis or configuration.

Acceptance: the methodology cites primary evidence and states what the tool will not infer; each new rule has reviewed positive and near-miss coverage; the default LSP publishes only Unicode findings, both opt-in modes are deterministic, and all release artifacts agree on 0.1.26 before the immutable v0.1.26 tag is created.

Accepted on 2026-09-30 after 19 shipped rules each passed positive and realistic near-miss characterization, the default protocol path published only Unicode, and weighted/all-diagnostic opt-ins passed unit, CLI, and real LSP tests. Formatting, Clippy, rustdoc, both feature matrices, evaluation, dependency policy/audit checks, Unicode-catalog reproducibility, and workspace package assembly pass; coverage is 92.72% (1,604/1,730 lines), and all release metadata and binary versions agree on 0.1.26.

Post-milestone CI maintenance

  • Prevent retained release bundles from breaking later builds in a reused Jenkins workspace, and keep release packaging limited to the artifacts the project currently distributes.
  • Replace the yanked transitive yoke-derive 0.8.3 lockfile entry with the compatible non-yanked 0.8.4 release so the deny-warnings audit remains reproducible.
  • Ignore legacy per-package cargo cyclonedx intermediates left by earlier builds so workspace packaging remains clean after SBOM generation is removed.
  • Remove Jenkins Tarpaulin installation and execution while the job does not publish coverage artifacts; retain the local 90% release gate.

Acceptance: release packaging emits archive and binary checksums, and Jenkins can rebuild the same release commit with an earlier dist/ bundle or legacy SBOM intermediates still present; the locked dependency graph passes the configured audit and deny policies.

Post-milestone release publishing

  • Add a small release.sh wrapper that reads a Gitea token from a supplied file, keeps it out of process arguments, and delegates the tagged john-slop release to rust_realease with optional arguments such as --dry-run.

Acceptance: missing, unreadable, and empty token files fail before publication; the token reaches rust_realease through GITEA_TOKEN, never an argument; and the wrapper selects the root workspace package and binary artifact mode.

Release candidate 0.1.27-rc.1

  • Synchronize the workspace, internal dependencies, lockfiles, evaluation sign-off, changelog, and version badge at 0.1.27-rc.1; make the release wrapper mark hyphenated versions as prereleases.
  • Run the complete quality, audit, package, and wrapper-contract gates before creating the immutable annotated v0.1.27-rc.1 tag.

Acceptance: all package and binary versions report 0.1.27-rc.1; the release wrapper expects v0.1.27-rc.1 at the current checkout and passes --prerelease; all gates pass before the local tag is created for explicit push and publication.

Accepted on 2026-09-30 after formatting, Clippy, rustdoc, both feature matrices, RustSec and dependency-policy checks, workspace package assembly, exact binary version checks, and the RC wrapper contract passed. Coverage is 92.72%; all workspace packages, lockfiles, evaluation sign-off, changelog, and the generated badge agree on 0.1.27-rc.1.

Release candidate 0.1.27-rc.2

  • Replace the certificate-mismatched direct Gitea repository metadata with the TLS-valid /gitea proxy URL and synchronize the workspace at 0.1.27-rc.2 without moving the existing RC1 tag.
  • Verify the proxy Git and API endpoints, complete all release gates, align the local origin, and create annotated tag v0.1.27-rc.2.

Acceptance: Cargo metadata, release links, and local Git origin select the same TLS-valid proxy repository; all package, lockfile, sign-off, changelog, badge, and binary versions agree on 0.1.27-rc.2; release dry-run reaches the proxy destination; and RC1 remains immutable.

Accepted on 2026-09-30 after the proxy Git and public API endpoints returned the expected repository, formatting, Clippy, rustdoc, both feature matrices, RustSec, dependency policy, package assembly, exact binary versions, and 92.72% coverage passed. Cargo metadata, release links, and local origin now agree on the proxy endpoint; RC1 remains unchanged.

Release candidate 0.1.27-rc.3

  • Rename the root Cargo package, upstream repository slug, release bundle, runtime configuration directory, and user-facing documentation to the canonical john-slop spelling. Retain underscores only where Rust identifier syntax requires Cargo's code-level john_slop form.
  • Synchronize all release artifacts at 0.1.27-rc.3, run the complete quality and release gates, align local Git configuration with the renamed upstream, and create immutable annotated tag v0.1.27-rc.3.

Acceptance: every user-facing project, package, repository, configuration, and artifact name uses john-slop; remaining john_slop occurrences are required Rust identifiers or stable diagnostic namespaces; all gates pass and prior RC tags remain unchanged before RC3 is tagged.

Accepted on 2026-09-30: formatting, Clippy, all-feature and no-default-feature tests, documentation, RustSec, dependency policy, package assembly, exact binary versions, and 92.72% coverage passed. Cargo metadata and release artifacts use john-slop; required Rust crate identifiers and stable diagnostic namespaces retain underscores. The local origin is prepared for the renamed upstream, and the earlier RC tags remain unchanged.

Release candidate 0.1.27-rc.4

  • Make release.sh temporarily switch origin to the canonical HTTPS release repository, invoke rust_realease, and restore the SSH development origin after both successful and failed invocations.
  • Synchronize release artifacts at 0.1.27-rc.4, run the complete quality and release gates, and create immutable annotated tag v0.1.27-rc.4 without moving any earlier release-candidate tag.

Acceptance: an integration test observes the HTTPS origin during publication and the restored SSH origin afterward for zero and nonzero publisher exits; all gates pass, the release dry-run succeeds, and earlier RC tags remain unchanged.

Accepted on 2026-09-30: the release-wrapper integration test observed HTTPS during publication and SSH after both success and failure; formatting, Clippy, both feature test matrices, documentation, RustSec, dependency policy, package assembly, exact binary versions, and 92.72% clean coverage passed. Earlier RC tags remain unchanged before RC4 is tagged.

Release candidate 0.1.27-rc.5

  • Add cargo-binstall package metadata matching the versioned target archives produced by the release publisher.
  • Synchronize release artifacts at 0.1.27-rc.5, run the complete quality and release gates, and publish immutable prerelease v0.1.27-rc.5 without moving any earlier release-candidate tag.

Acceptance: Cargo exposes the requested pkg-url, pkg-fmt, and bin-dir templates; all release metadata and binary versions agree on 0.1.27-rc.5; the complete gates and release dry-run pass before RC5 is tagged and published.

Accepted on 2026-09-30: the exact cargo-binstall metadata contract, formatting, Clippy, both feature test matrices, documentation, MSRV, RustSec, dependency policy, package assembly, exact binary versions, and 92.72% clean coverage passed. Earlier RC tags remain unchanged before RC5 is tagged and published.

Release candidate 0.1.27-rc.6

  • Publish cargo-binstall .tgz archives alongside raw binaries and pin the wrapper argument contract in its integration test.
  • Synchronize and verify release artifacts at 0.1.27-rc.6, then publish immutable prerelease v0.1.27-rc.6 without moving earlier RC tags.

Acceptance: the publisher receives artifact format both; the release contains the target archives named by package.metadata.binstall; cargo-binstall installation verification passes; and all standard release gates remain green.

Accepted on 2026-09-30: the wrapper contract passes artifact format both and prerelease mode; formatting, Clippy, both feature test matrices, documentation, MSRV, RustSec, dependency policy, package assembly, exact binary versions, and 92.72% clean coverage passed. Earlier RC tags remain unchanged before RC6 is tagged and published.

Release candidate 0.1.27-rc.7

  • Replace release-time Git origin mutation with the publisher's project-local repository fallback mapping and retain the SSH development remote unchanged.
  • Synchronize and verify release artifacts at 0.1.27-rc.7, then create and push immutable prerelease tag v0.1.27-rc.7 without moving earlier RC tags.

Acceptance: the publisher inspection resolves the RC7 package and tag through the fallback-aware project configuration; the integration test observes the SSH origin during successful and failed publisher invocations; and all standard release gates remain green.

Accepted on 2026-09-30: formatting, Clippy, both feature test matrices, documentation, RustSec, dependency policy, workspace package assembly, exact binary versions, publisher inspection, and 92.72% clean coverage passed. All workspace metadata, lockfiles, evaluation sign-off, changelog, and the generated version badge agree on 0.1.27-rc.7; earlier RC tags remain unchanged.

Deferred by design

  • Statistical or model-based authorship classification.
  • Automatic prose or source-code rewriting beyond configured ASCII replacements.
  • Locale-aware confusable policy beyond the pinned review profile. Broader locale selection still requires product validation; detection remains separate from automatic replacement.
  • In-place modification of archive members or office documents.
  • Network-backed analysis or telemetry.
  • Editor-specific extensions; the LSP is the integration boundary.
  • Runtime-defined matcher algorithms, arbitrary new diagnostic categories, and executable/script/plugin rules. TOML catalogs may select only the validated built-in data-driven matchers; expanding executable behavior needs a separate trust, sandboxing, compatibility, and performance design.

These are not implied follow-ups. Each requires a separate privacy, safety, performance, and product-design review before entering the active milestones.