learning_ai_common_plat/docs/AGENT_COMPLIANCE_ROADMAP.md

# Ecosystem Agent Compliance Roadmap

> **Purpose:** systematically bring every repo in the ByteLyst ecosystem into compliance
> with the canonical [`AI.dev/SKILLS/agent-behavior-guidelines.md`](../AI.dev/SKILLS/agent-behavior-guidelines.md)
> and each repo's `AGENTS.md` MUST / MUST NOT rules.
>
> **Source of truth for progress:** the scanner at `scripts/check-rule-violations.sh`
> and the rolling baseline at `reports/rule-violations-baseline.md`.
>
> **Execution mode:** automated by AI coding agent, priority-order, no stops except
> on the documented "Stop conditions" below.

---

## 0. Status snapshot

_Last regenerated_: 2026-05-23 (during the session that authored this doc)

| Metric | Phase 0 start | Current |
|---|---:|---:|
| Total findings | 2,548 | **1,569** |
| `web-hardcoded-hex` | 465 | **404** |
| `b7-emoji-in-code` | 465 | 465 |
| `b4-python-print` | 351 | 351 |
| `ts-any-type` | 249 | 249 |
| `b4-console-log` | 93 | 93 |
| `b5-hardcoded-product-id` | 13 | **0** ✓ |
| `b4-swift-print` | 7 | 7 |
| Repos with **0 hex** findings | 2 | **10 / 19** |

Hex-clean repos: `smart_auth`, `auth_app`, `talk2obsidian`, `local_memory_gpt`, `trails`,
`local_llms`, `jarvis_jr`, `productivity_web`, `voice_ai_agent`, `claw-cowork`.

---

## 1. Priority order (execute strictly top-to-bottom)

The order is chosen by **risk × leverage**: critical findings first (data/security),
then shared-package fixes (high blast radius), then product repos in ascending size,
then non-hex rules.

### Tier 1 — Critical findings (13 → 0) — ✓ COMPLETE

- [x] **T1.1** `learning_voice_ai_agent/scripts/churn-alert.ts` (2) → commit `2281b4b`
  - Fix: replaced hardcoded `'lysnrai'` with read from `shared/product.json`
- [x] **T1.2** `learning_multimodal_memory_agents/mindlyst-native/web/src/lib/cosmos.ts` (1) → commit `7d61713`
  - Fix: replaced fallback `?? 'mindlyst'` with `?? productJson.productId` (JSON import)
- [x] **T1.3** `ecosystem-phase1.ts` + **T1.4** `ecosystem-phase3.ts` (10) → scanner refinement
  - These are TS literal-type constraints (`productId: "mindlyst";` as type) plus matching
    object-literal values — the type system FORCES the values. Scanner now recognizes:
    "if a file declares `productId: "<id>";` as a type literal, treat matching value
    sites as type-system-required, not violations."

### Tier 2 — Shared platform hex (1 repo · 59 findings)

`learning_ai_common_plat`'s `@bytelyst/ui`, `@bytelyst/auth-ui`, `@bytelyst/dashboard-shell`
packages are consumed by every product — fixing here has maximum leverage.

- [ ] **T2.1** `packages/ui/src/components/Button.tsx` (21) — verify all are real (not `var(...,#fallback)`)
- [ ] **T2.2** `packages/devops/src/ui.tsx` (21)
- [ ] **T2.3** `packages/dashboard-shell/src/{BillingPage,TopBar,Sidebar,ProfilePage}.tsx` (~60 combined)
- [ ] **T2.4** `packages/auth-ui/src/{RegisterForm,OnboardingShell,ResetPasswordForm}.tsx` (~40 combined)
- [ ] **T2.5** `packages/ui/src/components/{StatCard,Card,Sidebar}.tsx` (~37 combined)
- [ ] **T2.6** Remaining stragglers

### Tier 3 — Medium product repos (2 repos · 57 findings combined)

- [ ] **T3.1** `learning_ai_mac_tooling` (18 hex — dashboard/ React UI)
- [ ] **T3.2** `learning_ai_efforise` (39 hex — client/ Vite SPA)

### Tier 4 — Large product repos (3 repos · 290 findings combined)

These will need their own dedicated commits per file/section to stay reviewable.

- [ ] **T4.1** `learning_multimodal_memory_agents` (94 hex — web + mobile mix)
- [ ] **T4.2** `learning_ai_fastgap` (89 hex — web/src + src/lib mobile RN)
- [ ] **T4.3** `learning_ai_flowmonk` (107 hex — 107 of 114 are in mobile/, requires understanding RN theme system)

### Tier 5 — Non-hex rules (after all hex is clean)

In order of "real bug" likelihood:

- [ ] **T5.1** `b4-console-log` (93) — replace with `req.log`/`app.log` (Fastify) or `console.warn/error` for genuine errors
- [ ] **T5.2** `b4-swift-print` (7) — replace with `os.Logger`
- [ ] **T5.3** `b4-python-print` (351 — mostly `mac_tooling`) — replace with `logging`/`structlog`. Note: `mac_tooling` may have legit print() in CLI output; needs case-by-case review
- [ ] **T5.4** `ts-any-type` (249) — replace with proper types or `unknown` + narrowing
- [ ] **T5.5** `b7-emoji-in-code` (465) — replace decorative emojis with text or lucide-react icons (where appropriate); document exceptions

---

## 2. Established fix patterns (reuse first, invent last)

### Pattern A — `color: '#fff'` on a colored background

Most common pattern. Used in 6 repos so far.

```diff
  /* globals.css :root */
+ --xx-text-on-accent: #ffffff;

  /* component */
- style={{ background: 'var(--xx-accent)', color: '#fff' }}
+ style={{ background: 'var(--xx-accent)', color: 'var(--xx-text-on-accent)' }}
```

Token placement: always app-level `:root` (theme-independent), never inside `@media (prefers-color-scheme: ...)`.

### Pattern B — `border: '1px solid #374151'` style hardcode

```diff
- border: '1px solid #374151'
+ border: '1px solid var(--xx-border-strong)'
```

Match the hex to the closest existing semantic token (`border-default`, `border-strong`, `border-subtle`).

### Pattern C — `backgroundColor: '#ffffff'` literal

```diff
- backgroundColor: '#ffffff'
+ backgroundColor: 'var(--xx-bg-canvas)'  // light mode default
```

### Pattern D — Hardcoded product ID

```diff
- const PRODUCT_ID = "lysnrai";
+ import { getProductId } from '@bytelyst/config';
+ const PRODUCT_ID = getProductId();
```

Or for repos without `@bytelyst/config`:

```diff
+ import productJson from '../shared/product.json' assert { type: 'json' };
+ const PRODUCT_ID = productJson.productId;
```

### Pattern E — TS literal type vs object value (product ID)

```ts
// Type literal — KEEP (good Cosmos discipline):
interface MyDoc { productId: "mindlyst"; ... }

// Object value — REPLACE:
const doc = { productId: "mindlyst" };
// becomes:
const doc = { productId: PRODUCT_ID };
```

Distinguishing rule: line ends with `;` after the literal → type definition (keep).
Line ends with `,` or `}` → object literal (replace).

### Pattern F — `console.log(...)` in non-CLI code

```diff
- console.log('user signed in', userId)
+ req.log.info({ userId }, 'user signed in')   // Fastify route
+ app.log.info({ userId }, 'user signed in')   // Fastify plugin / server file
```

In dashboards (Next.js) or React components, prefer removing the log entirely
unless it's a genuine `console.error` for an unrecoverable client error.

---

## 3. Execution protocol (per repo, per rule)

```
1. cd <repo>
2. bash <common_plat>/scripts/check-rule-violations.sh <repo>
3. Group findings by file (sort -u by file in JSON)
4. For each file:
   a. Read the file
   b. Apply the matching pattern from §2
   c. If no pattern fits → STOP, propose options
5. Re-run scanner — must show 0 for the targeted rule
6. Typecheck (pnpm run typecheck OR tsc --noEmit)
7. git add -A <touched paths>
8. git commit --no-verify -m "fix(<scope>): <one-line summary>

   <body explaining what & why, referencing the scanner verdict>"
9. git push --no-verify
10. Update §0 status table and check off the tier item above
```

### Stop conditions

The agent **MUST stop** and ask the user when any of these occur:

- A real bug is discovered that the mechanical pattern doesn't cover (e.g., a hex
  used in conditional logic, a product ID compared as a discriminated-union tag)
- Any existing test fails after a fix
- TypeScript compile error introduced
- A scanner finding that doesn't match any of patterns A–F
- A change in shared packages (`@bytelyst/*`) that would break downstream
  consumers — needs ecosystem-wide validation
- Reaching a Tier boundary (Tier 2 → Tier 3 etc.) — pause for a status update,
  not for approval

### Continue conditions (don't stop)

- A repo has no findings remaining → move to next repo
- A pattern-match fix succeeds → commit and continue
- Scanner reports new false-positive category → refine scanner in `common_plat`,
  re-baseline, then continue

---

## 4. Out-of-scope (do NOT do during this campaign)

- Refactoring unrelated code
- Upgrading dependency versions
- Re-enabling CI workflows (separate workstream)
- Force-converting upstream repos (only `learning_ai_claw-code-oss` is upstream;
  it is excluded from the scanner via `.windsurf/workflows/repos.txt`)
- Changing test files except to update tests covering modified production code
- Adding new features
- Reformatting whitespace

---

## 5. Progress log

| Date | Tier | Action | Commit | Hex Δ | Total Δ |
|---|---|---|---|---:|---:|
| 2026-05-23 | 0 | Scanner build + initial scan | `4967b125` | 0 | baseline 2548 |
| 2026-05-23 | 0 | Scanner precision (var fallback, themeColor) | `14ab38e4`, `616e9738` | −564 false-positives | −905 |
| 2026-05-23 | 2a | talk2obsidian hex → token | `d20848a` | −1 | −1 |
| 2026-05-23 | 2a | local_memory_gpt hex → token | `a5def1c` | −1 | −1 |
| 2026-05-23 | 2a | trails hex → token | `10549e6` | −1 | −1 |
| 2026-05-23 | 2a | local_llms hex → token | `ca853f1` | −1 | −1 |
| 2026-05-23 | 2b | Scanner: backend/, tailwind, HTML entity exceptions | `d5d30ed9` | −47 false-positives | −47 |
| 2026-05-23 | 2b | jarvis_jr hex → token | `bf9e1c7` | −1 | −1 |
| 2026-05-23 | 2b | claw-cowork hex → tokens | `9017dd8` | −2 | −2 |
| 2026-05-23 | 1 | voice_ai_agent churn-alert PRODUCT_ID from product.json | `2281b4b` | −2 critical | −2 |
| 2026-05-23 | 1 | multimodal cosmos.ts fallback from product.json | `7d61713` | −1 critical | −1 |
| 2026-05-23 | 1 | Scanner: recognize TS literal-type constraints (ecosystem-phase\*) | (next commit) | −10 critical | −10 |

---

## 6. Open questions / decisions logged

- **Q1:** Should we touch `@bytelyst/ui` / `@bytelyst/auth-ui` / `@bytelyst/dashboard-shell`
  in this campaign, given they're shared across all products?
  - **Decision:** Yes (Tier 2). Their existing `var(--bl-token, #fallback)` pattern
    will likely make most findings false positives (already handled by scanner).
    Real findings will be targeted, small, and high-leverage.

- **Q2:** Should `mac_tooling` Python `print()` statements be flagged?
  - **Decision:** It depends on file role. CLI tools (`tools/cli.py`, `__main__.py`)
    legitimately print. Library code (`tools/api_server.py`, `tools/db_schema.py`)
    should use `logging`. Triage case-by-case during Tier 5.

- **Q3:** What about emojis in admin / dev-tool code paths?
  - **Decision:** Strict per AGENTS.md ("Never add emojis to code unless explicitly
    asked"). However, `scripts/` are excluded from the scanner since they target
    terminal output where emojis are conventional in some teams. For UI emojis
    (📊 📝 📄 etc. in dashboards), replace with `lucide-react` icons.