38 KiB
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.tomland CI, add license/repository metadata, and document supported platforms. - Move
tempfileand other test-only crates to[dev-dependencies]; removerayon,once_cell, orunicode-segmentationif 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.rsand expose a small facade for loading config, analyzing a source, planning replacements, and reading inputs. - Replace demo functions and ad hoc errors in
main.rswith typed domain values (SourceId,Finding,Analysis,Confidence,TextEdit). - Split
reader.rsintoinput/file.rs,input/walk.rs, andinput/archive.rs; yield oneResult<Document, InputError>at a time rather than loading a directory into aVec. - Preserve outer and inner archive identities. Prevent path traversal and decompression bombs using the limits from Milestone 0.
- Centralize error enums with
thiserror; addmiettecontext only at presentation boundaries. Remove placeholdertry_reportand sample reports. - Add explicit
[[bin]]targets forjohn-slop,john-slop-fmt, andjohn-slop-lsp; the latter two may initially call stub adapters but all three must compile. - Keep binary parsing/orchestration out of the library. Add
clapwith 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,
figmentwith TOML support, and a platform-aware configuration directory crate such asdirectories. - Create
assets/config.tomlas the embedded replacement catalog withschema_versionand documented examples. - Create
assets/heuristics.tomlas 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
mietteconfiguration diagnostic. - Add
john-slop config showandjohn-slop config pathsso 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/Detectorinterface 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
Findinginto a typedmiette::Diagnosticwith named source, exactSourceSpan, 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-filenamefor 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:
0below fail threshold,1at/above it,2for usage/configuration/I/O failure. Add--fail-level. - Report per-document input errors without hiding findings from other
documents; define whether partial failure returns
2and 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-fmtstdin/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
--checkexit 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 an SBOM/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 preserving0.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, andEvidenceThresholds; retain deprecated Rust type aliases and the legacy--fail-confidenceCLI alias for migration. - Publish the low-care evidence-score wording across terminal output,
examples, and documentation; rename
--fail-confidenceto--fail-scoreand 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-coreworkspace crate and the protocol engine into ajohn-slop-lspworkspace 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_slopcompatibility 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 version0.1.Nbefore 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/formattingin the LSP using the same resolved configuration and core replacement planner asjohn-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|falsefor 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 initto 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.tomlbefore 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.tomlstarter 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.
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.