Adds a generic ErrorContextAnalyser under
src/Analyser/ProjectZomboid/ that walks Entry[] and emits one
ErrorContextProblem per ERROR or WARNING entry with up to 20
entries of before/after context. Overlapping windows clip so no
Entry appears in two context arrays; emission caps at 500 hits
with an ErrorContextTruncatedInformation note when reached.
pz_redact_all.sh is the one-shot Docker wrapper that runs the PHP
ProjectZomboidRedactor over .scratch/pz/Logs/ and produces the
gitignored .scratch/pz/Logs.redacted/ directory consumed by both
the Qwen analyser and the deterministic classifier.
pz_error_analysis.py is the developer-facing Qwen-backed log
analyser: walks the redacted directory, dedupes signatures, and
asks the local sam-desktop Qwen endpoint to classify each unique
shape into a fixed taxonomy with title / cause / fix / confidence.
Runtime depends on the Qwen endpoint; the deterministic classifier
at pz_classify.py is the production-bound counterpart.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a fourth pass to ProjectZomboidRedactor that scrubs IPv4
(strict 0-255 octets, optional :port suffix) and IPv6 (full,
abbreviated, bracketed-with-port, IPv4-mapped) addresses, replacing
them with the literal [REDACTED_IP]. The new pass runs first
because it is pattern-disjoint from the Steam-ID -> name -> coords
chain. A single redactIpAddresses(bool) toggle controls both
families; the existing toggles are unchanged. Strict regexes plus
filter_var() validation prevent false positives on PZ timestamps
(12:00:00.000) and PHP/Java scope ops (Foo::bar). 20 new tests
cover bare/with-port/multiple/loopback/boundary IPv4, full /
abbreviated / bracketed / IPv4-mapped IPv6, scope-op rejection,
timestamp rejection, Steam-ID non-collision, toggle-off, and
idempotence.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures iblogs as primary codex consumer with the call-site checklist
for cross-repo public-API changes; spells out the semver / changelog
cadence; documents the <feature>-bootstrap branch + --no-ff merge
pattern set by the redactor and iblogs-bootstrap branches; pins the
specs/plans path convention from the superpowers skills.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds a deterministic-only Project Zomboid log classifier under
tools/pz-analyzer/, parallel to the existing Qwen-based research
tool. pz_parser.py is a pure module (parsing, attribution, file:line,
cause-chain, kind detection, two-level signatures); pz_classify.py
walks the redacted DebugLog-server directory, merges cross-file by
signature, and writes the spec-shaped JSON. 32 unit tests.
Constant was already imported by pz_classify; this just formalises
it as part of the public surface so __all__ matches actual usage.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Was leaking unhandled OSError tracebacks when the output's parent
path could not be created. Exit code stays 1; user-facing message
matches the existing write-failure path.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walks DebugLog-server*.txt under the redacted directory, runs the
parser per file, merges cross-file by signature, and emits the
spec-shaped JSON report.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Honest test docstring (old/new semantics equivalent on contiguous
entries; test locks post-fix behavior against future regressions),
and add severity-prefix strip to the spec's normalization list.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Strip body-prefix severity in normalize_first_line so pattern_id
is stable across body-prefix vs bracketed-only variants.
- Lookback for inferred attribution now counts raw file lines
(per spec literal), not body-line budget across entries.
- Document hash truncation (64-bit) and direct-attribution priority.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Walks Entry[] once and emits one ErrorContextProblem per ERROR or
WARNING entry, attaching up to 20 entries before and 20 after as
context. Overlapping windows clip the second hit's before- and
after-ranges so no Entry appears in two context arrays. Caps emission
at 500 hits and adds an ErrorContextTruncatedInformation when reached.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Redactor introduces a new public API surface (RedactorInterface
plus per-game implementation), which under semver is a minor version
bump, not a patch. Correcting the changelog before the v0.1.1 tag is
re-pointed at v0.2.0 in a follow-up step.
Convert [Unreleased] section to [0.1.1] dated 2026-05-01. Records what
landed via the redactor branch merge: the RedactorInterface plus
ProjectZomboidRedactor, the 65 new tests across six files, and the
spec/plan documentation refresh. Adds a fresh empty [Unreleased]
section above for future work, plus a [0.1.1] link reference.
Implements the codex Redactor utility per
docs/superpowers/specs/2026-04-30-redactor-design.md and
docs/superpowers/plans/2026-05-01-redactor.md. Adds RedactorInterface
plus ProjectZomboidRedactor with three toggleable redaction passes
(Steam IDs, player names, world coordinates) under a new src/Util/
top-level directory. 65 new tests across five files; full suite
255 -> 260 green; zero deprecations or warnings under PHP 8.5.
Documented v1 limitations carried forward: in PvP, only the attacker's
name and coords are redacted (victim, after `hit`, deferred to v2). In
admin teleport lines, ` to <coords>` form is not redacted (the at-clause
regex anchors on ` at `).
Resolves observation #3 from the final code review. The integration
tests previously asserted Steam-ID elimination, structural
preservation, and idempotence but did not directly verify that
synthetic player names collapse to <player> after redaction.
Adds testFixturePlayerNamesCollapseInCoveredContexts, parameterised
over the five fixtures (chat, cmd, item, map, user) where every
synthetic name appears exclusively in a context the redactor
recognises (ChatMessage author or Steam-ID-followed-by-quoted-name).
The data provider docblock explicitly enumerates which fixtures are
excluded and why — admin and client-action/perk because names appear
in unanchored or bracket-only contexts; pvp because the victim name
after `hit` is a v1 limitation; burd-journals/debug-server because no
synthetic player names are present.
Test count: 255 -> 260 (5 new effective cases from data-provider).
The spec doc was written when the Redactor was deferred and shipped
with a "Status: deferred — not implemented" header. The redactor
branch lands the implementation; the header is now stale. Replace with
a pointer to the plan and CHANGELOG [Unreleased] section.
Resolves observation #1 from the final code review.
CLAUDE.md: added RedactorInterface bullet to the architecture list
(after Custom Analyser subclasses, before Detectors); added
ProjectZomboidRedactor entry under ProjectZomboid specifics; added
src/Util/ to the game-subtrees layout code block with a prose note
marking it as the sixth component directory introduced post-v0.1.0;
added Pitfall 5 on mandatory pass order.
README.md: new "Redaction" subsection between Quick start and
Architecture — PHP snippet, replacement descriptions, three toggle
methods, three documented v1 limitations.
CHANGELOG.md: added [Unreleased] section (Added + Changed) above
[0.1.0]. Removed the Redactor bullet from [0.1.0]'s Deferred list
entirely — the historical record stays accurate (v0.1.0 shipped
without it) and [Unreleased] now documents its arrival; a stub mention
in Deferred would be redundant.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds three COORDS_*_REGEX constants (at-clause, bracketed, parenthesised)
plus COORDS_REPLACEMENT, wires them into redact(), and covers all three
contexts with 8 new tests including a critical negative test asserting
DebugLog-server.txt server-metadata triples are not redacted.
Also updates two Task 3 player-name tests whose expected strings now
include the coords redaction that the wired pass applies.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds three lexical-context regexes (after-SteamID, ChatMessage author,
Combat/Safety pvp subsystem) and wires the player-name branch in redact().
Includes six PHPUnit tests covering all three contexts plus the toggle-off
and no-anchor-no-touch cases.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Forward-looking plan on the redactor branch covering all eight design
questions called out in the careful-protocol kickoff: render-time
filter (raw is canonical), standalone string utility (not a Printer
decorator), regex-based detection with lexical anchors per PII
category, per-category placeholder replacement matching synthetic
fixture conventions, thin generic interface plus per-game
implementation under src/Util/ProjectZomboid/, hybrid fixture strategy
(unit-level synthetic plus integration against existing PZ fixtures).
Branch off master aec835e. backup/pre-redactor tag pins start.
No code is written by this commit. Implementation pass kicks off
separately after plan review.
Phase B.1 registers 4 Insight classes (EngineVersion, ModLoad,
ModMissingProblem, ServerExceptionProblem) on PatternAnalyser; Phase
B.2 adds 7 (PvpDamage + 6 Admin verbs). Total: 11. Phase B.3's three
Problem classes are emitted by custom Analyser subclasses, not
registered with PatternAnalyser, so they don't belong in this count.
Step-3 deliverable from the #careful run. Captures the fork target
verification (mclogs MIT-licensed, active, PHP 8.5 floor, MongoDB
storage, already integrates Aternos's codex stack), the Composer dep
plan (indifferentketchup/codex via Gitea VCS pinned to v0.1.0), the
multi-file/session model decision (option iii — session-as-entity
wrapping N files, with mclogs single-pastes degenerating to
sessions-of-size-1), the UI changes (file-type tabs, redaction
toggle gated on Step 4), the API surface (session-aware new endpoints
plus legacy /api/1/log routes preserved for back-compat), a directional
string/branding inventory at file-level (line-precise inventory
deferred until the fork is cloned and grep-able), the migration
strategy (keep legacy routes, strip aternos/codex-* and Sherlock and
Aternos\Mclogs namespace), and open questions including the codex
Redactor decision deferred to Step 4.
No iblogs code is written by this commit. The fork, rename, and rewire
happen in a follow-up session after design approval.
Keep-a-Changelog format, dated 2026-05-01, sections Added / Changed /
Deferred. Captures the framework rename to IndifferentKetchup\Codex\*
(Aternos namespace fully removed in 66a2fcc, MIT LICENSE preserves
original copyright), the components-outer-with-game-suffix layout
(option 1 from the Phase A Q3 decision, not option 3), the package
name indifferentketchup/codex, and the eight analysers shipped across
Phase B.1 / B.2 / B.3. Redactor utility, non-PZ games, and Packagist
publication land in Deferred.
Forward-looking design for the codex-side PII redactor utility flagged
in Phase A Step E (Q5) and explicitly deferred from Phase B. Captures
the per-game redactor shape (RedactorInterface plus
ProjectZomboidRedactor under src/Util/), the rationale for not using
a single generic regex utility (PII detection is context-sensitive),
the replacement conventions that match the synthetic fixture
placeholders, the regex anchor shapes, and the open questions for v1
vs v2.
Status: deferred. Not implemented in this commit. The spec exists so
iblogs's upload-time PII story has a referenced design to point at,
and so a future implementation pass has a clear contract to start
from.
Retroactive design + plan documentation for Phase B.3 (deferred
analysers requiring custom Analyser subclasses for cross-entry and
threshold logic). Records the architectural shift away from vanilla
PatternAnalyser, the threshold constant rationale (event-pairing /
sliding-window / consecutive-snapshot deltas), and the synthetic
fixture extensions that exercise both trigger and non-trigger paths.
Plan is as-built with checkboxes pre-checked and SHAs referenced.
Retroactive design + plan documentation for Phase B.2 (PvP combat
detection plus six admin verb-dispatch insight classes), reconstructed
from chat history and git log. Mirrors the shape of the existing
Phase B.1 docs. Plan is as-built with checkboxes pre-checked and
commit SHAs referenced inline; Deviations section captures the
90c85a0 brace-fix interlude.
Replaces the four-line stub with a usable landing page: install line,
end-to-end PHP example showing how a caller goes from a log file to
analysed insights, sample (placeholder-laden) output, a one-diagram
architecture summary, and a per-game support table. Sends interested
readers to CLAUDE.md for the extension guide and developer setup so
this file stays focused on consumers.
The example uses Project Zomboid because that is the in-tree reference
implementation. Output is illustrated with placeholder identifiers
(<hash>, <mod_id>, <missing>) rather than copied real-log content.
The framework architecture section claimed PatternAnalyser was the
sole analysis surface; Phase B.3 introduced three custom Analyser
subclasses (ConnectionFailureAnalyser, ItemDuplicationAnalyser,
SkillProgressionAnomalyAnalyser) for cross-entry and threshold logic
that PatternAnalyser cannot express. Add a new bullet explaining when
to extend Analyser directly, plus an enumeration of which Log subclass
returns which kind of analyser from getDefaultAnalyser().
Also bumps the ProjectZomboid summary line from "11 log subclasses,
11 pattern classes" to include the analyser surface (12 Insight
classes plus 3 Analyser subclasses).
GitHub deprecated the ::set-output workflow command in 2022 and the
runners now emit warnings on every CI run. Switch to writing the
'name=value' line into the file pointed to by \$GITHUB_OUTPUT, which is
the documented modern equivalent. The downstream cache step already
references steps.composer-cache.outputs.dir, no other change needed.
Compares consecutive perks-snapshot rows per Steam ID and emits a
SkillProgressionAnomalyProblem for any single skill whose level gained
more than THRESHOLD_DELTA between two snapshots. Login/Logout/LevelUp
event rows are skipped via a perk-pair regex check on the bracketed
event field.
Threshold of 3 reflects PZ's slow leveling pace: typical session bridges
should not produce four-or-more level jumps in a single skill. The
constant is documented inline so operators can tune for modded XP
servers without touching analysis logic.
Synthetic fixture extended with a PlayerSuspect Steam ID carrying two
snapshots: Strength jumps 2 -> 10 (delta +8, triggers), Fitness jumps
2 -> 8 (+6, triggers), Maintenance jumps 0 -> 3 (+3, exactly at
threshold, does NOT trigger). The existing single-snapshot players
remain noise-free.
Sliding-window heuristic over (Steam ID, item code) groups: any window of
THRESHOLD_WINDOW_SECONDS containing THRESHOLD_COUNT or more positive-delta
events for the same player/item pair triggers a Problem. Negative deltas
(drops, transfers out) are filtered. Five events in ten seconds (defaults)
encodes the rule of thumb that legitimate gameplay rarely produces five
identical items in that span.
Constants live as class constants on the analyser so operators can
override via subclass without touching analysis logic; the docblocks
record the justification.
Synthetic fixture extended with a 6-event burst (AdminUser +
Base.Bullets9mm in <1s) and a 4-event sub-threshold group (Player1 +
Base.Plank scattered over 4 minutes) to exercise both paths.
First custom Analyser subclass in this game tree. PatternAnalyser
operates per-entry without cross-entry state, so pairing
'attempting to join' with 'allowed to join' per Steam ID requires a
bespoke pass over the log. The analyser counts attempts and allowed
events per Steam ID and emits a ConnectionFailureProblem for each
player whose attempt count exceeds their allowed count. Unmatched
'attempting to join used queue' rows are surfaced as failures in v1
because a long queue wait is indistinguishable from a real failure
without timing context.
The previous commit's Edit replaced the TELEPORTED constant including its
trailing closing brace and forgot to add the brace back. Tests went red
with a ParseError. Restoring the brace.
