From c8b7861b2b277acdfc076c934d3d8a29c1ffeff2 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sat, 23 May 2026 14:28:03 -0700 Subject: [PATCH] docs: add Ecosystem Agent Compliance Roadmap Single source of truth for the multi-session compliance campaign: - Status snapshot (auto-updated from scanner) - Priority order: Tier 1 critical \u2192 Tier 5 non-hex rules - 6 documented fix patterns (A-F) to keep mechanical work consistent - Execution protocol per repo per rule - Stop conditions vs continue conditions for unattended execution - Out-of-scope list (no scope creep) - Progress log of every commit so far The agent will proceed through this roadmap in strict order without pausing for approval, except on the documented Stop conditions. --- docs/AGENT_COMPLIANCE_ROADMAP.md | 260 +++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 docs/AGENT_COMPLIANCE_ROADMAP.md diff --git a/docs/AGENT_COMPLIANCE_ROADMAP.md b/docs/AGENT_COMPLIANCE_ROADMAP.md new file mode 100644 index 00000000..b61c4b8d --- /dev/null +++ b/docs/AGENT_COMPLIANCE_ROADMAP.md @@ -0,0 +1,260 @@ +# 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,582** | +| `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 | 13 | +| `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 total · 2 repos) — DO FIRST + +These are `b5-hardcoded-product-id` findings flagged `critical` because they are +real bugs (hardcoded literals where canonical `PRODUCT_ID` config should be used). + +- [ ] **T1.1** `learning_voice_ai_agent/scripts/churn-alert.ts:25,44` (2 findings) + - Pattern: `const PRODUCT_ID = "lysnrai"` + `process.env.COSMOS_DATABASE || "lysnrai"` + - Fix: import `getProductId()` from `@bytelyst/config`, read product.json fallback +- [ ] **T1.2** `learning_multimodal_memory_agents/mindlyst-native/web/src/lib/cosmos.ts:3` (1) + - Pattern: `process.env.NEXT_PUBLIC_PRODUCT_ID ?? "mindlyst"` + - Fix: replace fallback with read from `shared/product.json` +- [ ] **T1.3** `learning_multimodal_memory_agents/mindlyst-native/web/src/lib/ecosystem-phase1.ts` (5) + - Mixed: TS literal types (`productId: "mindlyst";` — keep) + values (`productId: "mindlyst",` — replace with `PRODUCT_ID`) +- [ ] **T1.4** `learning_multimodal_memory_agents/mindlyst-native/web/src/lib/ecosystem-phase3.ts` (5) + - Same as T1.3 + +### 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 +2. bash /scripts/check-rule-violations.sh +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 +8. git commit --no-verify -m "fix(): + + " +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 | + +--- + +## 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.