# AIFQ Site Review internals

v1.11 introduces explicit seams in the former monolithic plugin class while preserving the stable v1.10.2 product behavior.

Current boundaries:

- `AIFQ_SR_Site_Collector` — reads current WordPress/site facts; no evaluation or persistence.
- `AIFQ_SR_Evaluation_Pipeline` — preserves the checks → extension filter → finalization sequence.
- `AIFQ_SR_Review_Repository` — owns existing review/reviewed-state persistence only; this is not Evidence Memory.
- `AIFQ_SR_Review_Normalizer` — read compatibility for old/current saved review records; old title-derived identity is resolved here without rewriting historic storage.
- `AIFQ_SR_Reviewed_Findings_Service` — application logic for the existing reviewed-state feature; presentation remains read-only. Automatic State 4 / severity resurfacing is disabled in v1.12 unless a future key receives an explicit revisit contract.
- `AIFQ_SR_Finding_Catalog` — stable built-in finding/check identity plus canonical `setup`, `security`, `reliability`, `performance` category mapping. New built-in records use explicit keys; title mapping is legacy-read compatibility only.
- `AIFQ_SR_Copy_Builder` — builds the copyable review summary and developer/host handoff text.
- `AIFQ_SR_Snapshot_Builder` — builds the small canonical state anchor for future Evidence comparison. It deliberately does not persist the full Site Collector output.
  In v1.11, plugin/theme existence and version state remain grounded directly in the local filesystem rather than WordPress metadata caches. Filesystem read failure now invalidates the Evidence snapshot instead of being interpreted as absence/removal; the last trustworthy anchor is preserved.
  The scheme-independent site identity remains unchanged so HTTPS termination differences between browser, cron and WP-CLI cannot create a false foreign-site boundary; legacy v1 HTTP/HTTPS identities remain accepted during migration.
- `AIFQ_SR_Memory_Schema` — owns per-site Memory schema version, history boundary and the two local custom tables.
- `AIFQ_SR_Evidence_Repository` — append-only Evidence/relation persistence, Evidence shape validation, bounded FIFO retention and relation integrity.
- `AIFQ_SR_Memory_Identity` — canonical state serialization plus idempotency/identifier helpers.
- `AIFQ_SR_Memory_Manager` — fail-soft initialization of a trustworthy first snapshot/history boundary; it never backfills historic review records.
- `AIFQ_SR_Observed_Event_Recorder` — whitelisted WordPress lifecycle hooks → immutable Observed Evidence. Exact entities stay exact; generic upgrader operations never infer a target.
  For plugin/theme updates, `post_update_version_verified=true` is only set after reading the target version directly from the updated file on disk.
- `AIFQ_SR_Snapshot_Differ` — compares two canonical state anchors and emits concrete Detected transitions with an interval, never an invented event timestamp.
- `AIFQ_SR_Evidence_Correlator` — applies the frozen uniqueness/entity/transition rules to create `exact_match` or `generic_operation_context` relations conservatively.
- `AIFQ_SR_Memory_Processor` — after a successful Site Review, persists Detected Evidence, correlates it and advances the comparison anchor fail-soft.

Compatibility rules in v1.11:

- Existing `aifq_sr_last_scan`, `aifq_sr_previous_scan` and `aifq_sr_reviewed_findings` storage remain valid and separate from Evidence Memory.
- Old saved findings without `key`/`category_id` are normalized when read; they are not destructively migrated.
- New built-in findings, suggestions and passed checks persist explicit keys and canonical category IDs.
- Display titles remain presentation copy and must not define new finding identity.
- Memory starts at the first trustworthy v1.11 snapshot. Old reviews are not converted to Evidence.
- Memory storage is site-scoped (`$wpdb->prefix`) and bounded to 250 technical Evidence records.
- Deactivation preserves Memory; uninstall removes AIFQ-owned Memory storage.
- Optional Memory failures must not break the established current Review/Evaluation path.

Not included in v1.11:

- Evidence-driven `Since your last review` presentation.
- Decision Memory.
- Timeline/activity-log UI (intentionally out of scope).

## v1.12 Decision Memory dev.1–dev.2

- `AIFQ_SR_Decision_Memory_Schema` owns two per-site Decision Memory tables independently of bounded Evidence retention.
- `AIFQ_SR_Decision_Repository` is append-only. It exposes no decision update API and derives the current chain head without mutating an `is_current` flag.
- `AIFQ_SR_Decision_Memory_Service` validates the frozen five-type taxonomy, current/eligible finding identity, stale expected-decision IDs, immutable supersession and explicit reconfirmation.
- Explicit review/edit intent always creates a new superseding decision occurrence; free-text note comparison never decides lifecycle semantics.
- The decision row snapshots the registry `decision_contract` version used when the human decision was recorded.
- Root/successor predecessor guards are unique so concurrent requests cannot create two valid chain branches from one predecessor.
- Decision Memory is initialized and uninstalled separately from Evidence. Missing tables self-heal on a later ensure/write attempt; failure remains fail-soft for normal Site Review.
- v1.12 intentionally has no automatic Decision-Memory revisit-eligible finding keys yet. dev.2 adds the first Decision Memory capture UI without adding State-4 or confirmation UI.
- Decision-eligible attention findings and eligible `Worth reviewing` suggestions can enter the same explicit Decision picker.
- Successful Decision capture marks the finding reviewed only after the immutable write succeeds. A lightweight `decision_managed` marker remains in reviewed-state storage as compatibility/context metadata; Decision content stays exclusively in Decision Memory.
- Active findings with an existing current Decision show prior Decision context and use explicit immutable supersession when `Review decision` is submitted.
- Legacy/non-Decision reviewed findings preserve the established one-click review behaviour, but v1.12 does not automatically resurface them on severity changes. Natural reappearance or manual reactivation may show prior Decision context without a `Relevant again` claim.

## v1.12 Decision Memory dev.3

- `AIFQ_SR_Research_Store` is a bounded, local-only internal research-event/session store. It records narrow AIFQ product interactions required for Gate B and explicitly rejects raw Decision note content, visitor IPs, user agents and external telemetry.
- `AIFQ_SR_Research_Diagnostics` provides read-only Registry / Evidence / Decision chain diagnostics for internal development builds.
- The internal Research Console is development-gated and administrator-only; a clean research session must be started explicitly.
- Review sequence, not calendar week, drives Gate B return classification. A controlled reminder can be marked exactly after Review 1 and before Review 2; the store rejects early, duplicate or late markers so later organic reviews cannot be mislabeled as prompted.
- Reviewed Decision-backed findings expose a direct `Review decision` route. This produces immutable supersession without requiring `Show as active again` and without altering Current State truth.
- `AIFQ_SR_Site_Collector::collect_cache_signals()` is a lightweight diagnostic seam for local cache facts. Server/edge cache is deliberately reported as unknown until AIFQ has a trustworthy external/integration source.