docs: lean-out plan + verified safety audit (council Phase C, advisory only)

[Gradata]

Advisory PR — no code deletions yet. This branch carries:

• LEANOUT_PLAN.md (claude-opus-4-7's audit, raw)
• VERIFIED_LEANOUT.md (corrects 8/14 unsafe deletion calls after grep verification)

Key finding: Council's structural critique was correct (kernel works, surface bloated 11x vs Mem0). But specific delete recommendations were heuristic — verification revealed:

• _cloud_sync.py NOT dead (tests + doctor + migration use it)
• scoring/memory_extraction.py NOT broken (brain.py + dedicated test)
• daemon.py KEEP (Phase B just wired BrainLockedError into it)
• notifications.py PUBLIC API (exports Notification)
• onboard.py used by Brain.init() README headline
• safety.py used for PII redaction

Confirmed safe-to-delete: graduation/scoring.py (0 imports verified).
Confirmed safe-to-rename-with-deprecation-alias: events_bus.py, _config.py.

Don't merge this PR yet. Treat as decision document for the next round.

Branches off Phase B (PR #145).

[greptile-apps]

Too many files changed for review. (253 files found, 100 file limit)

[coderabbitai]

📝 Walkthrough

• New public APIs:

  • cloud_sync_tick(brain_dir, session_number) — hook-safe cloud telemetry sync.
  • diagnose(brain_dir, include_cloud: bool = True, cloud_only: bool = False) — adds cloud diagnostic flags (signature changed).
  • Transcript APIs: log_turn(...), load_turns(...), cleanup_ttl(...) and get_transcript_source(...) (Claude or Gradata-native).
  • synthesize_rules_block(...) and call_provider(...) — new rules synthesis + caching with multi-provider LLM support.
  • CLI: cmd_skill_export / cmd_skill — exports graduated rules as Claude Skills.

• Breaking changes / behavioral shifts:

  • diagnose() signature extended to include include_cloud and cloud_only flags — callers must pass or accept new params.
  • Meta-rule synthesis moved from cloud-only to local SDK (local LLM fallback); synthesis behavior and storage changed.
  • implicit_feedback hook contract hardened to emit-only (Phase B noted).

• Security / data safety:

  • PII redaction added for events (emails redacted in persisted event data); unredacted payloads written to a best-effort side-log events.raw.jsonl (failures are non-fatal and logged).
  • Cloud sync adds JSONB sanitization, deterministic row UUIDs, deduplication, and safer error classification for constraint violations.

• Data/migrations:

  • New Supabase migrations: de-duplication + UNIQUE constraints for corrections/events; brains.last_used_at column.
  • New local migrations: event identity (ULID, device_id, content_hash), sync_state table, device/tenant UUID utilities.

• Observability and robustness:

  • Widespread addition of logging: previously swallowed exceptions now emit debug/warning logs across many modules.
  • Doctor gained cloud probes (TCP/auth checks, cloud_push_error surfacing) and new CLI flags (--cloud / --no-cloud).

• Lean-out audit docs:

  • LEANOUT_PLAN.md (Phase C plan) and VERIFIED_LEANOUT.md (verification run) recorded; verification corrected 8/14 unsafe deletion recommendations and flagged multiple modules as unsafe-to-delete (e.g., _cloud_sync.py, memory_extraction.py, notifications.py, daemon.py, onboard.py, safety.py); graduation/scoring.py was confirmed import-blocked by tests.

• Notable confirmations / safe ops:

  • graduation/scoring.py deletion attempt failed due to test import (tests matter for deletion safety).
  • Some files marked for safe rename-with-deprecation alias (events_bus.py, _config.py) rather than immediate deletion.

Walkthrough

Local-first learning loop implemented: meta-rule synthesis and graduation moved to the SDK; added cloud sync plumbing, SQLite and Supabase migrations, transcript logging, broad logging of previously-suppressed exceptions, CLI skill export and cloud-aware diagnostics, and many doc/formatting updates.

Changes

Cohort / File(s)	Summary
Docs & Governance Gradata/AGENTS.md, Gradata/CHANGELOG.md, Gradata/LEANOUT_PLAN.md, Gradata/VERIFIED_LEANOUT.md, Gradata/docs/*, Gradata/.gitignore	New agent guidance, lean‑out plans, changelog entries, cloud‑sync spec, and multiple architecture doc edits shifting responsibilities to local SDK; added/expanded .gitignore entries.
Cloud Sync & Client Gradata/src/gradata/_cloud_sync.py, Gradata/src/gradata/cloud/client.py, Gradata/src/gradata/cloud/sync.py, Gradata/src/gradata/_doctor.py	Deterministic cloud IDs, payload shaping/scrubbing, deduplication, remapped tables, improved error classification and reporting; client base URL/path updates and cloud-aware doctor probes.
Migrations & Identity Gradata/migrations/supabase/*, Gradata/src/gradata/_migrations/* (including _ulid.py, device_uuid.py, 002_add_event_identity.py, 003_add_sync_state.py)	Supabase UNIQUE constraint migrations; new SQLite migrations for event identity, sync_state, tenant/device persistence; ULID generator and device/tenant ID utilities; migration README.
Local Graduation & Meta‑rules Gradata/src/gradata/enhancements/meta_rules.py, Gradata/src/gradata/enhancements/rule_pipeline.py, Gradata/src/gradata/enhancements/graduation/*	Local clustering and deterministic meta‑rule synthesis implemented (LLM-backed when creds present); pipeline refactors to use local graduation flow and gate promotion logic updates.
Rule Synthesis & Caching Gradata/src/gradata/enhancements/rule_synthesizer.py, Gradata/src/gradata/enhancements/meta_rules_storage.py	New rules-block synthesizer with provider abstraction, caching by hash, and strict validation of outputs; storage/load formatting/layout changes.
Events, Transcript & PII Gradata/src/gradata/_events.py, Gradata/src/gradata/_transcript.py, Gradata/src/gradata/_transcript_providers.py	PII redaction for persisted events, side-log of raw events, transcript logging/reading/cleanup and providers for external session sources.
CLI, Hooks & Skills Gradata/src/gradata/cli.py, Gradata/hooks/hooks.json, Gradata/skills/core/session-start/SKILL.md	Added gradata skill export, cloud/no-cloud flags for doctor, Stop-phase hook order change (ctx_watchdog then session_close), and documented session-start skill flow.
Logging & Error Handling Sweep Many Gradata/src/gradata/_* and Gradata/src/gradata/enhancements/* files	Replaced numerous silent except: pass sites with module loggers and logger.warning(..., exc_info=True), making previously-silent failures visible across database, file, and LLM flows.
New Tools & Utilities Gradata/src/gradata/_transcript*.py, Gradata/src/gradata/_migrations/_ulid.py, Gradata/src/gradata/_migrations/device_uuid.py	Transcript providers and lightweight ULID/device-id utilities added.
Formatting, Refactors & Deprecated Artifacts Many files across enhancements/, contrib/, detection/, etc.; Gradata/.archive/dashboard_streamlit_deprecated_2026-04-23.py	Large-scale formatting/whitespace cleanup across many modules; archived legacy Streamlit dashboard added to archive.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant UserAgent as Client (gradata CLI)
    participant SDK as Local SDK
    participant DB as SQLite (system.db / events.jsonl)
    participant LLM as LLM Provider (Anthropic/OpenAI/Gemini/HTTP)
    participant Cloud as Supabase / Gradata API

    UserAgent->>SDK: trigger graduation / skill export / cloud push
    SDK->>DB: read sessions, lessons, events
    DB-->>SDK: return rows/events
    SDK->>SDK: synthesize meta-rules (cluster + candidate selection)
    alt LLM creds present
        SDK->>LLM: request principle synthesis (prompt + context)
        LLM-->>SDK: synthesized principle
    else no creds
        SDK-->>SDK: fallback deterministic principle
    end
    SDK->>DB: write graduated meta-rules / cache synth results
    SDK->>Cloud: push transformed rows (batch, scrubbed JSONB)
    Cloud-->>SDK: ACK or constraint error (409)
    SDK->>DB: record cloud_push_error.json on failure
    SDK-->>UserAgent: return status / doctor diagnostics (local + cloud probes)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• v0.6.0: open-source pivot (Apache + cloud algorithms merged into SDK) #93: Overlapping open‑source pivot and large enhancements merge (cloud sync client, migrations, graduation changes).
• feat: multi-tenant SDK + cloud alignment (tenant_id, visibility, clusters, sync_state) #102: Related multi‑tenant and cloud sync changes (migrations, tenant/device helpers, scoped sync logic).
• feat: wire LLM meta-rule synthesis (Gemma native) #97: Related changes to meta‑rule LLM synthesis and principle generation logic.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/council-phase-c-leanout

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch feat/council-phase-c-leanout

[coderabbitai]

Actionable comments posted: 45

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@Gradata/.archive/dashboard_streamlit_deprecated_2026-04-23.py`:
- Around line 20-26: The hard-coded developer-specific Windows paths (BRAIN_DIR,
DB_PATH, EVENTS_PATH, LESSONS_PATH, PROSPECTS_DIR, BRIEF_PATH, TASKS_DIR) must
not be committed; replace them with configurable inputs and safe defaults: read
base path from an environment variable or CLI/config (e.g., BRAIN_DIR from
os.environ["BRAIN_DIR"] or a passed argument) and construct DB_PATH,
EVENTS_PATH, LESSONS_PATH, PROSPECTS_DIR, BRIEF_PATH, TASKS_DIR from that base
(falling back to a portable default like Path.home()/".gradata" when unset), and
remove or move the archived file from the repo and add it to .gitignore if it’s
personal. Ensure any code that imports these constants (search for usages of
BRAIN_DIR, DB_PATH, EVENTS_PATH, etc.) continues to work with the new
configuration API.

In `@Gradata/AGENTS.md`:
- Around line 80-85: The markdown has three fenced code blocks lacking language
identifiers (the blocks containing "Layer 2 — Public API        brain.py,
cli.py, daemon.py, mcp_server.py", "INSTINCT → PATTERN → RULE → META_RULE", and
"<type>(<scope>): <imperative description>"); add a language tag (e.g., ```text)
to each opening fence so the blocks become ```text ... ``` to silence
markdownlint MD040 warnings and keep formatting consistent.

In `@Gradata/CHANGELOG.md`:
- Around line 3-6: The changelog entry in CHANGELOG.md contains branch-relative
state ("33 commits ahead of public `origin/main`. Not yet pushed.") which will
become incorrect; remove that sentence from the Unreleased section and replace
it with a stable changelog-only note (or nothing) so the file only contains
release/change details, e.g., keep the "## [Unreleased] — post-0.6.0 (2026-04-23
→ 2026-04-24)" header and commit-based notes but delete the branch-status line;
update the file by editing CHANGELOG.md to eliminate any references to branch or
push status.
- Around line 13-15: Update the CHANGELOG entry to match the actual migration
filename used in the codebase: replace the incorrect migration name
`002_event_id_device_id_content_hash` with `002_add_event_identity.py` and
ensure the description corresponds to the implementation in
`002_add_event_identity.py`; also confirm the adjoining entry for
`003_add_sync_state` remains accurate and references the real migration filename
used in the PR.

In `@Gradata/docs/architecture/multi-tenant-future-proofing.md`:
- Around line 21-23: Add a single blank line immediately after the heading "###
1. Local-first stays the source of truth" so the paragraph starting with "SDK
writes to local SQLite + jsonl..." is separated by an empty line; update the
markdown around that heading in the document to satisfy MD022 while keeping the
heading text and paragraph content unchanged.

In `@Gradata/docs/cloud/dashboard.md`:
- Line 3: The doc contradicts itself about meta-rule synthesis: update the
"Brain detail" bullet that currently describes meta-rules as cloud-synthesized
to match the earlier statement that "Meta-rule synthesis runs locally in the
SDK" — locate the bullet that mentions "meta-rules" or "cloud-synthesized" and
change its wording to indicate synthesis happens locally (e.g., "meta-rules are
synthesized locally by the SDK and the dashboard renders the results") or remove
the cloud-synthesis claim so both passages consistently state local synthesis.

In `@Gradata/docs/concepts/meta-rules.md`:
- Around line 47-50: The blank line inside the "!!! info \"Local by default\""
admonition is currently unindented and being parsed as an indented code block;
to fix it, keep that blank line indented to match the admonition block (e.g.,
add a single space or the same indentation used for the surrounding admonition
lines) so the paragraph beginning with "Meta-rule clustering **and** principle
synthesis..." is treated as admonition text rather than a code block.

In `@Gradata/docs/LEGACY_CLEANUP.md`:
- Around line 16-46: Add a blank line immediately after each top-level heading
in LEGACY_CLEANUP.md to satisfy MD022: ensure there is one empty line after "1.
Deprecated adapter shims (scheduled v0.8.0)", "2. `_cloud_sync.py` terminology",
"3. Docstring drift in `meta_rules.py`", "4. Test-level cloud gating", "5.
`api_key` kwarg on `merge_into_meta`", and "6. Doc sweep" so that each heading
is followed by a single blank line before its subsequent paragraph or list
content.

In `@Gradata/docs/specs/cloud-sync-and-pricing.md`:
- Around line 34-40: Add blank-line padding before and after the permissions
table that begins "Each key is scoped at creation time:" (the table with
`brain:sync`, `brain:read`, `team:admin`, `marketplace:publish`) so it complies
with markdownlint rules, and update all fenced code blocks in this spec to
declare a language (e.g., ```json or ```text) to silence MD040/MD031/MD058;
apply the same blank-line padding and explicit language labels to the other
fenced sections referenced in the review so every table and code fence in the
document follows the markdownlint expectations.

In `@Gradata/LEANOUT_PLAN.md`:
- Around line 1-4: Add a prominent, top-of-file superseded warning to
Gradata/LEANOUT_PLAN.md that clearly states this plan is superseded by
VERIFIED_LEANOUT.md and must not be executed; update the document header (the
existing "# Gradata Leanout Plan (Phase C)" section) to prepend a visible banner
that references VERIFIED_LEANOUT.md and warns against running REMOVE/DELETE
steps, and insert the same brief warning immediately before the sections around
the noted destructive steps (near the blocks corresponding to the ranges called
out in the review) so readers cannot miss it before any REMOVE/DELETE or
mass-deletion instructions. Ensure the banner text names VERIFIED_LEANOUT.md,
uses unmistakable language (e.g., "SUPERSEDED — DO NOT EXECUTE"), and is present
both at the very top and directly above the destructive action blocks.

In `@Gradata/migrations/supabase/014_corrections_unique.sql`:
- Around line 23-34: The guard currently uses only c.conkey @> ARRAY[...] which
is a superset match and can falsely detect constraints that include additional
columns; update the existence check for the corrections table / target columns
(brain_id, session, description) to require an exact match by adding the
complementary subset check and a cardinality check (e.g., ensure c.conkey <@
ARRAY[...] and array_length(c.conkey,1) = 3) so the constraint is only
considered present when it covers exactly those three columns.

In `@Gradata/migrations/supabase/015_events_unique.sql`:
- Around line 23-34: The guard currently uses c.conkey @> ARRAY[...] which only
checks for a superset; change the condition that detects an existing UNIQUE on
the events table (the WHERE block referencing pg_constraint c, pg_class t,
relname = 'events', and the conkey array for brain_id/type/created_at) to
enforce exact set equality by either requiring mutual containment (c.conkey @>
arr AND arr @> c.conkey) or by requiring containment plus cardinality (c.conkey
@> arr AND array_length(c.conkey,1) = 3) where arr is the ARRAY[(SELECT attnum
... 'brain_id'), (SELECT attnum ... 'type'), (SELECT attnum ...
'created_at')]::smallint[]; update the WHERE clause accordingly so the migration
only skips when an exact 3-column UNIQUE exists.

In `@Gradata/migrations/supabase/README.md`:
- Around line 32-37: The fenced code block in README.md that documents
constraint states (containing corrections_brain_session_desc_key,
corrections_brain_session_description_unique, events_brain_type_created_at_key,
events_brain_type_created_at_unique) lacks a language identifier; update the
opening triple-backtick to include a language (e.g., ```text) so markdownlint
MD040 is satisfied and the block is explicitly marked as plain text.

In `@Gradata/skills/core/session-start/SKILL.md`:
- Around line 32-36: The fenced code block in SKILL.md lacks a language tag and
triggers markdownlint MD040; update the triple-backtick fence that currently
wraps the example (the block showing "[check] S[N] loaded | [today's calendar or
"clear"]" etc.) to include a language tag, e.g., change ``` to ```text so the
block is explicitly marked as plain text.
- Around line 12-21: The SKILL.md uses hard-coded Windows paths (e.g.,
C:/Users/olive/... in references to continuation.md, continuation.py,
lessons.md, loop-state.md, brain_prompt.md and domain/pipeline/startup-brief.md)
which will break on other machines; update the instructions to use repo-relative
or configurable placeholders (e.g., ${REPO_ROOT}/brain/continuation.md or
${BRAIN_DIR}/continuation.md) or reference an environment/config variable
(BRAIN_DIR/REPO_ROOT) and show example usage for invoking the archive script
(python ${BRAIN_DIR}/scripts/continuation.py archive); apply the same
replacement to the other occurrences referenced (lines ~48-50) and document the
required env var or config key in this SKILL.md so consumers know how to set it.

In `@Gradata/src/gradata/_brain_manifest.py`:
- Around line 64-77: The try/except around the DB cross-check can leak
connections and hides errors; update the block that uses ctx, get_connection(),
conn, and version_info so the DB connection is always closed (use a finally
block or a context manager around get_connection) and change the exception
handling to log at warning level using _log.warning with exc_info=True (include
a clear message like "Session count DB cross-check failed (non-fatal)"). Ensure
conn.close() is executed even on exceptions and preserve the existing behavior
of updating version_info["sessions_trained"] when db_max > current value.

In `@Gradata/src/gradata/_cloud_sync.py`:
- Around line 48-59: The code currently allows the SDK client path to read the
Supabase service-role key via ENV_KEY_ALIAS (GRADATA_SUPABASE_SERVICE_KEY) in
_env_key(), which exposes an admin credential to client environments; change
_env_key() to only return ENV_KEY (the client/anon key) and stop checking
ENV_KEY_ALIAS, and remove or relocate ENV_KEY_ALIAS use so service-role keys are
only read by secure backend code paths (e.g., backend-only functions/classes
that explicitly need the service key). Update references to ENV_KEY_ALIAS
accordingly and ensure any code that needs the service role reads it from a
backend-only accessor, not from _env_key().
- Around line 142-149: The current logic converts non-integer numerics (e.g.,
session_raw = 4.5) to int(4.5) → 4, mutating the session id; instead, only
accept true integers and preserve everything else in data_blob. Update the block
that sets session_int from session_raw so that: if session_raw is an actual int
(isinstance(session_raw, int)) or a string that represents an integer (use a
strict integer check, e.g., regex or str.isdigit with optional sign) then set
session_int to that integer; otherwise set session_int = None and ensure
data_blob["session_raw"] = session_raw (if not already present). Keep the
existing exception handling for TypeError/ValueError but do not coerce floats or
other numeric types into ints.

In `@Gradata/src/gradata/_core.py`:
- Around line 1293-1298: The comprehension that builds finals from
session_corrections is reading the wrong key ("final") so blandness is computed
as 0.0; change it to read "final_text" (and you can keep "final" as a fallback
for compatibility) so compute_blandness receives the corrected outputs—update
the finals list comprehension in the block that calls compute_blandness (refer
to session_corrections, compute_blandness, cloud_sync_tick(), and
brain_correct()) to use c.get("final_text", c.get("final", "")) and only include
truthy values.
- Around line 700-703: Replace the blanket suppression around
brain._rule_graph.save() so failures are logged: instead of using
contextlib.suppress(Exception) around brain._rule_graph.save(), wrap the call in
a try/except Exception as e and call the module logger (or existing logger
instance) with a warning or error message that includes exception context (e.g.,
logger.warning("Failed to save rule graph", exc_info=True) or similar). Keep the
call target brain._rule_graph.save() and remove the silent swallow so failures
are visible in logs.

In `@Gradata/src/gradata/_doctor.py`:
- Around line 309-318: The probe in _check_cloud_reachable currently ignores the
URL's scheme/port by hardcoding port 443; update _check_cloud_reachable to parse
api_url (use urllib.parse.urlparse) to extract hostname and port, derive the
effective port as parsed.port or (443 if scheme == "https" else 80) and pass
(hostname, port) to socket.create_connection with the existing
_CLOUD_PROBE_TIMEOUT; ensure api_url fallback logic remains and that the host
variable is the pure hostname (no ":port") before connecting.
- Around line 240-253: _read_cloud_config currently swallows parse and
permission errors and always returns {}, causing _check_cloud_config to report
"missing credentials" instead of the real problem; change _read_cloud_config
(and the analogous block used around lines 256-271) to only return {} for the
specifically expected "no file" and missing-tomllib cases, but let
PermissionError and TOML parse errors propagate (or raise a specific exception)
so callers like _check_cloud_config can detect and report unreadable or
malformed config; specifically, stop the broad except Exception: return {},
instead catch FileNotFoundError/NotADirectoryError to return {}, catch
ImportError for tomllib to return {}, and otherwise re-raise or raise a
descriptive exception for permission/parse errors (e.g., PermissionError,
tomllib.TOMLDecodeError or Exception as e) so diagnostics can surface the real
issue.

In `@Gradata/src/gradata/_events.py`:
- Around line 224-230: The current emit() logic writes raw_event to
events.raw.jsonl via _locked_append (using events_jsonl and raw_jsonl), which
persists unredacted PII; remove or change that behavior so the side-log never
contains full raw_event payloads — either stop writing the raw side-log entirely
or write a redacted/sanitized version (e.g., only metadata, event id, timestamp,
and hashed identifiers) using the same _locked_append call but passing a
redacted_event instead of raw_event; ensure any mention of events.raw.jsonl is
updated to use the sanitized content and that exc_info logging remains for
failures.

In `@Gradata/src/gradata/_installer.py`:
- Around line 188-199: The generic warning in list_installed suppresses
exceptions without file context; update the logger.warning calls in
gradata._installer.list_installed to include the failing path variables
(meta_file and manifest_file) and the brain directory identifier (e.g., the
brain path or variable used to derive meta_file/manifest_file) so operators can
triage bad installs—adjust both warning calls to log a descriptive message like
"Suppressed exception reading manifest/meta" along with the path and include
exc_info=True to preserve the traceback.

In `@Gradata/src/gradata/_migrations/__init__.py`:
- Around line 115-117: The except block in _apply_inline currently catches
sqlite3.OperationalError and logs it with logger.warning(..., exc_info=True),
which produces noisy stack traces for benign idempotent errors; update the
sqlite3.OperationalError handler in _apply_inline to inspect the exception
message (e.g., contains "already exists", "duplicate column", or other
idempotent patterns) and, for those cases, log at debug/info level without
exc_info, while only emitting a warning with exc_info=True for unexpected
OperationalError messages; reference the _apply_inline function and its
sqlite3.OperationalError except clause when making the change.

In `@Gradata/src/gradata/_migrations/_ulid.py`:
- Around line 47-51: The timestamp conversion uses datetime.timestamp() on dt
which may be naive if iso_ts lacked timezone info; make it deterministic by
normalizing dt to UTC before computing ts_ms: after parsing (the variable dt
from datetime.fromisoformat(...)), check dt.tzinfo and if it's None set its
timezone to UTC (e.g., dt = dt.replace(tzinfo=timezone.utc)) or otherwise
convert to UTC with dt = dt.astimezone(timezone.utc), then compute ts_ms =
int(dt.timestamp() * 1000) and pass that to new_ulid(ts_ms=ts_ms) (references:
variable dt and function new_ulid).

In `@Gradata/src/gradata/_migrations/device_uuid.py`:
- Around line 56-80: The temp filename is only PID-scoped so concurrent calls in
get_or_create_device_id can collide and cause callers to return new_did before
the on-disk .device_id is persisted; change the write logic to create a unique
temp file per invocation (e.g., include a uuid4/timestamp/random suffix or use
tempfile.NamedTemporaryFile with delete=False in the same directory) instead of
tmp = brain / f".device_id.tmp.{os.getpid()}"; write to that unique temp, fsync
if possible, then use os.replace(tmp_unique, fpath) atomically; also remove the
current FileExistsError branch that assumes a single PID file and instead on any
write conflict fall back to reading fpath (did) and validating it before
returning new_did, ensuring fpath.read_text() is checked again after any
suppressed exception so callers never get a non-persisted device id (affecting
variables tmp, new_did, fpath and the get_or_create_device_id function).

In `@Gradata/src/gradata/_transcript_providers.py`:
- Around line 133-137: The _path() method in GradataTranscriptSource currently
trusts self._session_id as a raw path segment (allowing "../" traversal); update
_path() to reuse the same session-id sanitizer/validator used by the writer
(e.g., validate_session_id or sanitize_session_id) before building the Path,
reject or return None for invalid session ids, and then construct the path using
the validated id so the lookup cannot escape the brain/sessions directory;
ensure you reference GradataTranscriptSource._path and the existing writer
sanitizer function when making the change.

In `@Gradata/src/gradata/_transcript.py`:
- Around line 74-78: The current env parsing for truncate and TTL in
_transcript.py directly casts os.environ values to int (e.g., the computation of
limit using truncate_at and os.environ.get(_TRUNCATE_ENV,
str(DEFAULT_TRUNCATE))) which raises ValueError on invalid env input and breaks
best-effort helpers like log_turn() and cleanup_ttl(); change these to robust
parsing with a safe_int helper or try/except: attempt to parse the env value to
int, on failure fall back to DEFAULT_TRUNCATE (for truncate) or DEFAULT_TTL_DAYS
(for TTL), and clamp the parsed value into acceptable bounds if needed, then use
that sanitized value in the existing logic (references: truncate_at,
_TRUNCATE_ENV, DEFAULT_TRUNCATE and the TTL parsing near
GRADATA_TRANSCRIPT_TTL_DAYS/DEFAULT_TTL_DAYS and cleanup_ttl()).
- Around line 46-51: The _session_dir and _transcript_path helpers currently
join a caller-controlled session_id into a filesystem path; validate and
sanitize session_id before using it: ensure session_id is not absolute (reject
Path(session_id).is_absolute()), does not contain path separators or parent
segments (reject if "/" or "\\" present or if any part == ".."), and restrict
characters (e.g., allow only a safe regex like alphanumerics, dot, dash,
underscore) or else raise an exception; update _session_dir (and any callers
like _transcript_path) to perform this validation and only use the vetted
session_id when building the Path to prevent path-traversal/absolute-path
writes.

In `@Gradata/src/gradata/brain.py`:
- Around line 897-915: The event payload for _bus.emit("rules.injected")
currently includes the raw task variable which may contain user PII/secrets;
remove or replace the verbatim task text with a non-sensitive representation
(e.g., a sanitized summary, redacted fields, or a stable task_id/hash) before
emitting. Modify the emission code around _bus.emit("rules.injected") to compute
a sanitized_task (or use task_id/task_meta) and include that instead of task,
ensuring any sensitive fields are stripped or hashed; keep other fields (rules,
scope) unchanged and update callers/subscribers to consume the sanitized field
name.

In `@Gradata/src/gradata/cli.py`:
- Around line 1112-1117: Resolve the brain once via _get_brain(args) and reuse
it for both brain_root and lessons_path instead of calling _resolve_brain_root()
and _get_brain() separately; call brain = _get_brain(args) first, set brain_root
from the resolved brain object (e.g., brain.root or equivalent attribute) and
then call lessons_path = brain._find_lessons_path(), ensuring the env-first
resolution (GRADATA_BRAIN > --brain-dir > cwd) is honored and the same brain is
used for export and lesson discovery.

In `@Gradata/src/gradata/cloud/sync.py`:
- Around line 160-164: The current call hardcodes "/api/v1/telemetry/metrics"
which will double-prefix if self.api_base already contains "/api/v1"; change the
endpoint construction so it joins api_base and the relative path safely (e.g.,
strip trailing slash from self.api_base and leading slash from
"telemetry/metrics" or use urllib.parse.urljoin) and call self._post with that
joined URL or pass just the relative path if _post already handles base joining;
update the line that calls self._post("/api/v1/telemetry/metrics",
asdict(payload)) to compute the endpoint from self.api_base and the telemetry
path to avoid duplicate "/api/v1".

In `@Gradata/src/gradata/contrib/enhancements/quality_gates.py`:
- Around line 360-370: The code in evaluate_success_conditions opens an sqlite3
connection into variable conn and calls conn.close() only on the happy path;
move to a context manager to guarantee closure on all paths: replace the manual
sqlite3.connect(...) and conn.close() pattern with "with
sqlite3.connect(str(db)) as conn:" and run the SELECT and assignment
(report.sessions_evaluated = max_session) inside that block so the connection is
always closed even if an exception occurs; ensure you keep the existing
exception handling that logs via logger.warning.

In `@Gradata/src/gradata/contrib/patterns/pipeline.py`:
- Around line 240-242: Stage.__repr__ currently assumes self.gate has a __name__
and can raise AttributeError; make it defensive by obtaining a safe gate_label:
try to use getattr(self.gate, "__name__", None), fall back to using
type(self.gate).__name__ or repr(self.gate) (or "none" when self.gate is None),
or wrap access in try/except so __repr__ never raises; update the gate_label
computation inside Stage.__repr__ accordingly (referencing Stage.__repr__,
self.gate, and gate_label).

In `@Gradata/src/gradata/contrib/patterns/q_learning_router.py`:
- Around line 389-391: The HMAC key in _compute_hmac() is derived from
platform.node(), which is not secret—change _compute_hmac to first look for a
real secret (e.g., read os.environ["GRADATA_ROUTER_HMAC_KEY"] or similar) and
use that as the HMAC key, falling back to the legacy
f"gradata-router-{platform.node()}" encoding only when the env var is absent;
also update the load() logic to accept either the legacy HMAC or the new
secret-derived HMAC (verify against both) so existing files remain readable
while new configs use the secret key.

In `@Gradata/src/gradata/enhancements/bandits/collaborative_filter.py`:
- Around line 155-167: Replace the magic literal 0.89 with a named constant
(e.g., CONFIDENCE_CAP_BELOW_RULE = 0.89) declared near the top of
Gradata/src/gradata/enhancements/bandits/collaborative_filter.py and use that
constant in the min(...) call that currently reads min(0.89, lesson.confidence +
boost); keep the existing logic and rounding unchanged and only swap the literal
in the cap expression (you may also add a brief comment on the constant to
clarify it intentionally sits below the RULE threshold used in the
lesson.confidence < 0.90 check).

In `@Gradata/src/gradata/enhancements/edit_classifier.py`:
- Around line 120-149: The current classifier only checks single-token sets
(_PROCESS_WORDS) against new_words/old_words, so multi-word markers like "touch
base" or "catch up" are never matched; update the logic to handle phrase markers
by adding a separate phrase collection (e.g., PROCESS_PHRASES containing "touch
base", "catch up", etc.) and check these phrases against the original text (or
against token n-grams) before or alongside the existing new_words/old_words set
check in the classification routine (the code that compares new_words/old_words
to _PROCESS_WORDS). Ensure phrase matching is done case-insensitively and
normalized the same way tokens are so multi-word markers can trigger PROCESS
classification.
- Around line 45-59: The tone marker set _TONE_WORDS contains mixed-case entries
(e.g., "I think", "I believe") while the comparison variables
old_lower/new_lower are lowercased, so those markers never match; to fix,
normalize the markers when constructing or using the set: either update
_TONE_WORDS to store all entries in lowercase (e.g., replace "I think"/"I
believe" with "i think"/"i believe") or ensure the code that builds the lookup
lowercases each marker (call .lower()/.casefold() for entries before adding to
_TONE_WORDS) and use the same normalization when comparing with
old_lower/new_lower; update references to _TONE_WORDS and any set membership
checks to use the normalized form consistently.

In `@Gradata/src/gradata/enhancements/graduation/agent_graduation.py`:
- Around line 222-225: The deterministic rule for the "owner_only" trigger is
compiled with the literal token EXCLUDED_NAMES_PLACEHOLDER so it never matches;
update compile_deterministic_rule() to detect this placeholder and either
substitute the configured excluded names (properly escaped and joined into the
regex) before calling re.compile(), or return None if no excluded-names config
is present; reference the "owner_only" rule, EXCLUDED_NAMES_PLACEHOLDER,
compile_deterministic_rule(), and enforce_rules() so the compiled rule is valid
only when the brain config provides the excluded names.

In `@Gradata/src/gradata/enhancements/observation_hooks.py`:
- Around line 81-87: The PEM redaction is incomplete: update the _PII_PATTERNS
entry that currently matches only the "-----BEGIN ...-----" header so it matches
and replaces the entire PEM block (header, base64 body, and "-----END ...-----"
footer). Replace that tuple in _PII_PATTERNS with a regex that spans multiple
lines (use DOTALL / re.S) and uses non-greedy matching between the BEGIN and END
markers (e.g., a pattern like "-----BEGIN [A-Z ]+-----.*?-----END [A-Z ]+-----")
and keep the replacement token "[PRIVATE_KEY]"; ensure the regex flag _re.S is
applied so multi-line PEM blocks are fully redacted.

In `@Gradata/src/gradata/enhancements/profiling/tone_profile.py`:
- Around line 502-505: The prompt generation interpolates profile.task_type
directly in generate_tone_prompt, creating a prompt-injection risk; update
generate_tone_prompt to validate profile.task_type against a closed allowlist
(e.g., a set/map of known task types) and replace or map any unrecognized value
to a safe default like "unknown" or a canonical mapped label, and also
strip/escape any control/newline characters before interpolation; reference the
generate_tone_prompt function and the profile.task_type use (lines ~463-503 and
the lines building the lines list) when applying this change.

In `@Gradata/src/gradata/enhancements/rule_synthesizer.py`:
- Around line 97-112: _read_cache currently returns whatever is on disk and
_write_cache uses write_text directly, which allows readers to see truncated
partial writes; change _write_cache to perform an atomic write to a temporary
file (e.g., create temp file in brain_dir/CACHE_DIRNAME, write and flush +
os.fsync the file, then os.replace to the final path, and fsync the containing
directory) and have _read_cache validate the read content before returning (at
minimum reject empty/truncated text and any parse/validation errors your synth
logic expects so callers fall back to malformed-output handling); use the
existing helpers _cache_path and CACHE_DIRNAME to locate files and handle
OSError consistently.

In `@Gradata/src/gradata/enhancements/rule_to_hook.py`:
- Around line 824-846: Replace the two contextlib.suppress(Exception) blocks
that call brain.emit for "RULE_TO_HOOK_REMOVED" and HOOK_DEMOTED with explicit
try/except Exception handlers: catch Exception around each brain.emit call (the
emits referencing variables source, slug, and target) and in the except log a
warning (e.g., logger.warning or processLogger.warning) including a clear
message and exc_info=True so the stack/exception is recorded instead of being
silently suppressed; ensure the warning message names the event
(RULE_TO_HOOK_REMOVED or HOOK_DEMOTED) and the slug/hook_path for context.

In `@Gradata/VERIFIED_LEANOUT.md`:
- Around line 125-128: Update the summary table entries to match the detailed
audit: change `notifications.py`, `onboard.py`, and `safety.py` from "pragmatist
DELETE | UNVERIFIED" to reflect the audit's KEEP decision (e.g.,
`notifications.py | KEEP`, `onboard.py | KEEP`, `safety.py | KEEP`), and ensure
`daemon.py` remains "DELETE_OR_MOVE | MOVE only — Phase B just wired lock
support" if that audit conclusion stands; make the table's status strings and
notes identical to the conclusions in the detailed lines 88–90 so the top-level
summary does not contradict the detailed audit.

---

Outside diff comments:
In `@Gradata/src/gradata/_core.py`:
- Around line 943-958: The INSERT into lesson_transitions is writing None for
the session column, losing session linkage; update the values tuple passed to
conn.execute in the lesson_transitions INSERT to supply the real session
identifier (e.g., use lesson.session or the local session variable used
elsewhere in _core.py) instead of None so the 7th parameter maps to the session
column; ensure the symbol conn.execute and the lesson_transitions INSERT call
are updated and that the session value is present and correctly formatted
(string/UUID) to match the table schema.

In `@Gradata/src/gradata/_data_flow_audit.py`:
- Around line 117-130: The check_embeddings function currently treats all
exceptions as the "table not created" case; update it to catch
sqlite3.OperationalError (import sqlite3 already present) and check the
exception message for "no such table" to call _check("embeddings:sqlite", True,
"brain_embeddings table not yet created (ok)"); for any other exception, call
_check("embeddings:sqlite", False, f"error checking brain_embeddings: {err}") or
re-raise so real DB errors aren’t masked—ensure you still obtain db from
ctx/db_path and keep using conn.execute(...).fetchone() and conn.close() as in
the function.
- Around line 55-79: check_index_completeness currently assumes
manifest_path.read_text() yields valid JSON and a dict; wrap the json.loads(...)
and subsequent manifest usage in a try/except that catches json.JSONDecodeError
and TypeError (and optionally ValueError) and on error calls
_check("index:manifest_exists" or "index:completeness", False, f"invalid
.embed-manifest.json: {err}") and returns so the audit doesn't raise; also
validate that manifest is a mapping (e.g., isinstance(manifest, dict)) before
using manifest.keys(), and if not, call _check with passed=False and a
descriptive detail and return.
- Around line 81-149: check_facts_freshness and check_fts5 open sqlite3
connections but only call conn.close() on the success path; change both to use
context managers (with sqlite3.connect(str(db)) as conn:) so the connection is
always closed even on exceptions, moving any conn.execute(...) calls inside the
with block and computing prospects_with_facts/count within that scope, and
remove the explicit conn.close() calls; ensure imports (sqlite3) remain
available where used and keep the existing exception handling logic intact
(functions: check_facts_freshness, check_fts5).
- Around line 21-53: check_event_pipes currently swallows all exceptions and
only closes the sqlite3 connection on the success path; change it to open the DB
in a try/finally (or use a context manager) to ensure conn.close() always runs,
catch specific DB/file errors (or catch Exception as e) but log the error
instead of silently treating it as empty (use logging.exception(...) or
_p.logger.exception(...) if available), and preserve the current behavior of
calling _check for each known_types item with emitted_types defaulting to empty
on error; update references in the function (check_event_pipes, ctx, _p.DB_PATH,
sqlite3.connect, emitted_types, and _check) accordingly.

In `@Gradata/src/gradata/_doctor.py`:
- Around line 549-556: The "degraded" branch handling around the status variable
prints a misleading pip-install remediation; update the elif status ==
"degraded" block in _doctor.py to emit a generic remediation message instead of
"Some optional dependencies missing... Run the suggested pip install commands",
e.g. indicate that degraded may be due to cloud auth, network, or disk issues
and instruct the user to inspect the detailed errors above and follow the
specific remediation for auth/network/disk or optional dependencies as
appropriate; keep the existing "healthy" and other/critical branches unchanged.

In `@Gradata/src/gradata/_events.py`:
- Around line 692-727: RetainOrchestrator.flush() is writing raw event["data"]
into events.jsonl and the SQLite INSERT, bypassing the redaction used by emit(),
which causes inconsistent persistence and a PII leak; update flush() to apply
the same redaction path emit() uses before serializing/writing events (i.e.,
compute a redacted_event or redacted_data for each event and pass that to
_locked_append_many and to the INSERT parameters instead of event["data"]), and
if no shared redaction helper exists, extract the redaction logic from emit()
into a reusable function (e.g., redact_event) and call that from flush(),
_locked_append_many usage, and the SQLite INSERT so both outputs store the
redacted payload.

In `@Gradata/src/gradata/_export_brain.py`:
- Around line 211-237: The export_brain function applies ctx only for brain_dir
and prospects_dir but still calls global helpers (_LESSONS_ARCHIVE, _CARL_LOOP,
_CARL_GLOBAL, _QUALITY_RUBRICS and possibly collect_* helpers) which can read
from the wrong brain; update export_brain to consistently use the provided ctx
when present: pass ctx into collect_brain_files and collect_domain_files (or
call their ctx-aware variants), and replace direct calls to global helpers
(_LESSONS_ARCHIVE(), _CARL_LOOP(), _CARL_GLOBAL(), _QUALITY_RUBRICS()) with the
equivalent paths obtained from ctx (or construct them from ctx.brain_dir /
ctx.prospects_dir) so all file reads/writes reference the same brain context
used for brain_dir/prospects_dir.

In `@Gradata/src/gradata/_file_lock.py`:
- Around line 99-107: The per-retry logger.warning in the non-blocking lock loop
is noisy; update the OSError handling inside the Windows lock helper (the block
that calls msvcrt.locking on fh.fileno() and catches OSError) to avoid emitting
a WARNING each retry: replace the per-retry logger.warning with a logger.debug
(or drop exc_info) so retries are silent, and ensure only the final failure path
(where you raise TimeoutError for fh.name) logs at warning/error level. Apply
the same change to the second occurrence of this pattern further down (the block
at the other locking attempt).

In `@Gradata/src/gradata/_manifest_metrics.py`:
- Around line 56-104: The function _correction_rate_trend currently opens a
SQLite connection via get_connection(db) and may exit on exceptions (from
_session_window or the queries) without closing conn; change the function to
ensure the connection is always closed by using a context manager or finally
block (e.g., use with closing(get_connection(db)) as conn: or try/finally) so
conn.close() is guaranteed even on errors; update the inner helper usage (the
_cro closure and calls to _session_window) to operate within that managed scope,
and apply the same pattern to the other similar helpers in this module to avoid
leaking SQLite handles.

In `@Gradata/src/gradata/_migrations/tenant_uuid.py`:
- Around line 47-63: The try block must begin before the os.open() call to catch
FileExistsError from O_EXCL collisions: in get_or_create_tenant_id move the try:
to wrap the os.open(tmp, flags, 0o644) invocation (which sets fd) so that the
existing except FileExistsError branch will handle PID-collision races; keep the
existing logic that fd is used with os.fdopen, the conditional os.replace(tmp,
fpath) / os.unlink(tmp) behavior, and the logger.warning('Suppressed exception
in get_or_create_tenant_id', exc_info=True) in the except block.

In `@Gradata/src/gradata/_query.py`:
- Around line 48-52: The current contextlib.suppress(sqlite3.OperationalError)
around conn.execute("ALTER TABLE brain_fts_content ADD COLUMN tenant_id TEXT")
hides all OperationalError types (e.g., "database is locked"); change it to a
try/except that catches sqlite3.OperationalError as e and only suppresses the
error when the message indicates the duplicate-column case (e.g., contains
"duplicate column" or "duplicate column name"), otherwise re-raise the exception
so real DB errors surface.

In `@Gradata/src/gradata/_stats.py`:
- Around line 188-217: The function rolling_comparison does not guard against
window <= 0, causing values[-window:] to behave incorrectly; add an explicit
parameter validation at the start of rolling_comparison to handle non-positive
windows (for example raise a ValueError or coerce window to 1), e.g. check if
window is not an int or window <= 0 and raise ValueError("window must be a
positive integer") (or set window = max(1, window)) before any
slicing/averaging; ensure this validation appears before computing
lifetime_avg/recent and mention rolling_comparison, window, values, recent,
lifetime_avg in the change.
- Around line 106-151: Add explicit input validation in beta_posterior: check
that trials is a non-negative integer, successes is an integer between 0 and
trials inclusive, and prior_alpha and prior_beta are positive numbers; if any
check fails, raise a ValueError with a clear message. Implement these guards at
the start of beta_posterior (before computing alpha and beta_param), e.g.,
validate types/values for successes, trials, prior_alpha, prior_beta, and only
then compute alpha = prior_alpha + successes and beta_param = prior_beta +
trials - successes so downstream calls to scipy.stats.beta (and the fallback std
math) cannot receive invalid parameters.
- Around line 159-181: The wilson_ci function should validate inputs before
computing: ensure total is an int >= 0, successes is an int between 0 and total
(inclusive), and z is positive; if total == 0 keep the existing early return,
but if total < 0 or successes < 0 or successes > total or z <= 0 raise a
ValueError with a clear message. Update wilson_ci to perform these checks at the
top (referencing the function name wilson_ci and parameters successes, total, z)
so downstream math.sqrt/divisions never receive invalid values and the function
fails fast with a descriptive error.
- Around line 375-403: The mtbf_mttr function currently treats a valid mttr
value of 0.0 as falsy and returns None; update the mttr return condition in
mtbf_mttr to only treat None as missing (e.g., use an explicit is not None
check) so that zero values are preserved and still rounded (change the `"mttr":
round(mttr, 1) if mttr else None` logic to use `if mttr is not None` for the
mttr field in the results dict).
- Around line 248-282: The ewma_control function lacks validation for
lambda_param and sigma_multiplier, which can produce division-by-zero or
negative-sqrt errors; at the start of ewma_control add explicit parameter checks
that raise ValueError with clear messages if invalid: ensure lambda_param is
numeric and 0 <= lambda_param < 2 (or >0 if you require strictly positive) and
ensure sigma_multiplier is numeric and >= 0; perform these checks before any
math using lambda_param (e.g., before computing ewma_sigma) so invalid inputs
are caught early and prevent downstream math errors.

In `@Gradata/src/gradata/audit.py`:
- Around line 51-67: The exception handlers in functions like write_provenance
(and the other handlers around the indicated ranges) only log the exception
string using _log.debug("...: %s", e); update these to include the traceback by
passing exc_info=True (e.g. _log.debug("write_provenance failed",
exc_info=True)) or using your structured logger's equivalent, and ensure all
similar debug calls in the file (lines ~51-67, 109-111, 154-156, 231-233) are
changed so the full stack trace is emitted rather than just e.

In `@Gradata/src/gradata/contrib/patterns/agent_modes.py`:
- Around line 150-169: Normalize the incoming action string in check_permission
before using _ACTION_FIELD_MAP: trim whitespace and convert to lowercase (e.g.,
action = action.strip().lower()) so keys like "Write" or " write " match the
map; then use the normalized value for the field lookup and for constructing the
error message so the reported action is consistent. Update references inside
check_permission (function name: check_permission, const/map: _ACTION_FIELD_MAP)
accordingly and ensure behavior unchanged for already-lowercase inputs.

In `@Gradata/src/gradata/contrib/patterns/context_brackets.py`:
- Around line 171-181: Update the inline comments on the ContextBracket enum
members to match the inclusive thresholds used by get_bracket(): change FRESH to
indicate ">=70% remaining", MODERATE to ">=40% and <70% remaining", DEEP to
">=20% and <40% remaining" (and optionally CRITICAL to "<20% remaining") so the
member doc/comments reflect the actual >= comparisons in get_bracket().

In `@Gradata/src/gradata/contrib/patterns/guardrails.py`:
- Around line 460-470: In check_write_path, the code currently returns ALLOWED
when target matches agent_write_paths before evaluating agent_tools_denied,
which lets explicit "Write " denies be bypassed; change the logic so you first
iterate agent_tools_denied (check entries that start with "Write " and compare
deny_pattern to target using fnmatch) and return ManifestCheckResult(False, ...)
on a match, and only after that iterate agent_write_paths and return
ManifestCheckResult(True, ...) when fnmatch matches; keep the same message
formats and use the existing symbols target, agent_tools_denied,
agent_write_paths, fnmatch, and ManifestCheckResult.
- Around line 640-650: The check_fn currently ignores the input and always
returns a passing GuardCheck; update check_fn (the closure that returns
GuardCheck) to actually evaluate the provided data by converting it to a
normalized string (e.g., lowercased via str(data).lower()), then test that text
against the rule derived from rule_text/rule_cat (e.g., detect "never X"
violations by checking presence of forbidden keywords or for "always Y" ensure
required keywords exist); set GuardCheck.result to "fail" when a violation is
found (and action_taken to a suitable value like "blocked" or "flagged") and to
"pass" otherwise, and include meaningful details mentioning the matched rule
fragment and the offending text so downstream code can act on failures.

In `@Gradata/src/gradata/contrib/patterns/loop_detection.py`:
- Around line 204-219: _norma­lize_args currently misses sets/frozensets,
doesn't stringify non-JSON types, and only shallow-normalizes list/tuple
elements; update _normalize_args to recursively normalize all container types
(dict, list, tuple, set, frozenset) by: sorting dict keys and recursively
normalizing values via _normalize_args, converting lists/tuples to tuples of
normalized elements (so order/determinism is preserved), converting
sets/frozensets to sorted tuples of normalized elements, and ensuring any
remaining non-JSON-serializable leaf values are converted to stable string
representations (e.g., via str()) so json.dumps in _hash_call cannot raise; keep
the function name _normalize_args and ensure its return structure is fully
deterministic for hashing.

In `@Gradata/src/gradata/contrib/patterns/middleware.py`:
- Around line 126-138: Docstring is misleading about circular dependency
detection; update the MiddlewareChain class docstring to state that anchors
(after_middleware and before_middleware) must reference already-registered
middleware names and that the current add() behavior raises MiddlewareError only
for unknown anchors or simultaneous conflicting anchors, so true cycles cannot
be created under this invariant; reference MiddlewareChain.add, MiddlewareError,
after_middleware and before_middleware in the text to make it clear.

In `@Gradata/src/gradata/contrib/patterns/orchestrator.py`:
- Around line 509-542: The orchestrator currently returns raw exception strings
(str(e)) in both the single-task direct branch and the multi-task sequential
fallback, which risks leaking sensitive data; update the error payloads in the
function (the branch where worker(tasks[0]) is called and the loop that calls
worker(task)) to return a generic error identifier (e.g., exception type via
type(e).__name__ or a fixed "internal_error" code) instead of str(e), and ensure
the full exception and stacktrace are logged securely (using an existing logger
or logging.exception) rather than included in the returned results; keep the
fields "task" and "status" unchanged and add an optional "error_code" or
"error_type" field to carry the non-sensitive identifier.

In `@Gradata/src/gradata/contrib/patterns/q_learning_router.py`:
- Around line 258-272: The cache entry currently stores (agent, cached_time) so
cached route decisions always return exploiting=True; update the cache to store
(agent, cached_time, exploiting) and change route()'s cache-hit branch to read
cached_agent, cached_time, cached_exploiting and pass cached_exploiting into
RouteDecision.exploiting instead of hardcoding True; also update any code that
writes to self._cache (where entries are set) to include the exploiting boolean
when inserting/updating the cache so reads are consistent with the new tuple
shape.

In `@Gradata/src/gradata/contrib/patterns/sub_agents.py`:
- Around line 36-48: Delegation.__post_init__ currently generates IDs with
id(self) % 10000 which can collide; update Delegation.__post_init__ to generate
a collision-resistant ID (e.g., use uuid.uuid4()) while preserving the existing
"agent_..." shape if needed; specifically, replace the id(self) % 10000 logic in
Delegation.__post_init__ with a uuid4-based suffix (or another sufficiently
unique generator) and ensure any code that references Delegation.id (such as
_topological_waves and depends_on handling) continues to use the new string IDs
correctly.

In `@Gradata/src/gradata/contrib/patterns/tools.py`:
- Around line 125-168: The ToolRegistry.execute method has an
off-by-one/inconsistent semantics for ToolResult.retries: success returns
retries=attempt (0-based) but failure returns retries=max_retries, causing e.g.
max_retries=1 to yield 0 on success and 1 on failure. Fix by making retries
represent the number of retries actually performed (attempt for the success
path, and max_retries - 1 for the final failure path); update the success return
in execute to keep retries=attempt and change the final failure return to set
retries = max(0, max_retries - 1). Refer to execute, ToolResult, max_retries and
the loop variable attempt when applying the change.

In `@Gradata/src/gradata/correction_detector.py`:
- Around line 259-307: detect_correction currently uses a 0.65 threshold while
extract_correction_context still treats confidence >= 0.50 as a correction,
causing inconsistent behavior; unify them by introducing a single named constant
(e.g., CORRECTION_THRESHOLD = 0.65) and use that constant in both
detect_correction and extract_correction_context (or have
extract_correction_context call detect_correction and use its boolean result)
and update any docstrings/comments to reflect the unified threshold so future
changes won’t diverge.

In `@Gradata/src/gradata/detection/addition_pattern.py`:
- Around line 153-167: classify_addition currently extracts added_text only when
old is a contiguous substring; update it to mirror is_addition’s subsequence
matching: when old is not empty and not found as a substring in new, walk new
with a two-pointer subsequence match (or reuse the helper from is_addition if
available) to consume characters that match old and build added_text from the
remaining characters in new; ensure this logic still handles empty old/new and
preserves current behavior when old is an exact substring, updating the
added_text variable accordingly in function classify_addition.

In `@Gradata/src/gradata/enhancements/bandits/collaborative_filter.py`:
- Around line 140-169: apply_transfer_boost currently matches only on category
and ignores the description hash required by the RuleFingerprint contract;
update apply_transfer_boost to compute the normalized description hash for the
recommendation exactly as BrainFingerprint.from_lessons does (use
lesson.description.lower().strip().encode() ->
hashlib.sha256(...).hexdigest()[:8]) and then require both rec.category ==
lesson.category and rec_description_hash == lesson_description_hash before
applying the boost; keep the existing boost calculation, caps, rounding, and the
break behavior.

In `@Gradata/src/gradata/enhancements/bandits/contextual_bandit.py`:
- Around line 194-205: In load_arms, validate and sanitize alpha/beta before
constructing RuleArm because random.betavariate(alpha, beta) and expected_value
computations require alpha>0 and beta>0; coerce non-positive or non-numeric
values to a sane default (e.g., 1.0) or skip the arm, and emit a warning using
the module/class logger. Specifically, in load_arms iterate incoming dict d,
extract raw_alpha/raw_beta, check isinstance/float-compatibility and if
raw_alpha <= 0 or raw_beta <= 0 replace with 1.0 (or continue to skip), then
pass the sanitized values into RuleArm(rule_id=..., alpha=sanitized_alpha,
beta=sanitized_beta, ...); also ensure any division in expected_value handles
alpha+beta==0 defensively.
- Around line 91-179: The update method currently accepts an opaque context_key
string that doesn't match the context key produced by _build_context_key used in
select; change update(self, rule_id: str, accepted: bool, context: dict | None =
None) to accept a context dict (or keep context_key optional) and inside update
call self._build_context_key(context) to produce the same canonical key before
reading/writing arm.context_scores (refer to get_or_create_arm,
arm.context_scores, and _build_context_key); also update the update() docstring
to show the dict format and add/update tests to verify round-trip: calling
update with a context dict and then select with the same dict results in a
context boost being applied.

In `@Gradata/src/gradata/enhancements/causal_chains.py`:
- Around line 80-96: get_rule_provenance currently uses a bare dict return type;
tighten it by declaring a structured return type such as dict[str, Any] or a
TypedDict (e.g., RuleProvenance) to reflect the payload shape. Update the
signature of get_rule_provenance to return dict[str, Any] or define a TypedDict
matching keys ("rule_id", "correction_sources", "behavioral_impacts",
"total_evidence") and use that type; import Any or TypedDict from
typing/typing_extensions as needed. Ensure the implementation (which calls
trace_rule_origin and trace_rule_impact) still returns a value compatible with
the new type.

In `@Gradata/src/gradata/enhancements/cluster_manager.py`:
- Around line 194-201: The current loop over state.centroids checks vector
dimension only against the first centroid and then breaks, which can miss
mismatched centroid sizes and cause cosine_similarity(vector, centroid) to fail
later; remove the stray break and instead iterate all entries in
state.centroids, raising a ValueError if len(vector) != len(centroid) for any
centroid (use the existing error message format referencing cid), so every
centroid is validated before proceeding.
- Around line 188-193: The current validation in cluster_manager.py only detects
NaN via "v != v" and therefore lets +/-inf through; update the vector validation
to reject non-finite numbers by importing and using math.isfinite (or
equivalent) in the existing check that iterates over vector elements (the block
that currently raises ValueError("vector contains non-finite values
(NaN/None)")). Replace the any(...) condition to fail when not isinstance(v,
(int, float)) or not math.isfinite(v), and adjust the error message if needed to
reflect rejection of non-finite values (NaN/inf).

In `@Gradata/src/gradata/enhancements/dedup.py`:
- Around line 198-220: The duplicate check and registration must be atomic:
replace the separate is_duplicate/read + register_observation/write in
check_and_register with a single upsert transaction using the observation_dedup
primary key (fingerprint). Implement an INSERT ... ON CONFLICT(fingerprint) DO
UPDATE that sets first_session/first_seen_ts on insert, increments seen_count
(seen_count = seen_count + 1) and updates last_session and last_seen_ts on
conflict, and include a RETURNING clause to get the pre/post row state (e.g.,
first_session and seen_count) so you can derive {"new": bool, "seen_count": int,
"fingerprint": fingerprint} from that single statement; perform this via
conn.execute(...).fetchone() inside the same transaction and remove the separate
is_duplicate/register_observation read/write paths. Ensure functions mentioned
(check_and_register, is_duplicate, register_observation) are updated to use the
upsert/returning approach and still call conn.commit() after the atomic
statement.

In `@Gradata/src/gradata/enhancements/git_backfill.py`:
- Around line 281-287: In backfill_from_git(), the generic exception handler
logs only the exception message via _log.warning("Backfill error on %s: %s",
diff.get("file", "?"), e) which omits the stack trace; update that except
Exception as e block (the handler around diffs in backfill_from_git) to include
the traceback by passing exc_info=True to the logging call (keep the same
message and arguments, add exc_info=True) so errors increment stats.errors but
also record full exception context for debugging.
- Around line 189-201: The loop currently skips when either old_content or
new_content is falsy, which drops legitimate additions/deletions and empty-file
changes; update the conditional to only skip when both git reads failed (e.g.,
both old_result.ok and new_result.ok are false) or when the contents are equal.
In other words, use the _git call results (old_result and new_result) to detect
complete failures and only continue when both reads failed or when old_content
== new_content; keep handling old_content/new_content as strings so additions
(empty old) and deletions (empty new) are preserved.
- Around line 158-188: The glob matching is too strict because patterns like
"*.py" won't match nested paths; before the loop that builds filtered_files
(around the patterns variable and the commit loop using _git and
filtered_files), normalize file_patterns into normalized_patterns by converting
any pattern that does not contain a directory separator (no '/' or '\\') into a
recursive glob (e.g. "**/<pattern>") and leave patterns with separators
unchanged, then use those normalized_patterns when testing files (or match
against Path(f).as_posix() / PurePosixPath to ensure separator consistency) so
Path(...).match() will correctly include nested files; update the reference to
patterns in the filtered_files list comprehension accordingly (the symbols to
change: patterns, file_patterns, and the filtered_files comprehension).

In `@Gradata/src/gradata/enhancements/graduation/agent_graduation.py`:
- Around line 623-630: The current except block in
AgentGraduationTracker.get_agent_rules (and the analogous block in
get_deterministic_rules around lines 854-860) only logs JSON parse errors for
lesson.scope_json but then continues processing, causing corrupted scoped
lessons to apply universally; update the except handlers to log the error and
then skip the lesson (i.e., continue the loop) so a JSONDecodeError/TypeError
will not let the lesson act as a global rule or blocker—locate the
json.loads(lesson.scope_json) blocks in get_agent_rules and
get_deterministic_rules and add a continue after logging.

In `@Gradata/src/gradata/enhancements/graduation/rules_distillation.py`:
- Around line 84-110: The evidence_sources list is built from a set which yields
nondeterministic ordering; change construction in the block that builds the
DistillationProposal (around evidence_sources and cat_entries) to produce a
deterministic sequence (e.g., preserve input order while deduplicating using an
ordered-unique approach or explicitly sort the sources) so
DistillationProposal.evidence_sources is stable across runs.
- Around line 84-86: The selection of representative entry currently uses
representative = cat_entries[-1].description which assumes ordering; update the
logic in rules_distillation.py to either sort cat_entries by entry.date (e.g.,
key=lambda e: e.date or parsed ISO date) before selecting the last element, or
if you cannot guarantee sortable dates, change the comment and variable to
reflect "last encountered" instead of "most recent" (e.g., update the comment
above representative and any uses of representative) so the behavior and naming
are consistent with entries ordering.

In `@Gradata/src/gradata/enhancements/meta_rules.py`:
- Around line 326-374: refresh_meta_rules() currently only revalidates
existing_metas and never invokes the new local synthesis implemented in
discover_meta_rules(), so newly discovered local meta-rules are never created;
update refresh_meta_rules to call discover_meta_rules(lessons,
min_group_size=..., current_session=...) to obtain locally synthesized metas,
then merge those with the revalidated existing_metas (preserving
validation/decay via _apply_decay or existing revalidation logic), deduplicate
by rule signature/description (or whatever identity refresh_meta_rules currently
uses), sort by confidence, and log counts; ensure you call merge_into_meta only
where appropriate and keep the existing revalidation path for existing_metas so
both cloud-validated and locally-discovered metas are returned.

In `@Gradata/src/gradata/enhancements/pipeline_rewriter.py`:
- Around line 70-84: The extraction in _failures_by_description is not safe
because desc = (...).strip() can fail for non-string payloads; change the code
to first retrieve raw_desc = data.get("failed_rule_description") or
data.get("description"), then if raw_desc is not a str skip it (or optionally
cast via str only after checking for None), and only call .strip() on a
confirmed string before using desc to update by_desc; update references to desc
and by_desc in _failures_by_description accordingly so non-string/None payloads
are ignored rather than causing errors.

In `@Gradata/src/gradata/enhancements/profiling/tone_profile.py`:
- Around line 324-346: build_tone_profile currently blends numeric fields but
never applies the promised categorical policy; before returning the ToneProfile,
add explicit merging for greeting_style, cta_style, and opener_type when
existing and existing.sample_count > 0: for each categorical field, set
features.<field> = existing.features.<field> if features.<field> ==
existing.features.<field> (stability), otherwise keep the new features.<field>
(correction signal). Update inside the same conditional that handles EMA (the
block using alpha) so the categorical behavior is applied consistently before
constructing the ToneProfile.

In `@Gradata/src/gradata/enhancements/prompt_synthesizer.py`:
- Around line 47-50: _anchor_of currently returns the raw first 4 chars which
can include uppercase or non-hex chars and break later logic that relies on
_ANCHOR_RE and extract_anchors; change _anchor_of(rule_id) to normalize and
validate: if rule_id is truthy, lowercase it and take the first 4 chars, then if
that 4-char string does not match _ANCHOR_RE, deterministically compute a
fallback hex anchor (e.g. hashlib.sha1(rule_id.encode()).hexdigest()[:4]) and
return that; ensure callers like extract_anchors and inject_brain_rules receive
only lowercase 4-char hex anchors and raise or fallback deterministically for
empty/invalid inputs.

In `@Gradata/src/gradata/enhancements/router_warmstart.py`:
- Around line 75-97: The sqlite3 connection in router_warmstart.py (the conn
created before executing the JSON-select query that uses json_extract and
fetchall with max_events) may leak if an exception occurs during
conn.execute(...) or fetchall(); update the code to guarantee closure by using a
context manager (with sqlite3.connect(str(db_path)) as conn:) or enclosing the
existing try block in a try/finally that always calls conn.close() after the
execute/fetchall operations so the connection is closed even on errors.
- Around line 122-124: Replace the current bare exception log in the except
block that reads "except Exception as e: _log.warning('Warm-start failed: %s',
e)" with a traceback-enabled log; e.g., call _log.warning(..., exc_info=True) or
use _log.exception("Warm-start failed") so the stack trace is captured. Update
the handler in router_warmstart.py where _log is used for the warm-start
exception to include exc_info=True (or swap to _log.exception) and keep the
existing message text to preserve context.

In `@Gradata/src/gradata/enhancements/rule_context_bridge.py`:
- Around line 84-107: The code uses sqlite3.Row.get() (in the
bootstrap_rule_context loop handling variable category) which raises
AttributeError and isn't caught; replace the try/except around category with the
same safe membership pattern used for principle: compute category =
row["category"] if "category" in row else "META" (remove the .get() call and the
incorrect exception handling) so category is read safely from sqlite3.Row
objects without raising AttributeError.

In `@Gradata/src/gradata/enhancements/rule_verifier.py`:
- Around line 39-71: The code crashes when a rule's "category" exists but is
None because should_verify() calls rule_category.upper(); fix by
normalizing/guarding the input in should_verify(): coerce rule_category to a
non-empty string before calling .upper() (e.g., rule_category = (rule_category
or "UNKNOWN") or convert non-str values to str and fall back to "UNKNOWN"), then
perform the membership check against TOOL_RULE_MATRIX as before; you can
alternatively also change get_relevant_rules() to pass rule.get("category") or
None through and rely on the hardened should_verify() to handle None safely.

In `@Gradata/src/gradata/enhancements/scoring/failure_detectors.py`:
- Around line 204-250: In detect_regression_to_mean, replace the hard-coded 0.70
used for evidence["threshold"] and in the Alert message with the blandness_warn
parameter so the function is fully parameterized; update evidence to set
"threshold": blandness_warn and change the message string that currently embeds
"threshold 0.70" to include blandness_warn (formatted similarly, e.g.,
{blandness_warn:.2f} or matching existing formatting) while keeping the severity
logic and other fields (current.blandness_score, prev_blandness,
blandness_delta) unchanged.

In `@Gradata/src/gradata/enhancements/scoring/gate_calibration.py`:
- Around line 145-151: The tie-break logic in the sweep (the if that compares
candidate.f1 to best_f1 and uses self._prefer_higher_on_tie with t >
best_threshold) can drift to the highest threshold when all F1s are 0.0; change
the condition to avoid updating best_threshold on ties when best_f1 == 0.0 by
adding an extra check that prefers keeping self._current_threshold (or fall back
to comparing false_positives/false_negatives) before applying the t >
best_threshold rule, so that when best_f1 == 0.0 you do not automatically move
to the maximum sweep threshold.

In `@Gradata/src/gradata/enhancements/scoring/loop_intelligence.py`:
- Around line 185-208: The DELTA_TAG emission call using
contextlib.suppress(Exception) hides failures; replace the suppress block around
the _emit_event_fn call with a try/except Exception as e: that logs a warning
including exception info (logger.warning("Failed to emit DELTA_TAG
(loop_intelligence) for activity_log_id=%s", row_id, exc_info=True)) and
otherwise swallows the error, ensuring you reference the same payload fields
(activity_type, prospect, company, source, prep_level, detail,
activity_log_id/row_id), tags construction, and session parameter; if no module
logger exists, create one via logging.getLogger(__name__) at module level.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language identifiers to fenced blocks (markdownlint MD040).

Line 80, Line 103, and Line 175 use fenced code blocks without language tags, which will keep markdownlint warnings active.

Suggested patch

-```
+```text
 Layer 2 — Public API        brain.py, cli.py, daemon.py, mcp_server.py
 Layer 1 — Enhancements      enhancements/*, rules/
 Layer 0 — Primitives        _types.py, _db.py, _events.py, _paths.py, _file_lock.py …
 Layer 0 — Patterns          contrib/patterns/*

- +text
INSTINCT → PATTERN → RULE → META_RULE
↓ ↓ ↓
KILLED INSTINCT ARCHIVE (contradiction / decay / graduation)

-```
+```text
<type>(<scope>): <imperative description>

[optional body — what + why, not how]

[optional trailers]

</details>


Also applies to: 103-107, 175-181

<details>
<summary>🧰 Tools</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>

[warning] 80-80: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

</details>

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @Gradata/AGENTS.md around lines 80 - 85, The markdown has three fenced code
blocks lacking language identifiers (the blocks containing "Layer 2 — Public API
brain.py, cli.py, daemon.py, mcp_server.py", "INSTINCT → PATTERN → RULE →
META_RULE", and "(): "); add a language tag
(e.g., text) to each opening fence so the blocks become text ... ``` to
silence markdownlint MD040 warnings and keep formatting consistent.

</details>

<!-- fingerprinting:phantom:poseidon:hawk:904d075c-04e1-42ab-ba41-a804662c7496 -->

<!-- d98c2f50 -->

<!-- This is an auto-generated comment by CodeRabbit -->

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Avoid branch-relative state in the changelog.

“33 commits ahead of public origin/main. Not yet pushed.” will be wrong as soon as this branch is rebased, pushed, or merged. That kind of status belongs in the PR description, not in release notes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/CHANGELOG.md` around lines 3 - 6, The changelog entry in CHANGELOG.md
contains branch-relative state ("33 commits ahead of public `origin/main`. Not
yet pushed.") which will become incorrect; remove that sentence from the
Unreleased section and replace it with a stable changelog-only note (or nothing)
so the file only contains release/change details, e.g., keep the "##
[Unreleased] — post-0.6.0 (2026-04-23 → 2026-04-24)" header and commit-based
notes but delete the branch-status line; update the file by editing CHANGELOG.md
to eliminate any references to branch or push status.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

This migration name does not match the codebase.

The migration referenced elsewhere in this PR is 002_add_event_identity.py, not 002_event_id_device_id_content_hash. Keeping the changelog aligned with the actual migration filenames will make rollout/debugging much easier.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/CHANGELOG.md` around lines 13 - 15, Update the CHANGELOG entry to
match the actual migration filename used in the codebase: replace the incorrect
migration name `002_event_id_device_id_content_hash` with
`002_add_event_identity.py` and ensure the description corresponds to the
implementation in `002_add_event_identity.py`; also confirm the adjoining entry
for `003_add_sync_state` remains accurate and references the real migration
filename used in the PR.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a blank line after the heading to satisfy MD022.

There should be an empty line after the ### 1. Local-first stays the source of truth heading before the paragraph at Line 22.

Suggested patch

 ### 1. Local-first stays the source of truth
+
 SDK writes to local SQLite + jsonl and runs the full learning loop (graduation, synthesis, rule-to-hook promotion) locally. Cloud is a **sync target + dashboard + future team + future shared-corpus surface** — not a gate on the local loop. Do NOT migrate SDK storage to Postgres. Reasons: privacy, offline, open source, speed.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	### 1. Local-first stays the source of truth
	SDK writes to local SQLite + jsonl. Cloud is a **sync target + shared meta-rule source + proprietary scoring service**. Do NOT migrate SDK storage to Postgres. Reasons: privacy, offline, open source, speed.
	SDK writes to local SQLite + jsonl and runs the full learning loop (graduation, synthesis, rule-to-hook promotion) locally. Cloud is a **sync target + dashboard + future team + future shared-corpus surface** — not a gate on the local loop. Do NOT migrate SDK storage to Postgres. Reasons: privacy, offline, open source, speed.
	### 1. Local-first stays the source of truth
	SDK writes to local SQLite + jsonl and runs the full learning loop (graduation, synthesis, rule-to-hook promotion) locally. Cloud is a **sync target + dashboard + future team + future shared-corpus surface** — not a gate on the local loop. Do NOT migrate SDK storage to Postgres. Reasons: privacy, offline, open source, speed.

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 21-21: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/docs/architecture/multi-tenant-future-proofing.md` around lines 21 -
23, Add a single blank line immediately after the heading "### 1. Local-first
stays the source of truth" so the paragraph starting with "SDK writes to local
SQLite + jsonl..." is separated by an empty line; update the markdown around
that heading in the document to satisfy MD022 while keeping the heading text and
paragraph content unchanged.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix contradictory meta-rule ownership in this doc page.

Line 3 says synthesis is local, but Line 26 still describes meta-rules as cloud-synthesized. Please align the Brain detail bullet to avoid conflicting guidance.

✏️ Suggested doc fix

-- **Meta-rules** — cloud-synthesized principles with their source rules.
+- **Meta-rules** — locally synthesized principles with their source rules (rendered in Cloud).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/docs/cloud/dashboard.md` at line 3, The doc contradicts itself about
meta-rule synthesis: update the "Brain detail" bullet that currently describes
meta-rules as cloud-synthesized to match the earlier statement that "Meta-rule
synthesis runs locally in the SDK" — locate the bullet that mentions
"meta-rules" or "cloud-synthesized" and change its wording to indicate synthesis
happens locally (e.g., "meta-rules are synthesized locally by the SDK and the
dashboard renders the results") or remove the cloud-synthesis claim so both
passages consistently state local synthesis.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Redact the full PEM block, not just the header.

The private-key pattern only replaces -----BEGIN ...-----, so the base64 payload and -----END ...----- footer still get written to observations.jsonl. That is still a secret leak.

Safer pattern

-    (_re.compile(r"-----BEGIN [A-Z ]+-----"), "[PRIVATE_KEY]"),
+    (
+        _re.compile(
+            r"-----BEGIN [A-Z ]+-----[\s\S]+?-----END [A-Z ]+-----",
+            _re.MULTILINE,
+        ),
+        "[PRIVATE_KEY]",
+    ),

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	_PII_PATTERNS = [
	(_re.compile(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'), '[EMAIL]'),
	(_re.compile(r'(?:\+?1[\s\-.]?)?\(?\d{3}\)?[\s\-.]?\d{3}[\s\-.]?\d{4}\b'), '[PHONE]'),
	(_re.compile(r'\b(?:sk-|api[_-]?key[=:]\s*)[A-Za-z0-9_-]{10,}\b', _re.I), '[API_KEY]'),
	(_re.compile(r'\b(?:token[=:]\s*|bearer\s+)[A-Za-z0-9_.-]{10,}\b', _re.I), '[TOKEN]'),
	(_re.compile(r'\b(?:password[=:]\s*|passwd[=:]\s*)\S+', _re.I), '[PASSWORD]'),
	(_re.compile(r'-----BEGIN [A-Z ]+-----'), '[PRIVATE_KEY]'),
	(_re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"), "[EMAIL]"),
	(_re.compile(r"(?:\+?1[\s\-.]?)?\(?\d{3}\)?[\s\-.]?\d{3}[\s\-.]?\d{4}\b"), "[PHONE]"),
	(_re.compile(r"\b(?:sk-|api[_-]?key[=:]\s*)[A-Za-z0-9_-]{10,}\b", _re.I), "[API_KEY]"),
	(_re.compile(r"\b(?:token[=:]\s*|bearer\s+)[A-Za-z0-9_.-]{10,}\b", _re.I), "[TOKEN]"),
	(_re.compile(r"\b(?:password[=:]\s*|passwd[=:]\s*)\S+", _re.I), "[PASSWORD]"),
	(_re.compile(r"-----BEGIN [A-Z ]+-----"), "[PRIVATE_KEY]"),
	_PII_PATTERNS = [
	(_re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"), "[EMAIL]"),
	(_re.compile(r"(?:\+?1[\s\-.]?)?\(?\d{3}\)?[\s\-.]?\d{3}[\s\-.]?\d{4}\b"), "[PHONE]"),
	(_re.compile(r"\b(?:sk-|api[_-]?key[=:]\s*)[A-Za-z0-9_-]{10,}\b", _re.I), "[API_KEY]"),
	(_re.compile(r"\b(?:token[=:]\s*|bearer\s+)[A-Za-z0-9_.-]{10,}\b", _re.I), "[TOKEN]"),
	(_re.compile(r"\b(?:password[=:]\s*|passwd[=:]\s*)\S+", _re.I), "[PASSWORD]"),
	(
	_re.compile(
	r"-----BEGIN [A-Z ]+-----[\s\S]+?-----END [A-Z ]+-----",
	_re.MULTILINE,
	),
	"[PRIVATE_KEY]",
	),

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/enhancements/observation_hooks.py` around lines 81 - 87,
The PEM redaction is incomplete: update the _PII_PATTERNS entry that currently
matches only the "-----BEGIN ...-----" header so it matches and replaces the
entire PEM block (header, base64 body, and "-----END ...-----" footer). Replace
that tuple in _PII_PATTERNS with a regex that spans multiple lines (use DOTALL /
re.S) and uses non-greedy matching between the BEGIN and END markers (e.g., a
pattern like "-----BEGIN [A-Z ]+-----.*?-----END [A-Z ]+-----") and keep the
replacement token "[PRIVATE_KEY]"; ensure the regex flag _re.S is applied so
multi-line PEM blocks are fully redacted.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Minor: ensure profile.task_type is allowlisted/sanitized before prompt interpolation.

generate_tone_prompt() interpolates profile.task_type directly into the generated prompt text. If task_type can ever be influenced by users (or derived from untrusted sources), it’s a prompt-injection surface. At minimum, ensure it’s from a closed set of known task types.

Also applies to: 463-503

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/enhancements/profiling/tone_profile.py` around lines 502
- 505, The prompt generation interpolates profile.task_type directly in
generate_tone_prompt, creating a prompt-injection risk; update
generate_tone_prompt to validate profile.task_type against a closed allowlist
(e.g., a set/map of known task types) and replace or map any unrecognized value
to a safe default like "unknown" or a canonical mapped label, and also
strip/escape any control/newline characters before interpolation; reference the
generate_tone_prompt function and the profile.task_type use (lines ~463-503 and
the lines building the lines list) when applying this change.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Validate cached synth output and write it atomically.

_read_cache() trusts whatever is on disk, while _write_cache() does a direct write_text(). A partial write or concurrent read can therefore leave a truncated cache entry that gets returned as-is on the next call, bypassing the malformed-output fallback entirely.

Suggested hardening

 def _read_cache(brain_dir: Path, cache_key: str) -> str | None:
     path = _cache_path(brain_dir, cache_key)
     if not path.is_file():
         return None
     try:
-        return path.read_text(encoding="utf-8")
+        cached = path.read_text(encoding="utf-8")
+        block = _extract_wisdom_block(cached)
+        return block if block and len(block) >= 50 else None
     except OSError:
         return None
@@
 def _write_cache(brain_dir: Path, cache_key: str, content: str) -> None:
     try:
         cache_dir = brain_dir / CACHE_DIRNAME
         cache_dir.mkdir(parents=True, exist_ok=True)
-        _cache_path(brain_dir, cache_key).write_text(content, encoding="utf-8")
+        path = _cache_path(brain_dir, cache_key)
+        tmp = path.with_suffix(f"{path.suffix}.tmp")
+        tmp.write_text(content, encoding="utf-8")
+        os.replace(tmp, path)
     except OSError as exc:
         _log.debug("synth cache write failed: %s", exc)

Also applies to: 326-329

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/enhancements/rule_synthesizer.py` around lines 97 - 112,
_read_cache currently returns whatever is on disk and _write_cache uses
write_text directly, which allows readers to see truncated partial writes;
change _write_cache to perform an atomic write to a temporary file (e.g., create
temp file in brain_dir/CACHE_DIRNAME, write and flush + os.fsync the file, then
os.replace to the final path, and fsync the containing directory) and have
_read_cache validate the read content before returning (at minimum reject
empty/truncated text and any parse/validation errors your synth logic expects so
callers fall back to malformed-output handling); use the existing helpers
_cache_path and CACHE_DIRNAME to locate files and handle OSError consistently.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Log demotion event emit failures instead of suppressing all exceptions

contextlib.suppress(Exception) here can hide broken telemetry/state transitions during demotion. Please switch to explicit try/except Exception with warning logs.

Proposed fix

-                with contextlib.suppress(Exception):
-                    brain.emit(
+                try:
+                    brain.emit(
                         "RULE_TO_HOOK_REMOVED",
                         source,
                         {
                             "slug": slug,
                             "hook_path": str(target),
                         },
                     )
+                except Exception:
+                    logger.warning("Failed to emit RULE_TO_HOOK_REMOVED", exc_info=True)
@@
-                with contextlib.suppress(Exception):
-                    brain.emit(
+                try:
+                    brain.emit(
                         HOOK_DEMOTED,
                         source,
                         {
                             "slug": slug,
                             "hook_path": str(target),
                         },
                     )
+                except Exception:
+                    logger.warning("Failed to emit HOOK_DEMOTED", exc_info=True)

As per coding guidelines: "Never use bare except: pass — use typed exceptions or at minimum log with logger.warning(..., exc_info=True)".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/enhancements/rule_to_hook.py` around lines 824 - 846,
Replace the two contextlib.suppress(Exception) blocks that call brain.emit for
"RULE_TO_HOOK_REMOVED" and HOOK_DEMOTED with explicit try/except Exception
handlers: catch Exception around each brain.emit call (the emits referencing
variables source, slug, and target) and in the except log a warning (e.g.,
logger.warning or processLogger.warning) including a clear message and
exc_info=True so the stack/exception is recorded instead of being silently
suppressed; ensure the warning message names the event (RULE_TO_HOOK_REMOVED or
HOOK_DEMOTED) and the slug/hook_path for context.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Align the summary table with the detailed audit above.

Lines 88-90 already identify concrete callers and conclude KEEP for notifications.py, onboard.py, and safety.py, but this table still says UNVERIFIED. That flips the document's own conclusion for the highest-level summary most readers will rely on.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/VERIFIED_LEANOUT.md` around lines 125 - 128, Update the summary table
entries to match the detailed audit: change `notifications.py`, `onboard.py`,
and `safety.py` from "pragmatist DELETE | UNVERIFIED" to reflect the audit's
KEEP decision (e.g., `notifications.py | KEEP`, `onboard.py | KEEP`, `safety.py
| KEEP`), and ensure `daemon.py` remains "DELETE_OR_MOVE | MOVE only — Phase B
just wired lock support" if that audit conclusion stands; make the table's
status strings and notes identical to the conclusions in the detailed lines
88–90 so the top-level summary does not contradict the detailed audit.

[coderabbitai]

Review continued from previous batch...

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Don’t check in a local archived dashboard with developer-specific paths.

These constants point at one Windows profile, so the script is broken as committed for every other machine and also leaks local workspace layout. If this is only a personal archive, it should stay out of the repo; otherwise the paths need to come from CLI/env/config.

Based on learnings Never commit scratch files like .tmp/, .archive/, sessions/handoff-*.md, or files named 0 or BrainDetail — ensure they are in .gitignore.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/.archive/dashboard_streamlit_deprecated_2026-04-23.py` around lines
20 - 26, The hard-coded developer-specific Windows paths (BRAIN_DIR, DB_PATH,
EVENTS_PATH, LESSONS_PATH, PROSPECTS_DIR, BRIEF_PATH, TASKS_DIR) must not be
committed; replace them with configurable inputs and safe defaults: read base
path from an environment variable or CLI/config (e.g., BRAIN_DIR from
os.environ["BRAIN_DIR"] or a passed argument) and construct DB_PATH,
EVENTS_PATH, LESSONS_PATH, PROSPECTS_DIR, BRIEF_PATH, TASKS_DIR from that base
(falling back to a portable default like Path.home()/".gradata" when unset), and
remove or move the archived file from the repo and add it to .gitignore if it’s
personal. Ensure any code that imports these constants (search for usages of
BRAIN_DIR, DB_PATH, EVENTS_PATH, etc.) continues to work with the new
configuration API.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Log rule-graph save failures instead of swallowing them.

Line 702 suppresses every exception from _rule_graph.save(). If persistence fails here, the graph can diverge from disk with no signal in logs, which makes later conflict/debugging state very hard to trust.

Suggested change

-    if hasattr(brain, "_rule_graph") and brain._rule_graph:
-        with contextlib.suppress(Exception):
-            brain._rule_graph.save()
+    if hasattr(brain, "_rule_graph") and brain._rule_graph:
+        try:
+            brain._rule_graph.save()
+        except Exception:
+            _log.warning("rule_graph save failed", exc_info=True)

As per coding guidelines Never use bare except: pass — use typed exceptions or at minimum log with logger.warning(..., exc_info=True).

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# Persist rule graph
	if hasattr(brain, '_rule_graph') and brain._rule_graph:
	if hasattr(brain, "_rule_graph") and brain._rule_graph:
	with contextlib.suppress(Exception):
	brain._rule_graph.save()
	# Persist rule graph
	if hasattr(brain, "_rule_graph") and brain._rule_graph:
	try:
	brain._rule_graph.save()
	except Exception:
	_log.warning("rule_graph save failed", exc_info=True)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/_core.py` around lines 700 - 703, Replace the blanket
suppression around brain._rule_graph.save() so failures are logged: instead of
using contextlib.suppress(Exception) around brain._rule_graph.save(), wrap the
call in a try/except Exception as e and call the module logger (or existing
logger instance) with a warning or error message that includes exception context
(e.g., logger.warning("Failed to save rule graph", exc_info=True) or similar).
Keep the call target brain._rule_graph.save() and remove the silent swallow so
failures are visible in logs.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Read final_text when deriving blandness from correction events.

cloud_sync_tick() forwards events.data_json rows, and brain_correct() stores corrected output under final_text, not final. With the current comprehension, the new hook-safe sync path uploads blandness_score = 0.0 for sessions that actually contain corrections.

Suggested change

-            finals = [c.get("final", "") for c in session_corrections if c.get("final")]
+            finals = [
+                c.get("final_text") or c.get("final", "")
+                for c in session_corrections
+                if c.get("final_text") or c.get("final")
+            ]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/_core.py` around lines 1293 - 1298, The comprehension
that builds finals from session_corrections is reading the wrong key ("final")
so blandness is computed as 0.0; change it to read "final_text" (and you can
keep "final" as a fallback for compatibility) so compute_blandness receives the
corrected outputs—update the finals list comprehension in the block that calls
compute_blandness (refer to session_corrections, compute_blandness,
cloud_sync_tick(), and brain_correct()) to use c.get("final_text",
c.get("final", "")) and only include truthy values.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Validate session_id before turning it into a filesystem path.

Path(brain_dir) / "sessions" / session_id accepts .. and absolute segments, so a caller-controlled session id can make log_turn() append outside the brain directory. With transcripts enabled, that's an arbitrary file write primitive.

🔒 Suggested fix

+import re
@@
+_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
@@
 def _session_dir(brain_dir: str, session_id: str) -> Path:
+    if not _SESSION_ID_RE.fullmatch(session_id):
+        raise ValueError("invalid session_id")
     return Path(brain_dir) / "sessions" / session_id

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/_transcript.py` around lines 46 - 51, The _session_dir
and _transcript_path helpers currently join a caller-controlled session_id into
a filesystem path; validate and sanitize session_id before using it: ensure
session_id is not absolute (reject Path(session_id).is_absolute()), does not
contain path separators or parent segments (reject if "/" or "\\" present or if
any part == ".."), and restrict characters (e.g., allow only a safe regex like
alphanumerics, dot, dash, underscore) or else raise an exception; update
_session_dir (and any callers like _transcript_path) to perform this validation
and only use the vetted session_id when building the Path to prevent
path-traversal/absolute-path writes.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Resolve the skill-export brain once and reuse it.

This path mixes _resolve_brain_root() with _get_brain(), but those helpers do not share the same fallback. Without GRADATA_BRAIN or --brain-dir, the command can read lessons from the cwd brain while exporting against brain/, which means gradata skill export can target the wrong brain.

Suggested change

-    brain_root = _resolve_brain_root(args)
-    lessons_path: Path | None = None
-    try:
-        brain = _get_brain(args)
-        lessons_path = brain._find_lessons_path()
-    except Exception:
-        lessons_path = None
+    lessons_path: Path | None = None
+    try:
+        brain = _get_brain(args)
+        brain_root = brain.dir
+        lessons_path = brain._find_lessons_path()
+    except Exception:
+        brain_root = _resolve_brain_root(args)
+        lessons_path = None

Based on learnings cli.py env-first brain resolution (GRADATA_BRAIN > --brain-dir > cwd).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/src/gradata/cli.py` around lines 1112 - 1117, Resolve the brain once
via _get_brain(args) and reuse it for both brain_root and lessons_path instead
of calling _resolve_brain_root() and _get_brain() separately; call brain =
_get_brain(args) first, set brain_root from the resolved brain object (e.g.,
brain.root or equivalent attribute) and then call lessons_path =
brain._find_lessons_path(), ensuring the env-first resolution (GRADATA_BRAIN >
--brain-dir > cwd) is honored and the same brain is used for export and lesson
discovery.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@Gradata/VERIFIED_LEANOUT.md`:
- Around line 37-43: The decision log contains conflicting verdicts for
enhancements/graduation/scoring.py (one saying "✅ likely safe" and another
saying "NOT safe to delete" after tests/test_graduation_scoring.py failure);
update VERIFIED_LEANOUT.md so only the final, failing verdict remains: remove
the earlier "✅ likely safe" entry (the block at or around the section labeled
`enhancements/graduation/scoring.py` near lines 37-43) and keep the failing
verdict text from the section that references tests/test_graduation_scoring.py
(lines ~155-170), ensuring the log states the file is NOT safe to delete and
includes the test failure reference.
- Around line 98-101: Two fenced code blocks in VERIFIED_LEANOUT.md are missing
language tags (MD040) — the block containing the pytest summary "3970 passed, 5
skipped..." and the block with "ModuleNotFoundError: No module named
'gradata.enhancements.graduation.scoring'". Edit those two code fences (and the
similar block at lines ~159-162) to add a language tag such as text (or bash if
you prefer shell output): replace ``` with ```text for the blocks that include
the pytest output and the ModuleNotFoundError to satisfy markdown lint and
improve readability.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 0060b50f-010a-4d80-bf5e-b2c750489bf8

📥 Commits

Reviewing files that changed from the base of the PR and between 86d8fe2 and 6333c05.

📒 Files selected for processing (1)

• Gradata/VERIFIED_LEANOUT.md

📜 Review details

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: Gradata
Repo: Gradata/gradata PR: 0
File: :0-0
Timestamp: 2026-04-17T17:18:07.439Z
Learning: In PR `#102` (gradata/gradata), Round 2 addressed: cli.py env-first brain resolution (GRADATA_BRAIN > --brain-dir > cwd), _tenant.py corrupt .tenant_id overwrite, _env_int default clamping to minimum, and _events.py tenant-scoped fallback SELECT for dedup. All ruff and 99 tests green after these fixes.

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Never import from higher layers into lower layers; Layer 0 must not import from Layer 1 or Layer 2 (brain.py, cli.py, daemon.py, mcp_server.py)

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Never write `rule_graph.json` non-atomically - use atomic-write helper to prevent poisoned brain from mid-write crashes

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Add failing test first when fixing bugs, then fix; test must remain green after fix

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Run smallest relevant test after each change, e.g., `pytest tests/test_brain.py -xvs` before full suite

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Honor strict layering rule and flag in PR description if changes cross Layer 0 → 2 boundary

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Never assume thread-safety on `Brain` - concurrent writes from daemon.py (HTTP) and mcp_server.py (stdio) require process-level coordination

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Never commit scratch files like `.tmp/`, `.archive/`, `sessions/handoff-*.md`, or files literally named `0` or `BrainDetail`

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Never leak private-sibling paths from ../Sprites/ or ../Hausgem/ into public gradata/* code or docs

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Never push to origin/main directly - all changes go through PR review

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Commit messages must use format: <type>(<scope>): <imperative description> with types: feat, fix, docs, refactor, perf, test, chore, revert

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: PR description must include: Summary (1-3 sentences), Test plan (tests added/changed and passing), Layering check (no Layer 0 → 2 imports), Risk (backwards-compat concerns, schema migrations, runtime contract changes)

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Brain.correct() is the canonical entry point for the headline product promise - corrections extract behavioral rules

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Single source of truth: consolidate duplicate-purpose modules instead of creating a third variant

Learnt from: CR
Repo: Gradata/gradata

Timestamp: 2026-04-30T16:58:50.391Z
Learning: Read target file in full before modifying it

📚 Learning: 2026-04-17T17:18:07.439Z

Learnt from: Gradata
Repo: Gradata/gradata PR: 0
File: :0-0
Timestamp: 2026-04-17T17:18:07.439Z
Learning: In PR `#102` (gradata/gradata), Round 2 addressed: cli.py env-first brain resolution (GRADATA_BRAIN > --brain-dir > cwd), _tenant.py corrupt .tenant_id overwrite, _env_int default clamping to minimum, and _events.py tenant-scoped fallback SELECT for dedup. All ruff and 99 tests green after these fixes.

Applied to files:

• Gradata/VERIFIED_LEANOUT.md

🪛 LanguageTool

Gradata/VERIFIED_LEANOUT.md

[style] ~55-~55: Consider a different adjective to strengthen your wording.
Context: ... fold into Brain → VERIFIED: ⚠️ NEEDS DEEPER LOOK Council's "fold mixin into Brain"...

(DEEP_PROFOUND)

---

[style] ~61-~61: To elevate your writing and sound more professional, you can use different wording here.
Context: ...y` have other consumers? (Did not have time to verify in this pass. Flagged for nex...

(DIDNT_HAVE_THE_TIME)

---

[style] ~164-~164: Consider replacing this word to strengthen your wording.
Context: ... callers) but the test file IS a caller and represents shipped intent. **Updated v...

(AND_THAT)

🪛 markdownlint-cli2 (0.22.1)

Gradata/VERIFIED_LEANOUT.md

[warning] 7-7: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

[warning] 98-98: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

[warning] 140-140: Spaces inside emphasis markers

(MD037, no-space-in-emphasis)

---

[warning] 159-159: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (1)

Gradata/VERIFIED_LEANOUT.md (1)

126-128: Summary table still contradicts detailed audit for three modules.

This was already flagged earlier: Line 126-128 should match Line 88-90 (KEEP for notifications.py, onboard.py, safety.py) instead of UNVERIFIED.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Conflicting verdict for graduation/scoring.py makes the decision log unsafe to act on.

Line 37-43 says “✅ likely safe,” but Line 166-170 explicitly updates this to “NOT safe to delete” after a real failure (tests/test_graduation_scoring.py). Keep only one final verdict to prevent accidental deletion decisions.

Suggested patch

-### `enhancements/graduation/scoring.py` — RECOMMENDED: DELETE  →  VERIFIED: ✅ likely safe
+### `enhancements/graduation/scoring.py` — RECOMMENDED: DELETE  →  VERIFIED: ❌ UNSAFE

-- 0 hits across whole repo for `graduation.scoring` import (verified via search_files)
-- Only 5 hits, all in docs / dist artifacts / LEANOUT_PLAN itself
-
-**Correct action**: Probably safe to delete. Still recommend running pytest after deletion to confirm no dynamic imports.
+- Initial grep suggested no production importers.
+- Deletion attempt failed immediately because `tests/test_graduation_scoring.py` imports this module.
+
+**Correct action**: Do not delete in this phase. If removal is desired, retire/migrate the feature and its dedicated tests first.

Also applies to: 155-170

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/VERIFIED_LEANOUT.md` around lines 37 - 43, The decision log contains
conflicting verdicts for enhancements/graduation/scoring.py (one saying "✅
likely safe" and another saying "NOT safe to delete" after
tests/test_graduation_scoring.py failure); update VERIFIED_LEANOUT.md so only
the final, failing verdict remains: remove the earlier "✅ likely safe" entry
(the block at or around the section labeled `enhancements/graduation/scoring.py`
near lines 37-43) and keep the failing verdict text from the section that
references tests/test_graduation_scoring.py (lines ~155-170), ensuring the log
states the file is NOT safe to delete and includes the test failure reference.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add language tags to fenced code blocks to satisfy markdown lint and improve readability.

MD040 is triggered in both blocks; use text (or bash if shell output formatting is intended).

Suggested patch

-```
+```text
 3970 passed, 5 skipped, 5 deselected, 4 warnings in 274.91s (4:34)
 exit=0

...
- +text
ModuleNotFoundError: No module named 'gradata.enhancements.graduation.scoring'
ERROR tests/test_graduation_scoring.py

Also applies to: 159-162

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 98-98: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Gradata/VERIFIED_LEANOUT.md` around lines 98 - 101, Two fenced code blocks in
VERIFIED_LEANOUT.md are missing language tags (MD040) — the block containing the
pytest summary "3970 passed, 5 skipped..." and the block with
"ModuleNotFoundError: No module named
'gradata.enhancements.graduation.scoring'". Edit those two code fences (and the
similar block at lines ~159-162) to add a language tag such as text (or bash if
you prefer shell output): replace ``` with ```text for the blocks that include
the pytest output and the ModuleNotFoundError to satisfy markdown lint and
improve readability.

[Gradata]

Superseded by clean rebase as rebase/council-phase-c.