john-slop/tasks.md

880 lines
49 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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:
```text
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
- [x] Capture current behavior with tests before moving code: plain file,
recursive directory, ZIP member, invalid UTF-8, missing path, and basic Unicode
matching.
- [x] Fix the misleading Unicode tests/comments (UTF-8 byte lengths and grapheme
terminology) so test names reflect what is actually asserted.
- [x] 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.
- [x] Define supported inputs and limits: extensions/MIME policy, maximum file
bytes, archive bytes, expanded bytes, entry count, nesting, hidden files,
symlinks, and ignore rules.
- [x] Establish an MSRV in `Cargo.toml` and CI, add license/repository metadata,
and document supported platforms.
- [x] 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
- [x] Add `src/lib.rs` and expose a small facade for loading config, analyzing a
source, planning replacements, and reading inputs.
- [x] Replace demo functions and ad hoc errors in `main.rs` with typed domain
values (`SourceId`, `Finding`, `Analysis`, `Confidence`, `TextEdit`).
- [x] 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`.
- [x] Preserve outer and inner archive identities. Prevent path traversal and
decompression bombs using the limits from Milestone 0.
- [x] Centralize error enums with `thiserror`; add `miette` context only at
presentation boundaries. Remove placeholder `try_report` and sample reports.
- [x] 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.
- [x] 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
- [x] Update the declared Rust toolchain and direct dependencies to their latest
stable releases; verify the locked graph with the declared toolchain.
- [x] Add focused behavioral and snapshot tests, including feature-matrix
coverage, without snapshotting structured domain values unnecessarily.
- [x] Configure Tarpaulin with an enforceable coverage floor around 30%, run
`rust_autobadges`, and publish local version/test/coverage badges.
- [x] 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
- [x] Add Serde, `figment` with TOML support, and a platform-aware configuration
directory crate such as `directories`.
- [x] Create `assets/config.toml` as the embedded replacement catalog with
`schema_version` and documented examples.
- [x] Create `assets/heuristics.toml` as a separate embedded rule catalog with
stable IDs, categories, matcher types, weights, messages, help, occurrence caps,
and applicability scopes.
- [x] Implement exact precedence: embedded defaults < user `config.toml` < named
user `<config_name>.toml` < explicit `--config` < explicit CLI flags.
- [x] Validate config names and refuse traversal, extensions, empty names, and
non-ASCII characters. Resolve the user path with platform APIs.
- [x] Implement merge-by-ID for rule/replacement tables rather than allowing
positional array replacement to produce surprising partial configuration.
- [x] 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.
- [x] Preserve enough provider metadata to identify the offending file and key in
a `miette` configuration diagnostic.
- [x] Add `john-slop config show` and `john-slop config paths` so precedence is
inspectable; output deterministic TOML or JSON.
- [x] 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
- [x] Define a `Rule`/`Detector` interface and a registry built entirely from the
validated heuristic config. Compile reusable matchers once.
- [x] Implement exact phrase and regex rules with precise byte spans, match text,
category, weight, message, help, and stable rule ID.
- [x] 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.
- [x] Add applicability filters for prose versus source code, extension/language,
include/exclude globs, and generated/vendor/minified paths.
- [x] Design the confidence formula: bounded weighted evidence, per-rule caps,
correlated-family damping, normalization to `0..=100`, and configurable
low/medium/high thresholds.
- [x] Return zero confidence and no verdict for empty/no-evidence input. Keep
unsupported/binary input distinct from a clean analysis.
- [x] Sort findings deterministically and deduplicate identical rule/span pairs.
- [x] 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.
- [x] 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.
- [x] 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
- [x] Convert each `Finding` into a typed `miette::Diagnostic` with named source,
exact `SourceSpan`, severity, rule ID as diagnostic code, message, and help.
- [x] Add a summary that reports confidence band/score and counts by severity,
while retaining every contributing diagnostic.
- [x] Build detector CLI inputs for file, directory, and stdin (`--stdin-filename`
for language/path scoping); add ignore and maximum-size controls.
- [x] Add human, concise, and versioned JSON output modes. Ensure JSON and stdout
diagnostics never contain logs or ANSI escapes.
- [x] Implement documented exit codes: `0` below fail threshold, `1` at/above it,
`2` for usage/configuration/I/O failure. Add `--fail-level`.
- [x] Report per-document input errors without hiding findings from other
documents; define whether partial failure returns `2` and test it.
- [x] 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
- [x] Parse replacement definitions into a trie or deterministic longest-match
planner and emit validated, non-overlapping `TextEdit`s against the original
source.
- [x] Apply edits from highest to lowest byte offset. Preserve line endings and
return the original buffer unchanged when there are no edits.
- [x] Reject non-character-boundary and overlapping edits as typed invariant
errors. Define deterministic behavior when sources share prefixes.
- [x] Implement `john-slop-fmt` stdin/stdout mode, `--check`, `--diff`, and
explicit `--write`. Require an explicit policy for recursive directory writes.
- [x] Make writes atomic with a same-directory temporary file plus rename when
supported; retain permissions and never rewrite on analysis/config failure.
- [x] Do not rewrite ZIP/DOCX/XLSX/PPTX members in this milestone; emit a clear
unsupported-operation diagnostic.
- [x] Add unit/property tests for idempotence, Unicode boundaries, longest match,
non-overlap, stable output, line endings, empty input, and no-op byte identity.
- [x] 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
- [x] 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.
- [x] Implement stdio initialization/shutdown and incremental or full document
synchronization with URI, version, language ID, and current text tracked per
open document.
- [x] Build and thoroughly test byte-offset to LSP UTF-16 line/character mapping,
including CRLF, emoji, combining marks, astral characters, and EOF positions.
- [x] Publish diagnostics only for configured ASCII-replacement findings in the
initial release. Include stable codes and source `john-slop`.
- [x] Expose quick fixes/code actions using the exact edits from the shared
replacement engine; reject stale-version requests.
- [x] Recompute after open/change/configuration updates, clear on close, and avoid
publishing obsolete results when analysis overlaps newer edits.
- [x] Keep all protocol bytes on stdout and diagnostics/logging on stderr. Add
opt-in structured logging without document contents.
- [x] 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
- [x] 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.
- [x] Publish commented sample base and named configs. Document how to disable a
rule/replacement and how merge-by-ID works.
- [x] Add CI on the supported OS/MSRV matrix for formatting, Clippy, tests, docs,
audit/deny checks, and fixture/golden consistency.
- [x] 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.
- [x] Benchmark large files, many small files, rule scaling, and archive limits.
Add parallelism only if measurement shows a benefit and output remains ordered.
- [x] Review dependency features, licenses, advisories, unsafe code, and release
binary size. Generate checksums if releases distribute binaries.
- [x] Add changelog, contribution guide, code of conduct, security reporting
instructions, release profile, and reproducible release procedure.
- [x] 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
- [x] Cover configuration merging, validation failures, domain formatting, and
diagnostic accessors with behavior-focused unit tests.
- [x] Cover archive and input resource-policy branches with generated fixtures,
including unsafe, binary, malformed, and oversized members.
- [x] Cover remaining practical CLI, formatter, and LSP adapter branches without
coupling tests to unreachable platform failures or coverage-tool artifacts.
- [x] 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
- [x] 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
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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
- [x] 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
- [x] 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
- [x] 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
- [x] 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
- [x] 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
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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.
- [x] Ignore legacy per-package `cargo cyclonedx` intermediates left by earlier
builds so workspace packaging remains clean after SBOM generation is removed.
- [x] 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
- [x] 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
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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
- [x] 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.
- [x] 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
- [x] Add `cargo-binstall` package metadata matching the versioned target
archives produced by the release publisher.
- [x] 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
- [x] Publish cargo-binstall `.tgz` archives alongside raw binaries and pin the
wrapper argument contract in its integration test.
- [x] 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
- [x] Replace release-time Git origin mutation with the publisher's project-local
repository fallback mapping and retain the SSH development remote unchanged.
- [x] 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.